From ce31ccaade3874233950e283b580007ea314f3aa Mon Sep 17 00:00:00 2001
From: fabrixxm <fabrix.xm@gmail.com>
Date: Wed, 12 Dec 2018 20:36:56 +0100
Subject: [PATCH] Add docs about storage backend

---
 doc/AddonStorageBackend.md | 202 +++++++++++++++++++++++++++++++++++++
 doc/Home.md                |   1 +
 doc/Settings.md            |  25 +++++
 doc/tools.md               |   3 +
 4 files changed, 231 insertions(+)
 create mode 100644 doc/AddonStorageBackend.md

diff --git a/doc/AddonStorageBackend.md b/doc/AddonStorageBackend.md
new file mode 100644
index 0000000000..d6ad9d37db
--- /dev/null
+++ b/doc/AddonStorageBackend.md
@@ -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");
+}
+
+
+
+
diff --git a/doc/Home.md b/doc/Home.md
index 5ca573c47b..03e2142570 100644
--- a/doc/Home.md
+++ b/doc/Home.md
@@ -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)
diff --git a/doc/Settings.md b/doc/Settings.md
index 4795a0402d..6eb3a5c440 100644
--- a/doc/Settings.md
+++ b/doc/Settings.md
@@ -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.
diff --git a/doc/tools.md b/doc/tools.md
index d068a2cc78..cb6aa1c3aa 100644
--- a/doc/tools.md
+++ b/doc/tools.md
@@ -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.