Merge pull request #2599 from FreshRSS/dev1.15.0

FreshRSS 1.15

2 files changed, 146 insertions, 104 deletions

diff --git a/docs/en/developers/01_First_steps.md b/docs/en/developers/01_First_steps.md
index adca4495b..28c249be4 100644
--- a/docs/en/developers/01_First_steps.md
+++ b/docs/en/developers/01_First_steps.md
@@ -1,6 +1,59 @@
-# Environment configuration
+# Environment configuration (Docker)
 
-**TODO**
+FreshRSS is built with PHP and uses a homemade framework, Minz. The dependencies are directly included in the source code, so you don't need Composer.
+
+There are various ways to configure your development environment. The easiest and most supported method is based on Docker, which is the solution documented below. If you already have a working PHP environment, you probably don't need it.
+
+We assume here that you use a GNU/Linux distribution, capable of running Docker. Otherwise, you'll have to adapt the commands accordingly.
+
+The commands that follow have to be executed in a console. They start by `$` when commands need to be executed as normal user, and by `#` when they need to be executed as root user. You don't have to type these characters. A path may be indicated before these characters to help you identify where they need to be executed. For instance, `app$ echo 'Hello World'` indicates that you have to execute `echo` command in the `app/` directory.
+
+First, you need to install [Docker](https://docs.docker.com/install/linux/docker-ce/ubuntu/).
+
+Once you're done, clone the repository with:
+
+```console
+$ git clone https://github.com/FreshRSS/FreshRSS.git
+$ cd FreshRSS
+```
+
+Note that, if you want to contribute, you have to fork the repository first and clone your fork instead of the "root" one. Adapt the commands in consequence.
+
+Then, the only command you need to know is the following:
+
+```console
+$ make start
+```
+
+This might take some time while Docker downloads the image. If your user isn't in the `docker` group, you'll need to prepend the command with `sudo`.
+
+**You can now access FreshRSS at [http://localhost:8080](http://localhost:8080).** Just follow the install process and select the SQLite database.
+
+You can stop the containers by typing <kbd>Control</kbd> + <kbd>c</kbd> or with the following command, in another terminal:
+
+```console
+$ make stop
+```
+
+If you're interested in the configuration, the `make` commands are defined in the [`Makefile`](/Makefile).
+
+If you need to use a different tag image (default is `dev-alpine`), you can set the `TAG` environment variable:
+
+```console
+$ TAG=dev-arm make start
+```
+
+You can find the full list of available tags [on the Docker hub](https://hub.docker.com/r/freshrss/freshrss/tags).
+
+You might want to rebuild the Docker image locally. You can do it with:
+
+```console
+$ make build
+$ # or
+$ TAG=dev-arm make build
+```
+
+The `TAG` variable can be anything (e.g. `dev-local`). You can target a specific architecture by adding `-alpine` or `-arm` at the end of the tag (e.g. `dev-local-arm`).
 
 # Project architecture
 
@@ -8,7 +61,7 @@
 
 # Extensions
 
-If you want to create your own FreshRSS extension, take a look at the [extension documentation](03_Backend/05_Extensions.md).  
+If you want to create your own FreshRSS extension, take a look at the [extension documentation](03_Backend/05_Extensions.md).
 
 # Coding style
 
@@ -57,7 +110,7 @@ There is a space before and after every operator.
 
 ```php
 if ($a == 10) {
-    // do something
+	// do something
 }
 
 echo $a ? 1 : 0;
@@ -69,11 +122,11 @@ There is no spaces in the brackets. There is no space before the opening bracket
 
 ```php
 if ($a == 10) {
-    // do something
+	// do something
 }
 
 if ((int)$a == 10) {
-    // do something
+	// do something
 }
 ```
 
@@ -84,16 +137,16 @@ It happens most of the time in Javascript files. When there is chained functions
 ```javascript
 // First instruction
 shortcut.add(shortcuts.mark_read, function () {
-        //...
-    }, {
-        'disable_in_input': true
-    });
+		//...
+	}, {
+		'disable_in_input': true
+	});
 // Second instruction
 shortcut.add("shift+" + shortcuts.mark_read, function () {
-        //...
-    }, {
-        'disable_in_input': true
-    });
+		//...
+	}, {
+		'disable_in_input': true
+	});
 ```
 
 ## Line length
@@ -105,7 +158,7 @@ With functions, parameters can be declared on different lines.
 ```php
 function my_function($param_1, $param_2,
                      $param_3, $param_4) {
-    // do something
+	// do something
 }
 ```
 
@@ -120,7 +173,7 @@ They must follow the "snake case" convention.
 ```php
 // a function
 function function_name() {
-    // do something
+	// do something
 }
 // a variable
 $variable_name;
@@ -132,7 +185,7 @@ They must follow the "lower camel case" convention.
 
 ```php
 private function methodName() {
-    // do something
+	// do something
 }
 ```
 
@@ -148,26 +201,9 @@ abstract class ClassName {}
 
 Files must be encoded with UTF-8 character set.
 
-## PHP 5.3 compatibility
-
-Do not get an array item directly from a function or a method. Use a variable.
-
-```php
-// code with PHP 5.3 compatibility
-$my_variable = function_returning_an_array();
-echo $my_variable[0];
-// code without PHP 5.3 compatibility
-echo function_returning_an_array()[0];
-```
-
-Do not use short array declaration.
+## PHP compatibility
 
-```php
-// code with PHP 5.3 compatibility
-$variable = array();
-// code without PHP 5.3 compatibility
-$variable = [];
-```
+Ensure that your code is working with a PHP version as old as what FreshRSS officially supports.
 
 ## Miscellaneous
 
@@ -177,7 +213,7 @@ They must be at the end of the line if a condition runs on more than one line.
 ```php
 if ($a == 10 ||
     $a == 20) {
-    // do something
+	// do something
 }
 ```
 
@@ -190,9 +226,9 @@ If the file contains only PHP code, the PHP closing tag must be omitted.
 If an array declaration runs on more than one line, each element must be followed by a comma even the last one.
 
 ```php
-$variable = array(
-    "value 1",
-    "value 2",
-    "value 3",
-);
+$variable = [
+	"value 1",
+	"value 2",
+	"value 3",
+];
 ```
diff --git a/docs/en/developers/03_Backend/05_Extensions.md b/docs/en/developers/03_Backend/05_Extensions.md
index ae304f6e0..4610e4b90 100644
--- a/docs/en/developers/03_Backend/05_Extensions.md
+++ b/docs/en/developers/03_Backend/05_Extensions.md
@@ -48,13 +48,13 @@ Code example:
 <?php
 
 class FreshRSS_hello_Controller extends Minz_ActionController {
-    public function indexAction() {
-        $this->view->a_variable = 'FooBar';
-    }
+	public function indexAction() {
+		$this->view->a_variable = 'FooBar';
+	}
 
-    public function worldAction() {
-        $this->view->a_variable = 'Hello World!';
-    }
+	public function worldAction() {
+		$this->view->a_variable = 'Hello World!';
+	}
 }
 
 ?>
@@ -74,7 +74,7 @@ As explained above, the views consist of HTML mixed with PHP. Code example:
 
 ```html
 <p>
-    This is a parameter passed from the controller: <?php echo $this->a_variable; ?>
+	This is a parameter passed from the controller: <?= $this->a_variable ?>
 </p>
 ```
 
@@ -119,7 +119,7 @@ To take full advantage of the Minz routing system, it is strongly discouraged to
 
 ```html
 <p>
-    Go to page <a href="http://example.com?c=hello&amp;a=world">Hello world</a>!
+	Go to page <a href="http://example.com?c=hello&amp;a=world">Hello world</a>!
 </p>
 ```
 
@@ -130,13 +130,13 @@ So use the `Minz_Url` class and its `display()` method instead. `Minz_Url::displ
 ```php
 <?php
 
-$url_array = array(
-    'c' => 'hello',
-    'a' => 'world',
-    'params' => array(
-        'foo' => 'bar',
-    )
-);
+$url_array = [
+	'c' => 'hello',
+	'a' => 'world',
+	'params' => [
+		'foo' => 'bar',
+	],
+];
 
 // Show something like .?c=hello&amp;a=world&amp;foo=bar
 echo Minz_Url::display($url_array);
@@ -166,10 +166,10 @@ Code example:
 ```php
 <?php
 
-$url_array = array(
-    'c' => 'hello',
-    'a' => 'world'
-);
+$url_array = [
+	'c' => 'hello',
+	'a' => 'world',
+];
 
 // Tells Minz to redirect the user to the hello / world page.
 // Note that this is a redirection in the Minz sense of the term, not a redirection that the browser will have to manage (HTTP code 301 or 302)
@@ -188,10 +188,10 @@ It is very common to want display a message to the user while performing a redir
 ```php
 <?php
 
-$url_array = array(
-    'c' => 'hello',
-    'a' => 'world'
-);
+$url_array = [
+	'c' => 'hello',
+	'a' => 'world',
+];
 $feedback_good = 'Tout s\'est bien passé !';
 $feedback_bad = 'Oups, quelque chose n\'a pas marché.';
 
@@ -226,18 +226,18 @@ The translation files are quite simple: it is only a matter of returning a PHP t
 <?php
 
 return array(
-    'action' => array(
-        'actualize' => 'Actualiser',
-        'back_to_rss_feeds' => '← Retour à vos flux RSS',
-        'cancel' => 'Annuler',
-        'create' => 'Créer',
-        'disable' => 'Désactiver',
-    ),
-    'freshrss' => array(
-        '_' => 'FreshRSS',
-        'about' => 'À propos de FreshRSS',
-    ),
-);
+	'action' => [
+		'actualize' => 'Actualiser',
+		'back_to_rss_feeds' => '← Retour à vos flux RSS',
+		'cancel' => 'Annuler',
+		'create' => 'Créer',
+		'disable' => 'Désactiver',
+	),
+	'freshrss' => array(
+		'_' => 'FreshRSS',
+		'about' => 'À propos de FreshRSS',
+	),
+];
 
 ?>
 ```
@@ -247,9 +247,9 @@ Code example:
 
 ```html
 <p>
-    <a href="<?php echo _url('index', 'index'); ?>">
-        <?php echo _t('gen.action.back_to_rss_feeds'); ?>
-    </a>
+	<a href="<?= _url('index', 'index') ?>">
+		<?= _t('gen.action.back_to_rss_feeds') ?>
+	</a>
 </p>
 ```
 
@@ -267,8 +267,8 @@ An extension allows you to add functionality easily to FreshRSS without having t
 
 ### Basic files and folders
 
-The first thing to note is that **all** extensions **must** be located in the `extensions` directory, at the base of the FreshRSS tree. 
-An extension is a directory containing a set of mandatory (and optional) files and subdirectories. 
+The first thing to note is that **all** extensions **must** be located in the `extensions` directory, at the base of the FreshRSS tree.
+An extension is a directory containing a set of mandatory (and optional) files and subdirectories.
 The convention requires that the main directory name be preceded by an "x" to indicate that it is not an extension included by default in FreshRSS.
 
 The main directory of an extension must contain at least two **mandatory** files:
@@ -276,16 +276,16 @@ The main directory of an extension must contain at least two **mandatory** files
 - A `metadata.json` file that contains a description of the extension. This file is written in JSON.
 - An `extension.php` file containing the entry point of the extension (which is a class that inherits Minz_Extension).
 
-Please note that there is a not a required link between the directory name of the extension and the name of the class inside `extension.php`, 
-but you should follow our best practice:  
+Please note that there is a not a required link between the directory name of the extension and the name of the class inside `extension.php`,
+but you should follow our best practice:
 If you want to write a `HelloWorld` extension, the directory name should be `xExtension-HelloWorld` and the base class name `HelloWorldExtension`.
 
 In the file `freshrss/extensions/xExtension-HelloWorld/extension.php` you need the structure:
 ```html
 class HelloWorldExtension extends Minz_Extension {
-    public function init() {
-        // your code here
-    }
+	public function init() {
+		// your code here
+	}
 }
 ```
 There is an example HelloWorld extension that you can download from [our GitHub repo](https://github.com/FreshRSS/xExtension-HelloWorld).
@@ -315,14 +315,14 @@ Only the `name` and` entrypoint` fields are required.
 
 ### Choose between « system » or « user »
 
-A __user__ extension can be enabled by some users and not by others (typically for user preferences). 
+A __user__ extension can be enabled by some users and not by others (typically for user preferences).
 
 A __system__ extension in comparison is enabled for every account.
 
 ### Writing your own extension.php
 
-This file is the entry point of your extension. It must contain a specific class to function. 
-As mentioned above, the name of the class must be your `entrypoint` suffixed by` Extension` (`HelloWorldExtension` for example). 
+This file is the entry point of your extension. It must contain a specific class to function.
+As mentioned above, the name of the class must be your `entrypoint` suffixed by` Extension` (`HelloWorldExtension` for example).
 In addition, this class must be inherited from the `Minz_Extension` class to benefit from extensions-specific methods.
 
 Your class will benefit from four methods to redefine:
@@ -351,25 +351,31 @@ You can register at the FreshRSS event system in an extensions `init()` method,
 ```html
 class HelloWorldExtension extends Minz_Extension
 {
-    public function init() {
-        $this->registerHook('entry_before_display', array($this, 'renderEntry'));
-    }
-    public function renderEntry($entry) {
-        $entry->_content('<h1>Hello World</h1>' . $entry->content());
-        return $entry;
-    }
-}    
+	public function init() {
+		$this->registerHook('entry_before_display', array($this, 'renderEntry'));
+	}
+	public function renderEntry($entry) {
+		$entry->_content('<h1>Hello World</h1>' . $entry->content());
+		return $entry;
+	}
+}
 ```
+
 The following events are available:
 
-- `entry_before_display` (`function($entry) -> Entry | null`) : will be executed every time an entry is rendered. The entry itself (instance of FreshRSS_Entry) will be passed as parameter. 
-- `entry_before_insert` (`function($entry) -> Entry | null`) : will be executed when a feed is refreshed and new entries will be imported into the database. The new entry (instance of FreshRSS_Entry) will be passed as parameter. 
-- `feed_before_insert` (`function($feed) -> Feed | null`) : will be executed when a new feed is imported into the database. The new feed (instance of FreshRSS_Feed) will be passed as parameter. 
-- `post_update` (`function(none) -> none`) : **TODO** add documentation
-- `simplepie_before_init` (`function($simplePie, $feed) -> none`) : **TODO** add documentation
+- `entry_before_display` (`function($entry) -> Entry | null`): will be executed every time an entry is rendered. The entry itself (instance of FreshRSS\_Entry) will be passed as parameter.
+- `entry_before_insert` (`function($entry) -> Entry | null`): will be executed when a feed is refreshed and new entries will be imported into the database. The new entry (instance of FreshRSS\_Entry) will be passed as parameter.
+- `feed_before_insert` (`function($feed) -> Feed | null`): will be executed when a new feed is imported into the database. The new feed (instance of FreshRSS\_Feed) will be passed as parameter.
+- `freshrss_init` (`function() -> none`): will be executed at the end of the initialization of FreshRSS, useful to initialize components or to do additional access checks
+- `menu_admin_entry` (`function() -> string`): add an entry at the end of the "Administration" menu, the returned string must be valid HTML (e.g. `<li class="item active"><a href="url">New entry</a></li>`)
+- `menu_configuration_entry` (`function() -> string`): add an entry at the end of the "Configuration" menu, the returned string must be valid HTML (e.g. `<li class="item active"><a href="url">New entry</a></li>`)
+- `menu_other_entry` (`function() -> string`): add an entry at the end of the header dropdown menu (i.e. after the "About" entry), the returned string must be valid HTML (e.g. `<li class="item active"><a href="url">New entry</a></li>`)
+- `nav_reading_modes` (`function($reading_modes) -> array | null`): **TODO** add documentation
+- `post_update` (`function(none) -> none`): **TODO** add documentation
+- `simplepie_before_init` (`function($simplePie, $feed) -> none`): **TODO** add documentation
 
 ### Writing your own configure.phtml
 
-When you want to support user configurations for your extension or simply display some information, you have to create the `configure.phtml` file. 
+When you want to support user configurations for your extension or simply display some information, you have to create the `configure.phtml` file.
 
 **TODO**