<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.controller.dispatcher">
    <title>Le distributeur</title>

    <sect2 id="zend.controller.dispatcher.overview">
        <title>Vue d'ensemble</title>

        <para>
            La distribution est le processus de récupération de l'objet requête,
            <classname>Zend_Controller_Request_Abstract</classname>, d'extraction du nom de module,
            du nom de contrôleur, du nom d'action, et des paramètres facultatifs qui s'y trouvent,
            et enfin d'instanciation du contrôleur et de l'appel d'une action de ce contrôleur. Si
            le module, le contrôleur, ou l'action ne sont pas trouvés, il emploiera des valeurs par
            défaut pour eux. <classname>Zend_Controller_Dispatcher_Standard</classname> indique
            <code>index</code> pour le contrôleur et l'action par défaut et <code>default</code>
            pour le module par défaut, mais permet au développeur de changer ces valeurs par défaut
            pour chacun en utilisant les méthodes respectives <methodname>setDefaultController()</methodname>,
            <methodname>setDefaultAction()</methodname>, et <methodname>setDefaultModule()</methodname>.
        </para>

        <note>
            <title>Le module "Default"</title>
            <para>
                Quand vous créez des applications modulaires, vous pouvez constater que vous
                voulez aussi que votre module par défaut ait son espace de noms (dans la
                configuration par défaut, le module "<code>default</code>"
                <emphasis>n'a pas</emphasis> d'espace de noms). A partir de la version 1.5.0, vous
                pouvez spécifier le paramètre <code>prefixDefaultModule</code> à <constant>TRUE</constant>
                soit dans le contrôleur frontal soit dans le distributeur&#160;:
            </para>
            <programlisting language="php"><![CDATA[
// Dans le contrôleur frontal :
$front->setParam('prefixDefaultModule', true);

// Dans le distributeur :
$dispatcher->setParam('prefixDefaultModule', true);
]]></programlisting>
            <para>
                Ceci vous permet de ré-utiliser un module existant en tant que module par
                défaut d'une application.
            </para>
        </note>

        <para>
            La distribution se produit dans une boucle dans le contrôleur frontal. Avant que
            le distribution ne se produise, le contrôleur frontal détermine la route de la requête
            pour récupérer les valeurs spécifiées par l'utilisateur pour le module, le contrôleur ,
            l'action , et les paramètres optionnels. Il entre alors dans la boucle d'expédition, et
            distribue la requête.
        </para>

        <para>
            Au début de chaque itération, il régle un drapeau dans l'objet requête indiquant
            que l'action a été distribuée. Si une action ou un plugin <code>pre/postDispatch</code>
            remet à zéro ce drapeau, la boucle de distribution continue et tente de distribuer la
            nouvelle requête. En changeant le contrôleur et/ou l'action dans la requête et en
            effaçant le drapeau de distribution, le développeur peut définir une chaîne de requêtes
            à réaliser.
        </para>

        <para>
            La méthode du contrôleur d'action qui contrôle cette distribution est
            <methodname>_forward()</methodname>&#160;; appelez cette méthode à partir de
            <code>pre/postDispatch()</code> ou d'une méthode d'action, en fournissant une action,
            un contrôleur, un module, et optionnellement des paramètres additionnels que vous
            souhaitez passer à la nouvelle action&#160;:
        </para>

        <programlisting language="php"><![CDATA[
public function fooAction()
{
    // Transférer la nouvelle action dans le contrôleur
    // et le module courant :
    $this->_forward('bar', null, null, array('baz' => 'bogus'));
}

public function barAction()
{
    // Transférer vers une action dans un autre contrôleur,
    // FooController::bazAction(), dans le module courant :
    $this->_forward('baz', 'foo', null, array('baz' => 'bogus'));
}

public function bazAction()
{
    // Transférer vers une action dans un autre contrôleur
    // dans un autre module, Foo_BarController::bazAction():
    $this->_forward('baz', 'bar', 'foo', array('baz' => 'bogus'));
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.controller.dispatcher.subclassing">
        <title>Sous-classer le distributeur</title>

        <para>
            <classname>Zend_Controller_Front</classname> appelle en premier le routeur pour
            déterminer la première action dans la requête. Il entre ensuite dans la boucle de
            distribution, qui demande au distributeur de distribuer l'action.
        </para>

        <para>
            Le distributeur a besoin de plusieurs données afin de réaliser son travail - il
            doit connaître le format des noms d'actions et de contrôleur, où chercher les fichiers
            de classe des contrôleurs, savoir si le nom de module fourni est valide, et il a besoin
            d'une <acronym>API</acronym> pour déterminer si une requête donnée est distribuable suivant les
            informations disponibles.
        </para>

        <para>
            <classname>Zend_Controller_Dispatcher_Interface</classname> définit les méthodes
            suivantes nécessaires pour toute implémentation d'un distributeur&#160;:
        </para>

        <programlisting language="php"><![CDATA[
interface Zend_Controller_Dispatcher_Interface
{
    /**
     * Formate une chaîne en un nom de classe de contrôleur
     *
     * @param string $unformatted
     * @return string
     */
    public function formatControllerName($unformatted);

    /**
     * Formate une chaîne en un nom de méthode d'action
     *
     * @param string $unformatted
     * @return string
     */
    public function formatActionName($unformatted);

    /**
     * Détermine si une requête est distribuable
     *
     * @param  Zend_Controller_Request_Abstract $request
     * @return boolean
     */
    public function isDispatchable(
                Zend_Controller_Request_Abstract $request);

    /**
     * Règle un paramètre utilisateur
     * (via le contrôleur frontal, ou pour un usage local)
     *
     * @param string $name
     * @param mixed $value
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function setParam($name, $value);

    /**
     * Règle un tableau de paramètres utilisateur
     *
     * @param array $params
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function setParams(array $params);

    /**
     * Récupère un paramètre utilisateur unique
     *
     * @param string $name
     * @return mixed
     */
    public function getParam($name);

    /**
     * Récupère tous les paramètres utilisateur
     *
     * @return array
     */
    public function getParams();

    /**
     * Efface le tableau des paramètres utilisateur,
     * ou un paramètre utilisateur unique :
     *
     * @param null|string|array single key or
     *                          array of keys for params to clear
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function clearParams($name = null);

    /**
     * Règle l'objet réponse à utiliser, s'il existe
     *
     * @param Zend_Controller_Response_Abstract|null $response
     * @return void
     */
    public function setResponse(
                Zend_Controller_Response_Abstract $response = null);

    /**
     * Récupère l'objet réponse, s'il existe
     *
     * @return Zend_Controller_Response_Abstract|null
     */
    public function getResponse();

    /**
     * Ajoute un dossier de contrôleur dans le tableau
     * des dossiers de contrôleurs
     *
     * @param string $path
     * @param string $args
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function addControllerDirectory($path, $args = null);

    /**
     * Règle le(s) dossier(s) où les fichiers de contrôleurs
     * sont stockés
     *
     * @param string|array $dir
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function setControllerDirectory($path);

    /**
     * Retourne le(s) dossier(s) où les fichiers de contrôleurs
     * sont stockés
     *
     * @return array
     */
    public function getControllerDirectory();

    /**
     * Distribue une requête vers un (module/)contrôleur/action.
     *
     * @param  Zend_Controller_Request_Abstract $request
     * @param  Zend_Controller_Response_Abstract $response
     * @return Zend_Controller_Request_Abstract|boolean
     */
    public function dispatch(Zend_Controller_Request_Abstract $request,
                             Zend_Controller_Response_Abstract $response);

    /**
     * Informe si un module donné est valide
     *
     * @param string $module
     * @return boolean
     */
    public function isValidModule($module);

    /**
     * Retourne le nom du module par défaut
     *
     * @return string
     */
    public function getDefaultModule();

    /**
     * Retourne le nom du contrôleur par défaut
     *
     * @return string
     */
    public function getDefaultControllerName();

    /**
     * Retourne le nom de l'action par défaut
     *
     * @return string
     */
    public function getDefaultAction();
}
]]></programlisting>

        <para>
            Cependant, dans la plupart des cas, vous devriez simplement étendre la classe
            abstraite <classname>Zend_Controller_Dispatcher_Abstract</classname>, dans laquelle
            chacune de ces méthodes a déjà été définie, ou
            <classname>Zend_Controller_Dispatcher_Standard</classname> pour modifier une
            fonctionnalité du distributeur standard.
        </para>

        <para>
            Les raisons possibles au sous-classement du distributeur incluent un désir
            d'employer une classe ou un schéma différent de nommage des classes et/ou des méthodes
            dans vos contrôleurs d'action, ou un désir d'employer un paradigme de distribution
            différent tel que la distribution de fichiers de classe d'action dans des dossiers de
            contrôleur (au lieu de la distribution des méthodes de classes).
        </para>
    </sect2>
</sect1>