X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=doc%2FAddonStorageBackend.md;h=e54960252be4777350d381531a5514bc00c0f42e;hb=486328336f9d4239cf67a32f31ffd58609729f93;hp=17c3f0414077ee1dfb4d8a800427aea46372e39c;hpb=cb80108957f16011b5b7b1b8961da8cbd78d60c9;p=friendica.git

diff --git a/doc/AddonStorageBackend.md b/doc/AddonStorageBackend.md
index 17c3f04140..e54960252b 100644
--- a/doc/AddonStorageBackend.md
+++ b/doc/AddonStorageBackend.md
@@ -10,12 +10,12 @@ A storage backend is implemented as a class, and the plugin register the class t
 
 The class must live in `Friendica\Addon\youraddonname` namespace, where `youraddonname` the folder name of your addon.
 
-The class must implement `Friendica\Model\Storage\IStorage` interface. All method in the interface must be implemented:
+The class must implement `Friendica\Model\Storage\IWritableStorage` interface. All method in the interface must be implemented:
 
-namespace Friendica\Model\Storage;
+namespace Friendica\Model\IWritableStorage;
 
 ```php
-interface IStorage
+interface IWritableStorage
 {
 	public function get(string $reference);
 	public function put(string $data, string $reference = '');
@@ -52,7 +52,7 @@ The info array for each option is defined as:
 		'type',
 
 define the field used in form, and the type of data.
-one of 'checkbox', 'combobox', 'custom', 'datetime', 'input', 'intcheckbox', 'password', 'radio', 'richtext', 'select', 'select_raw', 'textarea', 'yesno'
+one of 'checkbox', 'combobox', 'custom', 'datetime', 'input', 'intcheckbox', 'password', 'radio', 'richtext', 'select', 'select_raw', 'textarea'
 
 		'label',
 
@@ -73,14 +73,13 @@ Optional. Depends on which 'type' this option is:
 - 'select': array `[ value => label ]` of choices
 - 'intcheckbox': value of input element
 - 'select_raw': prebuild html string of `<option >` tags
-- 'yesno': array `[ 'label no', 'label yes']`
 
 Each label should be translatable
 
 	];
 
 
-See doxygen documentation of `IStorage` interface for details about each method.
+See doxygen documentation of `IWritableStorage` interface for details about each method.
 
 ## Register a storage backend class
 
@@ -106,8 +105,9 @@ Each new Storage class should be added to the test-environment at [Storage Tests
 Add a new test class which's naming convention is `StorageClassTest`, which extend the `StorageTest` in the same directory.
 
 Override the two necessary instances:
+
 ```php
-use Friendica\Model\Storage\IStorage;
+use Friendica\Model\Storage\IWritableStorage;
 
 abstract class StorageTest 
 {
@@ -115,13 +115,48 @@ abstract class StorageTest
 	abstract protected function getInstance();
 
 	// Assertion for the option array you return for your new StorageClass
-	abstract protected function assertOption(IStorage $storage);
+	abstract protected function assertOption(IWritableStorage $storage);
+} 
+```
+
+## Exception handling
+
+There are two intended types of exceptions for storages
+
+### `ReferenceStorageExecption`
+
+This storage exception should be used in case the caller tries to use an invalid references.
+This could happen in case the caller tries to delete or update an unknown reference.
+The implementation of the storage backend must not ignore invalid references.
+
+Avoid throwing the common `StorageExecption` instead of the `ReferenceStorageException` at this particular situation!
+
+### `StorageException`
+
+This is the common exception in case unexpected errors happen using the storage backend.
+If there's a predecessor to this exception (e.g. you caught an exception and are throwing this execption), you should add the predecessor for transparency reasons.
+
+Example:
+
+```php
+use Friendica\Model\Storage\IWritableStorage;
+
+class ExampleStorage implements IWritableStorage 
+{
+	public function get(string $reference) : string
+	{
+		try {
+			throw new Exception('a real bad exception');
+		} catch (Exception $exception) {
+			throw new \Friendica\Model\Storage\StorageException(sprintf('The Example Storage throws an exception for reference %s', $reference), 500, $exception);
+		}
+	}
 } 
 ```
 
 ## Example
 
-Here an hypotetical addon which register an unusefull storage backend.
+Here an hypotetical addon which register a useless storage backend.
 Let's call it `samplestorage`.
 
 This backend will discard all data we try to save and will return always the same image when we ask for some data.
@@ -134,12 +169,12 @@ The file will be `addon/samplestorage/SampleStorageBackend.php`:
 <?php
 namespace Friendica\Addon\samplestorage;
 
-use Friendica\Model\Storage\IStorage;
+use Friendica\Model\Storage\IWritableStorage;
 
 use Friendica\Core\Config\IConfig;
 use Friendica\Core\L10n;
 
-class SampleStorageBackend implements IStorage
+class SampleStorageBackend implements IWritableStorage
 {
 	const NAME = 'Sample Storage';
 
@@ -271,7 +306,7 @@ function samplestorage_storage_instance(\Friendica\App $a, array $data)
 **Theoretically - until tests for Addons are enabled too - create a test class with the name `addon/tests/SampleStorageTest.php`:
 
 ```php
-use Friendica\Model\Storage\IStorage;
+use Friendica\Model\Storage\IWritableStorage;
 use Friendica\Test\src\Model\Storage\StorageTest;
 
 class SampleStorageTest extends StorageTest 
@@ -285,7 +320,7 @@ class SampleStorageTest extends StorageTest
 	}
 
 	// Assertion for the option array you return for your new StorageClass
-	protected function assertOption(IStorage $storage)
+	protected function assertOption(IWritableStorage $storage)
 	{
 		$this->assertEquals([
 			'filename' => [