Le contrôleur frontal (Front Controller)

Présentation générale

Zend_Controller_Front implémente un » motif de contrôleur frontalutilisé dans les applications » Modèle-Vue-Contrôleur (MVC). Son but est d'initialiser l'environnement de requête, d'acheminer la requête entrante et de distribuer ensuite n'importe quelles actions découvertes ; il agrège n'importe quelles réponses et les retourne quand le processus est complet.

Zend_Controller_Front implémente aussi le » motif Singleton, signifiant que seule une instance du contrôleur frontal peut être disponible à n'importe quel moment. Cela lui permet aussi d'agir comme un enregistrement dans lequel les autres objets du processus de distribution peuvent écrire.

Zend_Controller_Front enregistre un plugin brokeravec lui, permettant à des événements divers qu'il déclenche d'être observés par plugins. Dans la plupart des cas, cela donne au développeur l'occasion de construire le processus de distribution du site sans avoir besoin d'étendre le contrôleur frontal pour ajouter une fonctionnalité.

Le contrôleur frontal a besoin au minimum d'un ou plusieurs répertoires contenants les contrôleurs d'actionpour faire son travail. Une variété de méthodes peut aussi être invoquée pour plus tard construire l'environnement de contrôleur frontal et celui de ses classes d'aide.

Note: Comportement par défaut
Par défaut, le contrôleur frontal charge le plugin ErrorHandler, ainsi que le plugin d'aide d'action ViewRenderer. Ceci est fait respectivement pour simplifier la gestion d'erreur et le rendu des vues dans vos contrôleurs.
Pour désactiver ErrorHandler, exécutez l'action suivante à n'importe quel point précédant l'appel à dispatch() :

// Désactivez le plugin ErrorHandler :

$front->setParam('noErrorHandler', true);
Pour désactiver ViewRenderer, exécutez l'action suivante à n'importe quel point précédant l'appel à dispatch() :

// Désactivez l'aide ViewRenderer :

$front->setParam('noViewRenderer', true);

Méthodes principales

Le contrôleur frontal a plusieurs accesseurs pour construire son environnement. Cependant, il y a trois méthodes principales clés dans la fonctionnalité de contrôleur frontal :

getInstance()

getInstance() est utilisé pour récupérer une instance du contrôleur frontal. Comme le contrôleur frontal implémente un motif de Singleton, c'est aussi le seul moyen possible pour instancier un objet unique de contrôleur frontal.

$front = Zend_Controller_Front::getInstance();

setControllerDirectory() et addControllerDirectory

setControllerDirectory() est utilisé pour informer le distributeuroù chercher les fichiers de classes de contrôleurs d'action. Ces méthodes acceptent un chemin unique ou un tableau associatif de paires modules/chemins.

Quelques exemples :

// Régler le dossier des contrôleurs par défaut :
$front->setControllerDirectory('../application/controllers');
 
// Régler plusieurs répertoires de modules d'un seul coup :
$front->setControllerDirectory(array(
    'default' => '../application/controllers',
    'blog'    => '../modules/blog/controllers',
    'news'    => '../modules/news/controllers',
));
 
// Ajouter le répertoire de module 'foo' :
$front->addControllerDirectory('../modules/foo/controllers', 'foo');

Note: Si vous utilisez addControllerDirectory() sans nom de module, cela réglera le répertoire pour le module default - en surchargeant une valeur déjà existante.

Vous pouvez récupérer les réglages courants des répertoires du contrôleur en utilisant getControllerDirectory() ; ceci retournera un tableau des paires modules/chemins.

addModuleDirectory() et getModuleDirectory()

Un des aspects du contrôleur frontal est que vous puissiez définir une structure de dossiers modulairepour créer des composants autonomes ; ceux-ci sont nommés "modules".

Chaque module doit être dans son propre dossier, ce dossier étant un miroir du dossier du module "default" en terme de structure - c'est-à-dire, qu'il doit contenir un sous-dossier "controllers" au minimum, et typiquement un sous-dossier "views" puis d'autres sous-dossiers.

addModuleDirectory() vous permet de fournir le nom du dossier contenant un ou plusieurs dossier de modules. Il scanne alors le dossier et les ajoute au contrôleur frontal.

Ensuite, si vous souhaitez déterminer le chemin vers un module en particulier ou vers le module courant, vous pouvez appeler getModuleDirectory(), en fournissant optionnellement le nom du module spécifique que vous recherchez.

dispatch()

dispatch(Zend_Controller_Request_Abstract $request = null, Zend_Controller_Response_Abstract $response = null) fait le gros travail du contrôleur frontal. Il peut facultativement prendre un objet de requêteet/ou un objet de réponse, permettant ainsi au développeur de fournir des objets personnalisés.

Si aucun objet de requête ou de réponse ne lui sont fournis, dispatch() vérifiera s'il existe des objets précédemment enregistrés et utilisera ceux-là ou des objets par défaut pour les utiliser dans son processus (dans les deux cas, le mode HTTP sera utilisé par défaut).

De la même manière, dispatch() vérifie s'il existe des objets routeuret distributeurinscrits, et instancie des versions par défaut si aucun n'est trouvé.

Le processus de distribution possède trois évènements

le routage
la distribution
la réponse

Le routage a lieu exactement une fois, utilisant les valeurs de l'objet de requête quand dispatch() est appelé. La distribution a lieu dans une boucle ; une demande peut soit indiquer des actions multiples à distribuer, soit le contrôleur ou un plugin peuvent remettre à zéro l'objet de requête et ainsi forcer la distribution d'actions supplémentaires. Quand tout est réalisé, le contrôleur frontal retourne la réponse.

run()

Zend_Controller_Front::run($path) est une méthode "raccourci", statique, prenant simplement un chemin vers un répertoire contenant des contrôleurs. Elle récupère l'instance de contrôleur frontal (via getInstance()), enregistre le chemin fourni par l'intermédiaire de setControllerDirectory(), et finalement réalise la distribution.

Fondamentalement, run() est une méthode de convenance qui peut être employée pour les installations de sites qui n'exigent pas la personnalisation de l'environnement du contrôleur frontal.

// Instancie le contrôleur frontal, règle les dossiers de contrôleurs,
// et distribue en une seule étape :
Zend_Controller_Front::run('../application/controllers');

Méthodes d'accès à l'environnement

En plus des méthodes énumérées ci-dessus, il y a un certain nombre de méthodes d'accès qui peuvent être employées pour affecter l'environnement de contrôleur frontal - et ainsi l'environnement des classes auxquelles le contrôleur frontal délégue.

resetInstance() peut être utilisé pour effacer tous les réglages courants. Son but principal est pour les tests, mais elle peut également être employée pour des instances où vous souhaitez enchaîner ensemble les contrôleurs frontaux multiples.
(set|get)DefaultControllerName() vous permet d'indiquer un nom différent pour l'utilisation du contrôleur par défaut ("index" est employé sinon) et de rechercher la valeur courante. Ils mandatent le distributeur.
(set|get)DefaultAction() vous permet d'indiquer un nom différent pour l'utilisation de l'action par défaut ("index" est employé sinon) et de rechercher la valeur courante. Ils mandatent le distributeur.
(set|get)Request() vous permet d'indiquer la classe ou l'objet de requête à utiliser durant le processus de distribution et de rechercher la valeur courante. En réglant l'objet de requête, vous pouvez fournir le nom d'une classe de requête, dans ce cas la méthode chargera le fichier de classe et l'instanciera.
(set|get)Router() vous permet d'indiquer la classe ou l'objet de routage à utiliser durant le processus de distribution et de rechercher la valeur courante. En réglant l'objet de routage, vous pouvez fournir le nom d'une classe de routage, dans ce cas la méthode chargera le fichier de classe et l'instanciera.

Lors de la recherche d'un objet routeur, cela vérifie d'abord si un objet est présent, et sinon, instancie le routeur par défaut ("rewrite router").
(set|get)BaseUrl() vous permet d'indiquer l'URL de base à écarter lors du routage des requêtes et de rechercher la valeur courante. La valeur est fournie à l'objet de requête juste avant le routage.
(set|get)Dispatcher() vous permet d'indiquer la classe ou l'objet distributeur à utiliser durant le processus de distribution et de rechercher la valeur courante. En réglant l'objet de distribution, vous pouvez fournir le nom d'une classe de distribution, dans ce cas la méthode chargera le fichier de classe et l'instanciera.

Lors de la recherche d'un objet distributeur, cela vérifie d'abord si un objet est présent, et sinon, instancie le distributeur par défaut.
(set|get)Response() vous permet d'indiquer la classe ou l'objet de réponse à utiliser durant le processus de distribution et de rechercher la valeur courante. En réglant l'objet de réponse, vous pouvez fournir le nom d'une classe de réponse, dans ce cas la méthode chargera le fichier de classe et l'instanciera.
registerPlugin(Zend_Controller_Plugin_Abstract $plugin, $stackIndex = null) vous permet d'inscrire un objet plugin. En réglant le paramètre facultatif $stackIndex, vous pouvez contrôler l'ordre dans lequel les plugins seront exécutés.
unregisterPlugin($plugin) vous permet de désinscrire un objet plugin. $plugin peut être soit un objet plugin ou une chaîne représentant la classe du plugin à désinscrire.
throwExceptions($flag) est utilisée pour activer/désactiver la possibilité de lever des exceptions durant le processus de distribution. Par défaut, les exceptions sont récupérées et placées dans l'objet réponse ; activer throwExceptions() surchargera ce comportement et indiquera au contrôleur frontal de ne pas enregistrer le plugin de gestion des erreurs : ErrorHandler.

Pour plus d'informations, voir Exceptions avec MVC.
returnResponse($flag) est utilisée pour informer le contrôleur frontal soit de récupérer la réponse (TRUE) issue de dispatch(), ou si la réponse peut être automatiquement émise (FALSE). Par défaut la réponse est automatiquement émise (en appelant Zend_Controller_Response_Abstract::sendResponse()) ; activer returnResponse() surchargera ce comportement.

Les raisons de la récupération de la réponse incluent le désir de vérifier l'existence d'exceptions avant d'émettre la réponse, la nécessité d'enregistrer certains aspects de la réponse (comme les en-têtes), etc.

Paramètres du contrôleur frontal

Dans l'introduction, nous avons indiqué que le contrôleur frontal agit également en tant qu'enregistreur pour les divers composants du contrôleur. Il réalise ceci grâce à une famille de méthodes "param". Ces méthodes vous permettent d'enregistrer des données arbitraires - objets et variables - que le contrôleur frontal peut rechercher à tout moment dans la chaîne de distribution. Ces valeurs sont transmises au routeur, au distributeur, et aux contrôleurs d'action. Les méthodes incluent :

setParam($name, $value) vous permet de régler un paramètre unique nommé $name avec la valeur $value.
setParams(array $params) vous permet de régler des paramètres multiples en une seule fois en utilisant un tableau associatif.
getParam($name) vous permet de récupérer un unique paramètre, en utilisant $name comme identificateur.
getParams() vous permet de récupérer la liste entière des paramètres.
clearParams() vous permet d'effacer un paramètre unique (en fournissant l'identificateur sous forme de chaîne), des paramètres multiples (en fournissant un tableau d'identificateurs sous forme de chaîne), ou tous les paramètres (en ne fournissant rien).

Il y a plusieurs paramètres prédéfinis qui peuvent être réglés et qui ont des utilisations spécifiques dans la chaîne d'expédition :

useDefaultControllerAlways() est utilisée pour informer le distributeur d'utiliser le contrôleur par défaut dans le module par défaut pour toute requête qui ne serait pas distribuable (par exemple si le module/contrôleur/action n'existe pas). Par défaut, cette fonctionnalité est désactivée.

Voir Différents types d'exceptions que vous pouvez rencontrer pour plus d'informations concernant l'utilisation de ce réglage.
disableOutputBuffering() est utilisée pour informer le distributeur qu'il ne doit pas utiliser l'"output buffering" pour capturer le rendu généré par les contrôleurs d'action. Par défaut, le distributeur capture tout rendu et l'ajoute au contenu de l'objet réponse.
noViewRenderer est utilisée pour désactiver le ViewRenderer. Réglez ce paramètre à TRUE pour le désactiver.
noErrorHandler est utilisée pour désactiver le plugin ErrorHandler. Réglez ce paramètre à TRUE pour le désactiver.

Étendre le contrôleur frontal

Pour étendre le contrôleur frontal, vous devez au minimum surcharger la méthode getInstance() :

class Mon_Controleur_Frontal extends Zend_Controller_Front
{
    public static function getInstance()
    {
        if (null === self::$_instance) {
            self::$_instance = new self();
        }
 
        return self::$_instance;
    }
}

Surcharger la méthode getInstance() assure que des appels suivants à Zend_Controller_Front::getInstance() retourneront une instance de votre nouvelle sous-classe au lieu d'une instance de Zend_Controller_Front - c'est particulièrement utile pour certains des routeurs alternatifs et certaines aides de vue.

Typiquement, vous n'aurez pas besoin de sous-classer le contrôleur frontal à moins que vous ne deviez ajouter une nouvelle fonctionnalité (par exemple, un plugin d'autoloader, ou une manière d'indiquer des chemins d'aide d'action). Quelques exemples où vous pouvez vouloir changer le comportement peuvent inclure modifier comment des répertoires de contrôleur sont stockés, ou quel routeur ou distributeur par défaut sont employés.