Zend_Controller_Front implémente un » motif de contrôleur frontal utilisé 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 dispatcher 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 dispatching peuvent écrire.

Zend_Controller_Front enregistre un plugin broker avec 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 dispatching au 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'action pour 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);

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 :

$front = Zend_Controller_Front::getInstance();

// 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');

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

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 dispatcheur.

• (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 dispatcheur.

• (set|get)Request() vous permet d'indiquer la classe ou l'objet de requête à utiliser durant le processus de dispatching 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 dispatching 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 dispatcheur à utiliser durant le processus de dispatching et de rechercher la valeur courante. En réglant l'objet de dispatching, vous pouvez fournir le nom d'une classe de dispatching, dans ce cas la méthode chargera le fichier de classe et l'instanciera.

  Lors de la recherche d'un objet dispatcheur, cela vérifie d'abord si un objet est présent, et sinon, instancie le dispatcheur par défaut.

• (set|get)Response() vous permet d'indiquer la classe ou l'objet de réponse à utiliser durant le processus de dispatching 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 dispatching. 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 entêtes), etc.

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 dispatching. Ces valeurs sont transmises au routeur, au dispatcheur, 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 dispatcheur d'utiliser le contrôleur par défaut dans le module par défaut pour toute requête qui ne serait pas dispatchable (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 dispatcheur 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 dispatcheur capture tout rendu et l'ajoute au contenu de l'objet réponse.

Pour sous-classer 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 dispatcheur par défaut sont employés.