Friendica Communications Platform (please note that this is a clone of the repository at github, issues are handled there) https://friendi.ca
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

AddonStorageBackend.md 5.5 KiB

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