diff options
| author | 2022-01-08 21:58:55 +0100 | |
|---|---|---|
| committer | 2022-01-08 21:58:55 +0100 | |
| commit | 1acd3ab09be1b65bfd6122ee351490c3b5527bb8 (patch) | |
| tree | f11de558e7a09522a45d1c155d9707ecda6bf1eb /docs/fr/developers/03_Backend | |
| parent | 916df412f5b6f7fb9bcfb705a3c8c23e35304410 (diff) | |
Use typographic quotes (#4133)
* Use typographic quotes
* A few fixes
* Fix
* Fix not saved
* Implement feedback
* Detail
* Revert spoken English fixes
Left for a future dedicated discussion
* More reverts
* Final reverts
* Final minor
Diffstat (limited to 'docs/fr/developers/03_Backend')
| -rw-r--r-- | docs/fr/developers/03_Backend/04_Changing_source_code.md | 2 | ||||
| -rw-r--r-- | docs/fr/developers/03_Backend/05_Extensions.md | 174 |
2 files changed, 88 insertions, 88 deletions
diff --git a/docs/fr/developers/03_Backend/04_Changing_source_code.md b/docs/fr/developers/03_Backend/04_Changing_source_code.md index 734d40569..3bcbada97 100644 --- a/docs/fr/developers/03_Backend/04_Changing_source_code.md +++ b/docs/fr/developers/03_Backend/04_Changing_source_code.md @@ -8,7 +8,7 @@ > **À FAIRE** -## Gestion de l'authentification +## Gestion de l’authentification > **À FAIRE** diff --git a/docs/fr/developers/03_Backend/05_Extensions.md b/docs/fr/developers/03_Backend/05_Extensions.md index 98c2b9f7e..a8cfd40cd 100644 --- a/docs/fr/developers/03_Backend/05_Extensions.md +++ b/docs/fr/developers/03_Backend/05_Extensions.md @@ -1,9 +1,9 @@ -# Écriture d'extensions pour FreshRSS +# Écriture d’extensions pour FreshRSS ## Présentation de FreshRSS FreshRSS est un agrégateur de flux RSS / Atom écrit en PHP depuis octobre -2012. Le site officiel est situé à l'adresse +2012. Le site officiel est situé à l’adresse [freshrss.org](https://freshrss.org) et son dépot Git est hébergé par Github : [github.com/FreshRSS/FreshRSS](https://github.com/FreshRSS/FreshRSS). @@ -13,25 +13,25 @@ FreshRSS est limité dans ses possibilités techniques par différents facteurs : * La disponibilité des développeurs principaux ; -* La volonté d'intégrer certains changements ; +* La volonté d’intégrer certains changements ; * Le niveau de « hack » nécessaire pour intégrer des fonctionnalités à la marge. Si la première limitation peut, en théorie, être levée par la participation de nouveaux contributeurs au projet, elle est en réalité conditionnée par la -volonté des contributeurs à s'intéresser au code source du projet en +volonté des contributeurs à s’intéresser au code source du projet en entier. Afin de lever les deux autres limitations quant à elles, il faudra la plupart du temps passer par un « à-coté » souvent synonyme de « fork ». -Une autre solution consiste à passer par un système d'extensions. En -permettant à des utilisateurs d'écrire leur propre extension sans avoir à -s'intéresser au cœur même du logiciel de base, on permet : +Une autre solution consiste à passer par un système d’extensions. En +permettant à des utilisateurs d’écrire leur propre extension sans avoir à +s’intéresser au cœur même du logiciel de base, on permet : 1. De réduire la quantité de code source à assimiler pour un nouveau contributeur ; -2. De permettre d'intégrer des nouveautés de façon non-officielles ; -3. De se passer des développeurs principaux pour d'éventuelles améliorations +2. De permettre d’intégrer des nouveautés de façon non-officielles ; +3. De se passer des développeurs principaux pour d’éventuelles améliorations sans passer par la case « fork ». -Note : il est tout à fait imaginable que les fonctionnalités d'une extension +Note : il est tout à fait imaginable que les fonctionnalités d’une extension puissent par la suite être intégrées dans le code initial de FreshRSS de façon officielle. Cela permet de proposer un « proof of concept » assez facilement. @@ -42,45 +42,45 @@ facilement. Cette fiche technique devrait renvoyer vers la documentation officielle de FreshRSS et de Minz (le framework PHP sur lequel repose -FreshRSS). Malheureusement cette documentation n'existe pas encore. Voici -donc en quelques mots les principaux éléments à connaître. Il n'est pas -nécessaire de lire l'ensemble des chapitres de cette section si vous n'avez -pas à utiliser une fonctionnalité dans votre extension (si vous n'avez pas -besoin de traduire votre extension, pas besoin d'en savoir plus sur le +FreshRSS). Malheureusement cette documentation n’existe pas encore. Voici +donc en quelques mots les principaux éléments à connaître. Il n’est pas +nécessaire de lire l’ensemble des chapitres de cette section si vous n’avez +pas à utiliser une fonctionnalité dans votre extension (si vous n’avez pas +besoin de traduire votre extension, pas besoin d’en savoir plus sur le module `Minz_Translate` par exemple). ### Architecture MVC -Minz repose et impose une architecture MVC pour les projets l'utilisant. On +Minz repose et impose une architecture MVC pour les projets l’utilisant. On distingue dans cette architecture trois composants principaux : -* Le Modèle : c'est l'objet de base que l'on va manipuler. Dans FreshRSS, +* Le Modèle : c’est l’objet de base que l’on va manipuler. Dans FreshRSS, les catégories, les flux et les articles sont des modèles. La partie du code qui permet de les manipuler en base de données fait aussi partie du modèle mais est séparée du modèle de base : on parle de DAO (pour « Data Access Object »). Les modèles sont stockés dans un répertoire `Models`. -* La Vue : c'est ce qui représente ce que verra l'utilisateur. La vue est - donc simplement du code HTML que l'on mixe avec du PHP pour afficher les +* La Vue : c’est ce qui représente ce que verra l’utilisateur. La vue est + donc simplement du code HTML que l’on mixe avec du PHP pour afficher les informations dynamiques. Les vues sont stockées dans un répertoire `views`. -* Le Contrôleur : c'est ce qui permet de lier modèles et vues entre +* Le Contrôleur : c’est ce qui permet de lier modèles et vues entre eux. Typiquement, un contrôleur va charger des modèles à partir de la base - de données (une liste d'articles par exemple) pour les « passer » à une - vue afin qu'elle les affiche. Les contrôleurs sont stockés dans un + de données (une liste d’articles par exemple) pour les « passer » à une + vue afin qu’elle les affiche. Les contrôleurs sont stockés dans un répertoire `Controllers`. ### Routage Afin de lier une URL à un contrôleur, on doit passer par une phase dite de « routage ». Dans FreshRSS, cela est particulièrement simple car il suffit -d'indiquer le nom du contrôleur à charger dans l'URL à l'aide d'un paramètre `c`. -Par exemple, l'adresse <http://exemple.com?c=hello> va exécuter le code +d’indiquer le nom du contrôleur à charger dans l’URL à l’aide d’un paramètre `c`. +Par exemple, l’adresse <http://exemple.com?c=hello> va exécuter le code contenu dans le contrôleur `hello`. -Une notion qui n'a pas encore été évoquée est le système d'« actions ». Une +Une notion qui n’a pas encore été évoquée est le système d'« actions ». Une action est exécutée *sur* un contrôleur. Concrètement, un contrôleur va être représenté par une classe et ses actions par des méthodes. Pour exécuter une -action, il est nécessaire d'indiquer un paramètre `a` dans l'URL. +action, il est nécessaire d’indiquer un paramètre `a` dans l’URL. Exemple de code : @@ -100,12 +100,12 @@ class FreshRSS_hello_Controller extends FreshRSS_ActionController { ?> ``` -Si l'on charge l'adresse <http://exemple.com?c=hello&a=world>, l'action +Si l’on charge l’adresse <http://exemple.com?c=hello&a=world>, l’action `world` va donc être exécutée sur le contrôleur `hello`. -Note : si `c` ou `a` n'est pas précisée, la valeur par défaut de chacune de -ces variables est `index`. Ainsi l'adresse <http://exemple.com?c=hello> va -exécuter l'action `index` du contrôleur `hello`. +Note : si `c` ou `a` n’est pas précisée, la valeur par défaut de chacune de +ces variables est `index`. Ainsi l’adresse <http://exemple.com?c=hello> va +exécuter l’action `index` du contrôleur `hello`. Plus loin, sera utilisée la convention `hello/world` pour évoquer un couple contrôleur/action. @@ -131,7 +131,7 @@ La variable `$this->a_variable` a été passée précédemment par le contrôleu Il est souvent nécessaire de profiter des paramètres passés par GET ou par POST. Dans Minz, ces paramètres sont accessibles de façon indistincts à -l'aide de la classe `Minz_Request`. Exemple de code : +l’aide de la classe `Minz_Request`. Exemple de code : ```php <?php @@ -140,7 +140,7 @@ $default_value = 'foo'; $param = Minz_Request::param('bar', $default_value); // Affichera la valeur du paramètre `bar` (passé via GET ou POST) -// ou "foo" si le paramètre n'existe pas. +// ou "foo" si le paramètre n’existe pas. echo $param; // Force la valeur du paramètre `bar` @@ -153,25 +153,25 @@ echo Minz_Request::param('bar'); ?> ``` -La méthode `Minz_Request::isPost()` peut être utile pour n'exécuter un -morceau de code que s'il s'agit d'une requête POST. +La méthode `Minz_Request::isPost()` peut être utile pour n’exécuter un +morceau de code que s’il s’agit d’une requête POST. -Note : il est préférable de n'utiliser `Minz_Request` que dans les +Note : il est préférable de n’utiliser `Minz_Request` que dans les contrôleurs. Il est probable que vous rencontriez cette méthode dans les -vues de FreshRSS, voire dans les modèles, mais sachez qu'il ne s'agit -**pas** d'une bonne pratique. +vues de FreshRSS, voire dans les modèles, mais sachez qu’il ne s’agit +**pas** d’une bonne pratique. ### Accéder aux paramètres de session -L'accès aux paramètres de session est étrangement similaire aux paramètres -GET / POST mais passe par la classe `Minz_Session` cette fois-ci ! Il n'y a -pas d'exemple ici car vous pouvez reprendre le précédent en changeant tous +L’accès aux paramètres de session est étrangement similaire aux paramètres +GET / POST mais passe par la classe `Minz_Session` cette fois-ci ! Il n’y a +pas d’exemple ici car vous pouvez reprendre le précédent en changeant tous les `Minz_Request` par des `Minz_Session`. ### Gestion des URL Pour profiter pleinement du système de routage de Minz, il est fortement -déconseillé d'écrire les URL en dur dans votre code. Par exemple, la vue +déconseillé d’écrire les URL en dur dans votre code. Par exemple, la vue suivante doit être évitée : ```html @@ -180,11 +180,11 @@ suivante doit être évitée : </p> ``` -Si un jour il est décidé d'utiliser un système d'« url rewriting » pour +Si un jour il est décidé d’utiliser un système d'« url rewriting » pour avoir des adresses au format <http://exemple.com/controller/action>, toutes les adresses précédentes deviendraient ineffectives ! -Préférez donc l'utilisation de la classe `Minz_Url` et de sa méthode +Préférez donc l’utilisation de la classe `Minz_Url` et de sa méthode `display()`. `Minz_Url::display()` prend en paramètre un tableau de la forme suivante : @@ -206,7 +206,7 @@ echo Minz_Url::display($url_array); ``` Comme cela peut devenir un peu pénible à utiliser à la longue, surtout dans -les vues, il est préférable d'utiliser le raccourci `_url()` : +les vues, il est préférable d’utiliser le raccourci `_url()` : ```php <?php @@ -224,8 +224,8 @@ utilisée dans les contrôleurs. ### Redirections Il est souvent nécessaire de rediriger un utilisateur vers une autre -page. Pour cela, la classe `Minz_Request` dispose d'une autre méthode utile -: `forward()`. Cette méthode prend en argument le même format d'URL que +page. Pour cela, la classe `Minz_Request` dispose d’une autre méthode utile +: `forward()`. Cette méthode prend en argument le même format d’URL que celui vu juste avant. Exemple de code : @@ -238,8 +238,8 @@ $url_array = [ 'a' => 'world', ]; -// Indique à Minz de rediriger l'utilisateur vers la page hello/world. -// Notez qu'il s'agit d'une redirection au sens Minz du terme, pas d'une redirection que le navigateur va avoir à gérer (code HTTP 301 ou 302) +// Indique à Minz de rediriger l’utilisateur vers la page hello/world. +// Notez qu’il s’agit d’une redirection au sens Minz du terme, pas d’une redirection que le navigateur va avoir à gérer (code HTTP 301 ou 302) // Le code qui suit forward() va ainsi être exécuté ! Minz_Request::forward($url_array); @@ -251,12 +251,12 @@ Minz_Request::forward($url_array, true); ``` Il est très fréquent de vouloir effectuer une redirection tout en affichant -un message à l'utilisateur pour lui indiquer comment s'est déroulée l'action -effectuée juste avant (validation d'un formulaire par exemple). Un tel +un message à l’utilisateur pour lui indiquer comment s’est déroulée l’action +effectuée juste avant (validation d’un formulaire par exemple). Un tel message est passé par une variable de session `notification` (note : nous parlerons plutôt de « feedback » désormais pour éviter la confusion avec une notification qui peut survenir à tout moment). Pour faciliter ce genre -d'action très fréquente, il existe deux raccourcis qui effectuent tout deux +d’action très fréquente, il existe deux raccourcis qui effectuent tout deux une redirection type 302 en affectant un message de feedback : ```php @@ -266,8 +266,8 @@ $url_array = [ 'c' => 'hello', 'a' => 'world', ]; -$feedback_good = 'Tout s\'est bien passé !'; -$feedback_bad = 'Oups, quelque chose n\'a pas marché.'; +$feedback_good = 'Tout s’est bien passé !'; +$feedback_bad = 'Oups, quelque chose n’a pas marché.'; Minz_Request::good($feedback_good, $url_array); @@ -280,32 +280,32 @@ Minz_Request::bad($feedback_bad, $url_array); ### Gestion de la traduction -Il est fréquent (et c'est un euphémisme) de vouloir afficher des phrases à -l'utilisateur. Dans l'exemple précédent par exemple, nous affichions un -feedback à l'utilisateur en fonction du résultat d'une validation de +Il est fréquent (et c’est un euphémisme) de vouloir afficher des phrases à +l’utilisateur. Dans l’exemple précédent par exemple, nous affichions un +feedback à l’utilisateur en fonction du résultat d’une validation de formulaire. Le problème est que FreshRSS possède des utilisateurs de différentes nationalités. Il est donc nécessaire de pouvoir gérer -différentes langues pour ne pas rester cantonné à l'Anglais ou au Français. +différentes langues pour ne pas rester cantonné à l’Anglais ou au Français. La solution consiste à utiliser la classe `Minz_Translate` qui permet de traduire dynamiquement FreshRSS (ou toute application basée sur Minz). Avant -d'utiliser ce module, il est nécessaire de savoir où trouver les chaînes de +d’utiliser ce module, il est nécessaire de savoir où trouver les chaînes de caractères à traduire. Chaque langue possède son propre sous-répertoire dans un répertoire parent nommé `i18n`. Par exemple, les fichiers de langue en Français sont situés dans `i18n/fr/`. Il existe sept fichiers différents : -* `admin.php` pour tout ce qui est relatif à l'administration de FreshRSS ; -* `conf.php` pour l'aspect configuration ; +* `admin.php` pour tout ce qui est relatif à l’administration de FreshRSS ; +* `conf.php` pour l’aspect configuration ; * `feedback.php` contient les traductions des messages de feedback ; * `gen.php` stocke ce qui est global à FreshRSS (gen pour « general ») ; * `index.php` pour la page principale qui liste les flux et la page « À propos » ; -* `install.php` contient les phrases relatives à l'installation de FreshRSS ; -* `sub.php` pour l'aspect gestion des abonnements (sub pour « subscription »). +* `install.php` contient les phrases relatives à l’installation de FreshRSS ; +* `sub.php` pour l’aspect gestion des abonnements (sub pour « subscription »). Cette organisation permet de ne pas avoir un unique énorme fichier de traduction. -Les fichiers de traduction sont assez simples : il s'agit seulement de +Les fichiers de traduction sont assez simples : il s’agit seulement de retourner un tableau PHP contenant les traductions. Extrait du fichier `app/i18n/fr/gen.php` : @@ -329,7 +329,7 @@ return array( ?> ``` -Pour accéder à ces traductions, `Minz_Translate` va nous aider à l'aide de +Pour accéder à ces traductions, `Minz_Translate` va nous aider à l’aide de sa méthode `Minz_Translate::t()`. Comme cela peut être un peu long à taper, il a été introduit un raccourci qui **doit** être utilisé en toutes circonstances : `_t()`. Exemple de code : @@ -342,20 +342,20 @@ circonstances : `_t()`. Exemple de code : </p> ``` -La chaîne à passer à la fonction `_t()` consiste en une série d'identifiants +La chaîne à passer à la fonction `_t()` consiste en une série d’identifiants séparés par des points. Le premier identifiant indique de quel fichier on veut extraire la traduction (dans notre cas présent, de `gen.php`), tandis que les suivantes indiquent des entrées de tableaux. Ainsi `action` est une entrée du tableau principal et `back_to_rss_feeds` est une entrée du tableau -`action`. Cela permet d'organiser encore un peu plus nos fichiers de +`action`. Cela permet d’organiser encore un peu plus nos fichiers de traduction. Il existe un petit cas particulier qui permet parfois de se simplifier la -vie : le cas de l'identifiant `_`. Celui-ci doit nécessairement être présent -en bout de chaîne et permet de donner une valeur à l'identifiant de niveau -supérieur. C'est assez dur à expliquer mais très simple à comprendre. Dans -l'exemple donné plus haut, un `_` est associé à la valeur `FreshRSS` : cela -signifie qu'il n'y a pas besoin d'écrire `_t('gen.freshrss._')` mais +vie : le cas de l’identifiant `_`. Celui-ci doit nécessairement être présent +en bout de chaîne et permet de donner une valeur à l’identifiant de niveau +supérieur. C’est assez dur à expliquer mais très simple à comprendre. Dans +l’exemple donné plus haut, un `_` est associé à la valeur `FreshRSS` : cela +signifie qu’il n’y a pas besoin d’écrire `_t('gen.freshrss._')` mais `_t('gen.freshrss')` suffit. ### Gestion de la configuration @@ -364,14 +364,14 @@ signifie qu'il n'y a pas besoin d'écrire `_t('gen.freshrss._')` mais Nous y voilà ! Nous avons abordé les fonctionnalités les plus utiles de Minz et qui permettent de faire tourner FreshRSS correctement et il est plus que -temps d'aborder les extensions en elles-même. +temps d’aborder les extensions en elles-même. -Une extension permet donc d'ajouter des fonctionnalités facilement à +Une extension permet donc d’ajouter des fonctionnalités facilement à FreshRSS sans avoir à toucher au cœur du projet directement. ### Travailler dans Docker -Quand on travaille sur une extension, c'est toujours plus facile de la travailler directement dans son environnement. Avec Docker, on peut exploiter l'option ```volume``` quand on démarre le conteneur. Heureusement, on peut l'utiliser sans avoir de connaissances particulières de Docker en utilisant la règle du Makefile : +Quand on travaille sur une extension, c’est toujours plus facile de la travailler directement dans son environnement. Avec Docker, on peut exploiter l’option ```volume``` quand on démarre le conteneur. Heureusement, on peut l’utiliser sans avoir de connaissances particulières de Docker en utilisant la règle du Makefile : ```sh make start extensions="/chemin/complet/de/l/extension/1 /chemin/complet/de/l/extension/2" ``` @@ -379,18 +379,18 @@ make start extensions="/chemin/complet/de/l/extension/1 /chemin/complet/de/l/ext ### Les fichiers et répertoires de base La première chose à noter est que **toutes** les extensions **doivent** se -situer dans le répertoire `extensions`, à la base de l'arborescence de +situer dans le répertoire `extensions`, à la base de l’arborescence de FreshRSS. Une extension est un répertoire contenant un ensemble de fichiers -et sous-répertoires obligatoires ou facultatifs. La convention veut que l'on -précède le nom du répertoire principal par un « x » pour indiquer qu'il ne -s'agit pas d'une extension incluse par défaut dans FreshRSS. +et sous-répertoires obligatoires ou facultatifs. La convention veut que l’on +précède le nom du répertoire principal par un « x » pour indiquer qu’il ne +s’agit pas d’une extension incluse par défaut dans FreshRSS. -Le répertoire principal d'une extension doit comporter au moins deux +Le répertoire principal d’une extension doit comporter au moins deux fichiers **obligatoire** : -* Un fichier `metadata.json` qui contient une description de l'extension. Ce +* Un fichier `metadata.json` qui contient une description de l’extension. Ce fichier est écrit en JSON ; -* Un fichier `extension.php` contenant le point d'entrée de l'extension. +* Un fichier `extension.php` contenant le point d’entrée de l’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 @@ -434,14 +434,14 @@ important elements. It must contain a valid JSON array containing the following entries: * `name` : le nom de votre extension ; -* `author` : votre nom, éventuellement votre adresse mail mais il n'y a pas +* `author` : votre nom, éventuellement votre adresse mail mais il n’y a pas de format spécifique à adopter ; * `description` : une description de votre extension ; -* `version` : le numéro de version actuel de l'extension ; -* `entrypoint` : indique le point d'entrée de votre extension. Il doit +* `version` : le numéro de version actuel de l’extension ; +* `entrypoint` : indique le point d’entrée de votre extension. Il doit correspondre au nom de la classe contenue dans le fichier `extension.php` - sans le suffixe `Extension` (donc si le point d'entrée est `HelloWorld`, - votre classe s'appellera `HelloWorldExtension`) ; + sans le suffixe `Extension` (donc si le point d’entrée est `HelloWorld`, + votre classe s’appellera `HelloWorldExtension`) ; * `type` : définit le type de votre extension. Il existe deux types : `system` et `user`. Nous étudierons cette différence juste après. @@ -524,7 +524,7 @@ The following events are available: * `check_url_before_add` (`function($url) -> Url | null`): will be executed every time a URL is added. The URL itself will be passed as - parameter. This way a website known to have feeds which doesn't advertise + parameter. This way a website known to have feeds which doesn’t advertise it in the header can still be automatically supported. * `entry_before_display` (`function($entry) -> Entry | null`): will be executed every time an entry is rendered. The entry itself (instance of |
