1 Friendica Storage Backend Addon development
2 ===========================================
6 Storage backends can be added via addons.
7 A storage backend is implemented as a class, and the plugin register the class to make it avaiable to the system.
9 ## The Storage Backend Class
11 The class must live in `Friendica\Addon\youraddonname` namespace, where `youraddonname` the folder name of your addon.
13 The class must implement `Friendica\Model\Storage\IStorage` interface. All method in the interface must be implemented:
15 namespace Friendica\Model\Storage;
20 public function get(string $reference);
21 public function put(string $data, string $reference = '');
22 public function delete(string $reference);
23 public function getOptions();
24 public function saveOptions(array $data);
25 public function __toString();
29 - `get(string $reference)` returns data pointed by `$reference`
30 - `put(string $data, string $reference)` saves data in `$data` to position `$reference`, or a new position if `$reference` is empty.
31 - `delete(string $reference)` delete data pointed by `$reference`
33 Each storage backend can have options the admin can set in admin page.
35 - `getOptions()` returns an array with details about each option to build the interface.
36 - `saveOptions(array $data)` get `$data` from admin page, validate it and save it.
38 The array returned by `getOptions()` is defined as:
41 'option1name' => [ ..info.. ],
42 'option2name' => [ ..info.. ],
46 An empty array can be returned if backend doesn't have any options.
48 The info array for each option is defined as:
53 define the field used in form, and the type of data.
54 one of 'checkbox', 'combobox', 'custom', 'datetime', 'input', 'intcheckbox', 'password', 'radio', 'richtext', 'select', 'select_raw', 'textarea', 'yesno'
58 Translatable label of the field. This label will be shown in admin page
62 Current value of the option
66 Translatable description for the field. Will be shown in admin page
70 Optional. Depends on which 'type' this option is:
72 - 'select': array `[ value => label ]` of choices
73 - 'intcheckbox': value of input element
74 - 'select_raw': prebuild html string of `<option >` tags
75 - 'yesno': array `[ 'label no', 'label yes']`
77 Each label should be translatable
82 See doxygen documentation of `IStorage` interface for details about each method.
84 ## Register a storage backend class
86 Each backend must be registered in the system when the plugin is installed, to be aviable.
88 `DI::facStorage()->register(string $name, string $class)` is used to register the backend class.
89 The `$name` must be univocal and will be shown to admin.
91 When the plugin is uninstalled, registered backends must be unregistered using
92 `DI::facStorage()->unregister(string $name)`.
96 **Currently testing is limited to core Friendica only, this shows theoretically how tests should work in the future**
98 Each new Storage class should be added to the test-environment at [Storage Tests](https://github.com/friendica/friendica/tree/develop/tests/src/Model/Storage/).
100 Add a new test class which's naming convention is `StorageClassTest`, which extend the `StorageTest` in the same directory.
102 Override the two necessary instances:
104 use Friendica\Model\Storage\IStorage;
106 abstract class StorageTest
108 // returns an instance of your newly created storage class
109 abstract protected function getInstance();
111 // Assertion for the option array you return for your new StorageClass
112 abstract protected function assertOption(IStorage $storage);
118 Here an hypotetical addon which register an unusefull storage backend.
119 Let's call it `samplestorage`.
121 This backend will discard all data we try to save and will return always the same image when we ask for some data.
122 The image returned can be set by the administrator in admin page.
124 First, the backend class.
125 The file will be `addon/samplestorage/SampleStorageBackend.php`:
129 namespace Friendica\Addon\samplestorage;
131 use Friendica\Model\Storage\IStorage;
133 use Friendica\Core\Config;
134 use Friendica\Core\L10n;
136 class SampleStorageBackend implements IStorage
138 const NAME = 'Sample Storage';
140 /** @var Config\IConfiguration */
142 /** @var L10n\L10n */
146 * SampleStorageBackend constructor.
147 * @param Config\IConfiguration $config The configuration of Friendica
149 * You can add here every dynamic class as dependency you like and add them to a private field
150 * Friendica automatically creates these classes and passes them as argument to the constructor
152 public function __construct(Config\IConfiguration $config, L10n\L10n $l10n)
154 $this->config = $config;
158 public function get(string $reference)
160 // we return always the same image data. Which file we load is defined by
162 $filename = $this->config->get('storage', 'samplestorage', 'sample.jpg');
163 return file_get_contents($filename);
166 public function put(string $data, string $reference = '')
168 if ($reference === '') {
169 $reference = 'sample';
171 // we don't save $data !
175 public function delete(string $reference)
177 // we pretend to delete the data
181 public function getOptions()
183 $filename = $this->config->get('storage', 'samplestorage', 'sample.jpg');
186 'input', // will use a simple text input
187 $this->l10n->t('The file to return'), // the label
188 $filename, // the current value
189 $this->l10n->t('Enter the path to a file'), // the help text
190 // no extra data for 'input' type..
195 public function saveOptions(array $data)
197 // the keys in $data are the same keys we defined in getOptions()
198 $newfilename = trim($data['filename']);
200 // this function should always validate the data.
201 // in this example we check if file exists
202 if (!file_exists($newfilename)) {
203 // in case of error we return an array with
204 // ['optionname' => 'error message']
205 return ['filename' => 'The file doesn\'t exists'];
208 $this->config->set('storage', 'samplestorage', $newfilename);
210 // no errors, return empty array
214 public function __toString()
219 public static function getName()
226 Now the plugin main file. Here we register and unregister the backend class.
228 The file is `addon/samplestorage/samplestorage.php`
233 * Name: Sample Storage Addon
234 * Description: A sample addon which implements an unusefull storage backend
236 * Author: Alice <https://alice.social/~alice>
239 use Friendica\Addon\samplestorage\SampleStorageBackend;
242 function samplestorage_install()
244 // on addon install, we register our class with name "Sample Storage".
245 // note: we use `::class` property, which returns full class name as string
246 // this save us the problem of correctly escape backslashes in class name
247 DI::facStorage()->register(SampleStorageBackend::class);
250 function samplestorage_unistall()
252 // when the plugin is uninstalled, we unregister the backend.
253 DI::facStorage()->unregister(SampleStorageBackend::class);
257 **Theoretically - until tests for Addons are enabled too - create a test class with the name `addon/tests/SampleStorageTest.php`:
260 use Friendica\Model\Storage\IStorage;
261 use Friendica\Test\src\Model\Storage\StorageTest;
263 class SampleStorageTest extends StorageTest
265 // returns an instance of your newly created storage class
266 protected function getInstance()
268 // create a new SampleStorageBackend instance with all it's dependencies
269 // Have a look at DatabaseStorageTest or FilesystemStorageTest for further insights
270 return new SampleStorageBackend();
273 // Assertion for the option array you return for your new StorageClass
274 protected function assertOption(IStorage $storage)
276 $this->assertEquals([
279 'The file to return',
281 'Enter the path to a file'
283 ], $storage->getOptions());