FreshRSS/docs/fr/developers/Minz/index.md

Minz

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 module Minz_Translate par exemple).

Architecture MVC

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, 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 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 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 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 contenu dans le contrôleur hello.

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.

Exemple de code :

<?php

class FreshRSS_hello_Controller extends FreshRSS_ActionController {
	public function indexAction() {
		$this->view->a_variable = 'FooBar';
	}

	public function worldAction() {
		$this->view->a_variable = 'Hello World!';
	}
}

?>

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.

Plus loin, sera utilisée la convention hello/world pour évoquer un couple contrôleur/action.

Vues

Chaque vue est associée à un contrôleur et à une action. La vue associée à hello/world va être stockée dans un fichier bien spécifique : views/hello/world.phtml. Cette convention est imposée par Minz.

Comme expliqué plus haut, les vues sont du code HTML mixé à du PHP. Exemple de code :

<p>
	Phrase passée en paramètre : <?= $this->a_variable ?>
</p>

La variable $this->a_variable a été passée précédemment par le contrôleur (voir exemple précédent). La différence est que dans le contrôleur il est nécessaire de passer par $this->view et que dans la vue $this suffit.

Accéder aux paramètres GET / POST

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 :

<?php

$default_value = 'foo';
$param = Minz_Request::paramString('bar') ?: $default_value;

// Affichera la valeur du paramètre `bar` (passé via GET ou POST)
// ou "foo" si le paramètre n’existe pas.
echo $param;

// Force la valeur du paramètre `bar`
Minz_Request::_param('bar', 'baz');

// Affichera forcément "baz" puisque nous venons de forcer sa valeur.
// Notez que le second paramètre (valeur par défaut) est facultatif.
echo Minz_Request::paramString('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.

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.

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 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 suivante doit être évitée :

<p>
	Accéder à la page <a href="http://exemple.com?c=hello&amp;a=world">Hello world</a>!
</p>

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 display(). Minz_Url::display() prend en paramètre un tableau de la forme suivante :

<?php

$url_array = [
	'c' => 'hello',
	'a' => 'world',
	'params' => [
		'foo' => 'bar',
	],
];

// Affichera quelque chose comme .?c=hello&amp;a=world&amp;foo=bar
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() :

<?php

// Affichera la même chose que précédemment
echo _url('hello', 'world', 'foo', 'bar');

?>

Note : en règle générale, la forme raccourcie (_url()) doit être utilisée dans les vues tandis que la forme longue (Minz_Url::display()) doit être 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 celui vu juste avant.

Exemple de code :

<?php

$url_array = [
	'c' => 'hello',
	'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)
// Le code qui suit forward() va ainsi être exécuté !
Minz_Request::forward($url_array);

// Pour effectuer une redirection type 302, ajoutez "true".
// Le code qui suivra ne sera alors jamais exécuté.
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 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 une redirection type 302 en affectant un message de feedback :

<?php

$url_array = [
	'c' => 'hello',
	'a' => 'world',
];
$feedback_good = 'Tout s’est bien passé !';
$feedback_bad = 'Oups, quelque chose n’a pas marché.';

Minz_Request::good($feedback_good, $url_array, showNotification: FreshRSS_Context::userConf()->good_notification_timeout > 0);

// ou

Minz_Request::bad($feedback_bad, $url_array);

?>

Gestion de la traduction

Cette partie est expliquée dans la page dédiée.

Migration

Existing documentation includes:

• How to manage migrations