# Aides d'action (Helper)

## Introduction

Les aides d'action permettent aux développeurs d'injecter, en cours d'exécution et / ou à la demande, des fonctionnalités dans tout contrôleur d'action qui étend Zend_Controller_Action. Le but des aides d'action est de minimiser la nécessité d'étendre le contrôleur d'action abstrait en y injectant des fonctionnalités communes de contrôleur d'action.

Il y a de nombreuses manières d'utiliser les aides d'action. Les aides d'action utilisent le système de gestionnaire ("Broker"), similaire aux gestionnaires vus pour les Zend_View_Helper, et les Zend_Controller_Plugin. Les aides d'action (comme les aides de vue Zend_View_Helper) peuvent être chargées et appelées à la demande, ou elles peuvent être instanciées au début de la requête ("bootstrap") ou au moment de la création des contrôleurs d'action (init()). Pour mieux comprendre ceci, reportez vous à la section d'utilisation ci-dessous.

## Initialisation des aides

Une aide peut être initialisée de plusieurs manières différentes, basées sur vos besoins aussi bien que la fonctionnalité de l'aide.

Le gestionnaire d'aide est stocké en tant que membre `$_helper` du Zend_Controller_Action ; utilisez le gestionnaire pour récupérer ou appeler les aides. Les méthodes pour faire ceci incluent :

- L'utilisation explicite de getHelper(). Passez lui simplement un nom, et l'objet d'aide est retourné :

      $flashMessenger = $this->_helper->getHelper('FlashMessenger');
      $message = 'Nous avons fait quelquechose lors de la dernière requête';
      $flashMessenger->addMessage($message);

- L'utilisation de la fonctionnalité __get() du gestionnaire d'aide et récupérez l'aide comme si elle était une propriété membre du gestionnaire :

      $flashMessenger = $this->_helper->FlashMessenger;
      $message = 'Nous avons fait quelquechose lors de la dernière requête';
      $flashMessenger->addMessage($message);

- Enfin, la plupart des aides d'action implémente la méthode direct() qui va appeler une méthode spécifique par défaut dans l'aide. Dans l'exemple de FlashMessenger, ceci appelle addMessage() :

      $message = 'Nous avons fait quelquechose lors de la dernière requête';
      $this->_helper->FlashMessenger($message);

Tous les exemples ci-dessus sont équivalents.

Vous pouvez vouloir aussi instancier les aides explicitement. Vous pourriez avoir besoin de ceci si vous utilisez l'aide hors du contexte du contrôleur d'action, ou si vous souhaitez fournir une aide au gestionnaire d'aides à utiliser pour une action quelconque. L'instanciation se fait comme toute autre classe PHP.

## Le gestionnaire d'aide (Broker)

Zend_Controller_Action_HelperBroker gère les détails de l'enregistrement des objets d'aide et les chemins de ces aides, ainsi que la récupération des aides à la demande.

Pour enregistrer une aide dans le gestionnaire, utilisez addHelper() :

    Zend_Controller_Action_HelperBroker::addHelper($helper);

Bien sûr, instancier et fournir des aides au gestionnaire est coûteux en temps et en ressource donc deux méthodes existent pour automatiser les choses légèrement : addPrefix() et addPath().

- addPrefix() prend un préfixe de classe et l'utilise pour déterminer le chemin des dossiers dans lesquels les classes d'aides ont été définies. Ceci suppose que le préfixe de la classe respecte la convention de nommage de Zend Framework.

      // Ajoute les aides préfixées Mes_Action_Helpers dans Mes/Action/Helpers/
      Zend_Controller_Action_HelperBroker::addPrefix('Mes_Action_Helpers');

- addPath() prend un répertoire en premier argument et un préfixe de classe en second (par défaut réglé à "Zend_Controller_Action_Helper"). Ceci vous permet de faire correspondre vos propres préfixes de classe à vos dossiers spécifiques.

      // Ajoute les aides préfixées avec Aide dans Plugins/Aides/
      Zend_Controller_Action_HelperBroker::addPath('./Plugins/Aides', 'Aide');

Puisque ces méthodes sont statiques, elles peuvent être appelées en tout point du déroulement du contrôleur pour ajouter dynamiquement les aides nécessaires.

En interne, le gestionnaire d'aide utilise une instance de PluginLoaderpour conserver les chemins. Vous pouvez récupérer le PluginLoader en utilisant la méthode statique getPluginLoader(), ou alternativement, injecter une instance personnalisée de PluginLoader en utilisant setPluginLoader().

Pour déterminer si une aide existe dans le gestionnaire d'aide, utilisez hasHelper($name), où `$name` est le nom raccourci de l'aide (sans le préfixe) :

    // Vérifie si l'aide 'redirector' est enregistrée dans le gestionnaire :
    if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
        echo 'L\'aide Redirector est enregistrée';
    }

Il existe aussi deux méthodes statiques pour récupérer les aides issues du gestionnaire d'aide : getExistingHelper() et getStaticHelper(). getExistingHelper() récupérera une aide seulement si elle a précédemment été invoquée par ou explicitement enregistrée dans le gestionnaire d'aides; la méthode lèvera une exception sinon. getStaticHelper() réalise la même chose que getExistingHelper(), mais tentera d'instancier l'aide si elle n'a pas déjà été enregistrée dans la pile des aides. getStaticHelper() est un bon choix pour récupérer les aides que vous voulez configurer.

Les deux méthodes prennent un unique paramètre, `$name`, qui est le nom court de l'aide (c'est-à-dire sans le préfixe).

    // Vérifie si l'aide 'redirector' est enregistrée dans le gestionnaire,
    // et l'extrait :
    if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
        $redirector =
            Zend_Controller_Action_HelperBroker::getExistingHelper('redirector');
    }

    // Ou, simplement le récupère, sans se soucier s'il a ou non été
    // enregistré précédemment :
    $redirector =
        Zend_Controller_Action_HelperBroker::getStaticHelper('redirector');
    }

Enfin, pour effacer une aide enregistrée du gestionnaire, utilisez removeHelper($name), où `$name` est le nom raccourci de l'aide (sans le préfixe) :

    // Effacement conditionnel de l'aide 'redirector' du gestionnaire :
    if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
        Zend_Controller_Action_HelperBroker::removeHelper('redirector')
    }

## Aides d'action intégrées

Zend Framework inclue plusieurs aides d'action par défaut : AutoComplete pour des réponses automatiques à des auto-complétions AJAX ; ContextSwitch et AjaxContext pour distribuer des formats de réponse alternatifs pour vos actions ; FlashMessenger pour gérer des messages entre les sessions ; Json pour encoder et envoyer des réponses JSON ; Redirector, qui fournit différentes implémentations pour rediriger vers des pages internes ou externes à votre application ; et ViewRenderer pour automatiser le processus de paramétrage de vos objets de vues dans votre contrôleur et du rendu de ces vues.

## Écrire vos propres aides

Les aides d'action étendent Zend_Controller_Action_Helper_Abstract, une classe abstraite qui fournit l'interface basique et les fonctionnalités requises par le gestionnaire d'aides. Ceci inclue les méthodes suivantes :

- setActionController() est utilisée pour paramétrer le contrôleur d'action courant.

- init(), déclenchée par le gestionnaire d'aides à l'instanciation, peut être utilisée pour déclencher l'initialisation dans l'aide ; ceci peut être pratique pour remettre dans l'état initial quand de multiples contrôleurs utilisent la même aide dans des actions enchaînées.

- preDispatch() est déclenchée avant la distribution d'une action.

- postDispatch() est déclenchée quand une action a été distribuée - même si un plugin preDispatch() a évité l'action. Principalement utile pour le nettoyage.

- getRequest() récupère l'objet de requête courant.

- getResponse() récupère l'objet de réponse courant.

- getName() récupère le nom de l'aide. Elle récupère la portion du nom de la classe qui suit le dernier tiret bas ("_"), ou le nom de la classe entier sinon. Pour exemple, si la classe est nommée Zend_Controller_Action_Helper_Redirector, elle retourne Redirector ; une classe nommée FooMessage retournera elle-même.

Vous pouvez optionnellement inclure une méthode direct() dans votre classe d'aide. Si définie, ceci vous permet de traiter l'aide comme une méthode du gestionnaire, dans le but de faciliter un usage unique de l'aide. Pour exemple, l'aide Redirectordéfinit direct() comme un alias de goto(), vous permettant d'utiliser l'aide comme ceci :

    // Redirige vers /blog/view/item/id/42
    $this->_helper->redirector('item', 'view', 'blog', array('id' => 42));

En interne, la méthode __call() du gestionnaire d'aides cherche une aide nommée redirector, puis vérifie si cette aide possède une méthode direct(), et enfin appelle cette méthode avec les arguments fournis.

Une fois que vous avez créé vos propres classes d'aide, vous pouvez en fournir l'accès comme décrit dans les sections ci-dessus.