bitPickups/friendica_2019-12_sharedHosting_hotFix
1
1
Fork 0
Code Pull requests Activity

Add docs about storage backend

Browse source
This commit is contained in:
fabrixxm 2018-12-12 20:36:56 +01:00 committed by Hypolite Petovan
parent 2f935a1fbf
commit ce31ccaade
4 changed files with 231 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

202
doc/AddonStorageBackend.md Normal file
View file

@ -0,0 +1,202 @@
Friendica Storage Backend Addon development
===========================================
* [Home](help)
Storage backends can be added via addons.
A storage backend is implemented as a class, and the plugin register the class to make it avaiable to the system.
## The Storage Backend Class
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:
namespace Friendica\Model\Storage;
interface IStorage
{
public static function get($ref);
public static function put($data, $ref = "");
public static function delete($ref);
public static function getOptions();
public static function saveOptions($data);
}
- `get($ref)` returns data pointed by `$ref`
- `put($data, $ref)` saves data in `$data` to position `$ref`, or a new position if `$ref` is empty.
- `delete($ref)` delete data pointed by `$ref`
Each storage backend can have options the admin can set in admin page.
- `getOptions()` returns an array with details about each option to build the interface.
- `saveOptions($data)` get `$data` from admin page, validate it and save it.
The array returned by `getOptions()` is defined as:
[
'option1name' => [ ..info.. ],
'option2name' => [ ..info.. ],
...
]
An empty array can be returned if backend doesn't have any options.
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'
'label',
Translatable label of the field. This label will be shown in admin page
value,
Current value of the option
'help text',
Translatable description for the field. Will be shown in admin page
extra data
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.
## Register a storage backend class
Each backend must be registered in the system when the plugin is installed, to be aviable.
`Friendica\Core\StorageManager::register($name, $class)` is used to register the backend class.
The `$name` must be univocal and will be shown to admin.
When the plugin is uninstalled, registered backends must be unregistered using
`Friendica\Core\StorageManager::unregister($class)`.
## Example
Here an hypotetical addon which register an unusefull 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.
The image returned can be set by the administrator in admin page.
First, the backend class.
The file will be `addon/samplestorage/SampleStorageBackend.php`:
```php
<?php
namespace Friendica\Addon\samplestorage;
use Friendica\Model\Storage\IStorage;
use Friendica\Core\Config;
use Friendica\Core\L10n;
class SampleStorageBackend implements IStorage
{
public static function get($ref)
{
// we return alwais the same image data. Which file we load is defined by
// a config key
$filename = Config::get("storage", "samplestorage", "sample.jpg");
return file_get_contents($filename);
}
public static function put($data, $ref = "")
{
if ($ref === "") {
$ref = "sample";
}
// we don't save $data !
return $ref;
}
public static function delete($ref)
{
// we pretend to delete the data
return true;
}
public static function getOptions()
{
$filename = Config::get("storage", "samplestorage", "sample.jpg");
return [
"filename" => [
"input", // will use a simple text input
L10n::t("The file to return"), // the label
$filename, // the current value
L10n::t("Enter the path to a file"), // the help text
// no extra data for "input" type..
];
}
public static function saveOptions($data)
{
// the keys in $data are the same keys we defined in getOptions()
$newfilename = trim($data["filename"]);
// this function should always validate the data.
// in this example we check if file exists
if (!file_exists($newfilename)) {
// in case of error we return an array with
// ["optionname" => "error message"]
return ["filename" => "The file doesn't exists"];
}
Config::set("storage", "samplestorage", $newfilename);
// no errors, return empty array
return [];
}
}
```
Now the plugin main file. Here we register and unregister the backend class.
The file is `addon/samplestorage/samplestorage.php`
```php
<?php
/**
* Name: Sample Storage Addon
* Description: A sample addon which implements an unusefull storage backend
* Version: 1.0.0
* Author: Alice <https://alice.social/~alice>
*/
use Friendica\Core\StorageManager;
use Friendica\Addon\samplestorage\SampleStorageBackend;
function samplestorage_install()
{
// on addon install, we register our class with name "Sample Storage".
// note: we use `::class` property, which returns full class name as string
// this save us the problem of correctly escape backslashes in class name
StorageManager::register("Sample Storage", SampleStorageBackend::class);
}
function samplestorage_unistall()
{
// when the plugin is uninstalled, we unregister the backend.
StorageManager::unregister("Sample Storage");
}

1
doc/Home.md
View file

@ -47,6 +47,7 @@ Friendica Documentation and Resources
* [Addon Development](help/Addons)
* [Theme Development](help/themes)
* [Smarty 3 Templates](help/smarty3-templates)
* [Storage backend addon](help/AddonStorageBackend)
* How To
* [Translate Friendica](help/translations)
* [Use Composer](help/Composer)

25
doc/Settings.md
View file

@ -101,6 +101,31 @@ Default is false.
### File upload
#### File storage backend
Set the backend used by Friendica to store uploaded file data.
Two storage backends are avaiable with Friendica:
- **Database** : Data is stored in a dedicated table in database (`storage`)
- **Filesystem** : Data is stored as file on the filesystem.
More storage backends can be avaiable from third-party addons.
Default value is 'None': it's the legacy way used to store data directly in database.
Existing data can be moved to the current active backend using the ['storage move' console command](help/tools)
If selected backend has configurable options, new fields are shown here.
##### Filesystem: Storage base path
The base path where Filesystem storage backend saves data.
For maximum security, this path should be outside the folder tree served by the web server: this way files can't be downloaded bypassing the privacy checks.
Default value is `storage`, that is the `storage` folder in Friendica code root folder.
#### Maximum Image Size
Maximum size in bytes of uploaded images.

3
doc/tools.md
View file

@ -9,6 +9,7 @@ Friendica Tools
Friendica has a build in command console you can find in the *bin* directory.
The console provides the following commands:
* cache: Manage node cache
* config: Edit site config
* createdoxygen: Generate Doxygen headers
* dbstructure: Do database updates
@ -24,6 +25,8 @@ The console provides the following commands:
* php2po: Generate a messages.po file from a strings.php file
* po2php: Generate a strings.php file from a messages.po file
* typo: Checks for parse errors in Friendica files
* postupdate: Execute pending post update scripts (can last days)
* storage: Manage storage backend
Please consult *bin/console help* on the command line interface of your server for details about the commands.