doc/AddonStorageBackend.md

   1 Friendica Storage Backend Addon development
   2 ===========================================
   3
   4 * [Home](help)
   5
   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.
   8
   9 ## The Storage Backend Class
  10
  11 The class must live in `Friendica\Addon\youraddonname` namespace, where `youraddonname` the folder name of your addon.
  12
  13 The class must implement `Friendica\Model\Storage\IStorage` interface. All method in the interface must be implemented:
  14
  15 namespace Friendica\Model\Storage;
  16
  17 ```php
  18 interface IStorage
  19 {
  20         public static function get($ref);
  21         public static function put($data, $ref = "");
  22         public static function delete($ref);
  23         public static function getOptions();
  24         public static function saveOptions($data);
  25 }
  26 ```
  27
  28 - `get($ref)` returns data pointed by `$ref`
  29 - `put($data, $ref)` saves data in `$data` to position `$ref`, or a new position if `$ref` is empty.
  30 - `delete($ref)` delete data pointed by `$ref`
  31
  32 Each storage backend can have options the admin can set in admin page.
  33
  34 - `getOptions()` returns an array with details about each option to build the interface.
  35 - `saveOptions($data)` get `$data` from admin page, validate it and save it.
  36
  37 The array returned by `getOptions()` is defined as:
  38
  39         [
  40                 'option1name' => [ ..info.. ],
  41                 'option2name' => [ ..info.. ],
  42                 ...
  43         ]
  44
  45 An empty array can be returned if backend doesn't have any options.
  46
  47 The info array for each option is defined as:
  48
  49         [
  50                 'type',
  51
  52 define the field used in form, and the type of data.
  53 one of 'checkbox', 'combobox', 'custom', 'datetime', 'input', 'intcheckbox', 'password', 'radio', 'richtext', 'select', 'select_raw', 'textarea', 'yesno'
  54
  55                 'label',
  56
  57 Translatable label of the field. This label will be shown in admin page
  58
  59                 value,
  60
  61 Current value of the option
  62
  63                 'help text',
  64
  65 Translatable description for the field. Will be shown in admin page
  66
  67                 extra data
  68
  69 Optional. Depends on which 'type' this option is:
  70
  71 - 'select': array `[ value => label ]` of choices
  72 - 'intcheckbox': value of input element
  73 - 'select_raw': prebuild html string of `<option >` tags
  74 - 'yesno': array `[ 'label no', 'label yes']`
  75
  76 Each label should be translatable
  77
  78         ];
  79
  80
  81 See doxygen documentation of `IStorage` interface for details about each method.
  82
  83 ## Register a storage backend class
  84
  85 Each backend must be registered in the system when the plugin is installed, to be aviable.
  86
  87 `Friendica\Core\StorageManager::register($name, $class)` is used to register the backend class.
  88 The `$name` must be univocal and will be shown to admin.
  89
  90 When the plugin is uninstalled, registered backends must be unregistered using
  91 `Friendica\Core\StorageManager::unregister($class)`.
  92
  93 ## Example
  94
  95 Here an hypotetical addon which register an unusefull storage backend.
  96 Let's call it `samplestorage`.
  97
  98 This backend will discard all data we try to save and will return always the same image when we ask for some data.
  99 The image returned can be set by the administrator in admin page.
 100
 101 First, the backend class.
 102 The file will be `addon/samplestorage/SampleStorageBackend.php`:
 103
 104 ```php
 105 <?php
 106 namespace Friendica\Addon\samplestorage;
 107
 108 use Friendica\Model\Storage\IStorage;
 109
 110 use Friendica\Core\Config;
 111 use Friendica\Core\L10n;
 112
 113 class SampleStorageBackend implements IStorage
 114 {
 115         public static function get($ref)
 116         {
 117                 // we return alwais the same image data. Which file we load is defined by
 118                 // a config key
 119                 $filename = Config::get("storage", "samplestorage", "sample.jpg");
 120                 return file_get_contents($filename);
 121         }
 122
 123         public static function put($data, $ref = "")
 124         {
 125                 if ($ref === "") {
 126                         $ref = "sample";
 127                 }
 128                 // we don't save $data !
 129                 return $ref;
 130         }
 131
 132         public static function delete($ref)
 133         {
 134                 // we pretend to delete the data
 135                 return true;
 136         }
 137
 138         public static function getOptions()
 139         {
 140                 $filename = Config::get("storage", "samplestorage", "sample.jpg");
 141                 return [
 142                         "filename" => [
 143                                 "input",        // will use a simple text input
 144                                 L10n::t("The file to return"),  // the label
 145                                 $filename,      // the current value
 146                                 L10n::t("Enter the path to a file"), // the help text
 147                                 // no extra data for "input" type..
 148                 ];
 149         }
 150
 151         public static function saveOptions($data)
 152         {
 153                 // the keys in $data are the same keys we defined in getOptions()
 154                 $newfilename = trim($data["filename"]);
 155
 156                 // this function should always validate the data.
 157                 // in this example we check if file exists
 158                 if (!file_exists($newfilename)) {
 159                         // in case of error we return an array with
 160                         // ["optionname" => "error message"]
 161                         return ["filename" => "The file doesn't exists"];
 162                 }
 163
 164                 Config::set("storage", "samplestorage", $newfilename);
 165
 166                 // no errors, return empty array
 167                 return [];
 168         }
 169 }
 170 ```
 171
 172 Now the plugin main file. Here we register and unregister the backend class.
 173
 174 The file is `addon/samplestorage/samplestorage.php`
 175
 176 ```php
 177 <?php
 178 /**
 179  * Name: Sample Storage Addon
 180  * Description: A sample addon which implements an unusefull storage backend
 181  * Version: 1.0.0
 182  * Author: Alice <https://alice.social/~alice>
 183  */
 184
 185 use Friendica\Addon\samplestorage\SampleStorageBackend;
 186 use Friendica\DI;
 187
 188 function samplestorage_install()
 189 {
 190         // on addon install, we register our class with name "Sample Storage".
 191         // note: we use `::class` property, which returns full class name as string
 192         // this save us the problem of correctly escape backslashes in class name
 193         DI::facStorage()->register("Sample Storage", SampleStorageBackend::class);
 194 }
 195
 196 function samplestorage_unistall()
 197 {
 198         // when the plugin is uninstalled, we unregister the backend.
 199         DI::facStorage()->unregister("Sample Storage");
 200 }
 201 ```
 202
 203
 204