<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect3 id="zend.controller.actionhelpers.redirector">
    <title>Redirector</title>

    <sect4 id="zend.controller.actionhelper.redirector.introduction">
        <title>Introduction</title>

        <para>
            L'aide <emphasis>Redirector</emphasis> vous permet d'utiliser un objet de redirection
            qui remplit tous les besoins de votre application, nécessaires à une redirection vers
            une nouvelle <acronym>URL</acronym>. Il fournit de nombreux avantages par rapport à la
            méthode <methodname>_redirect()</methodname>, comme la capacité de préconfigurer le
            comportement du site dans l'objet redirecteur ou d'utiliser l'interface intégrée
            <methodname>gotoSimple($action, $controller, $module, $params)</methodname>
            similaire à <methodname>Zend_Controller_Action::_forward()</methodname>.
        </para>

        <para>
            <emphasis>Redirector</emphasis> possède une certain nombre de méthodes qui peuvent être
            utilisées pour affecter le comportement de la redirection&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setCode()</methodname> peut être utilisée pour paramétrer le code
                    <acronym>HTTP</acronym> de la réponse à utiliser pendant la redirection.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setExit()</methodname> peut être utilisée pour forcer un
                    <methodname>exit()</methodname> juste après la redirection. Par défaut ceci
                    vaut <constant>TRUE</constant>.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setGotoSimple()</methodname> peut être utilisée pour paramétrer
                    l'<acronym>URL</acronym> par défaut à utiliser si aucune n'est fournie à
                    <methodname>gotoSimple()</methodname>. Elle utilise les <acronym>API</acronym>
                    de <methodname>Zend_Controller_Action::_forward()</methodname>&#160;:
                    <methodname>setGotoSimple($action, $controller = null, $module = null,
                    array $params = array())</methodname>
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setGotoRoute()</methodname> peut être utilisée pour paramétrer
                    une <acronym>URL</acronym> basée sur une route enregistrée. Fournissez un
                    tableau de paires clé&#160;/&#160;valeur et une route nommée, et elle assemblera
                    une <acronym>URL</acronym> suivant le type de la route et sa définition.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setGotoUrl()</methodname> peut être utilisée pour paramétrer
                    l'<acronym>URL</acronym> par défaut à utiliser si aucune n'est fournie à
                    <methodname>gotoUrl()</methodname>. Accepte une chaîne unique correspondant
                    à une <acronym>URL</acronym>.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setPrependBase()</methodname> peut être utilisée pour ajouter une
                    chaîne au début de l'<acronym>URL</acronym> de base de l'objet requête pour
                    les <acronym>URL</acronym>s spécifiées avec
                    <methodname>setGotoUrl()</methodname>, <methodname>gotoUrl()</methodname>, ou
                    <methodname>gotoUrlAndExit()</methodname>.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setUseAbsoluteUri()</methodname> peut être utilisée pour forcer le
                    <emphasis>Redirector</emphasis> à utiliser des <acronym>URI</acronym> absolus
                    pour la redirection. Quand cette option est choisie, elle utilise les valeurs
                    de <varname>$_SERVER['HTTP_HOST']</varname>,
                    <varname>$_SERVER['SERVER_PORT']</varname>, et
                    <varname>$_SERVER['HTTPS']</varname> pour former un <acronym>URI</acronym>
                    complet à partir de l'<acronym>URL</acronym> spécifiée par une des méthodes
                    de redirection. Cette option est inactive par défaut, mais pourra être activée
                    par défaut dans les prochaines releases.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            De plus, il y a une variété de méthodes dans le redirecteur pour réaliser les
            redirections actuelles&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>gotoSimple()</methodname> utilise
                    <methodname>setGotoSimple()</methodname> (<acronym>API</acronym> de type
                    <methodname>_forward()</methodname>) pour construire une <acronym>URL</acronym>
                    et réaliser une redirection.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>gotoRoute()</methodname> utilise
                    <methodname>setGotoRoute()</methodname> (<emphasis>assemblage de
                    route</emphasis>) pour construire une <acronym>URL</acronym> et réaliser une
                    redirection.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>gotoUrl()</methodname> utilise <methodname>setGotoUrl()</methodname>
                    (<emphasis> <acronym>URL</acronym> sous forme de chaîne</emphasis>) pour
                    construire une <acronym>URL</acronym> et réaliser une redirection.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Enfin, vous pouvez déterminer l'<acronym>URL</acronym> de la redirection courante à
            tout moment en utilisant <methodname>getRedirectUrl()</methodname>.
        </para>
    </sect4>

    <sect4 id="zend.controller.actionhelper.redirector.basicusage">
        <title>Exemples d'utilisation basique</title>

        <example id="zend.controller.actionhelper.redirector.basicusage.example-1">

            <title>Options de réglage</title>

            <para>
                Cet exemple surcharge de multiples options, incluant le réglage du code de statut
                <acronym>HTTP</acronym> à utiliser dans la redirection ("303"), pas de sortie
                par défaut après la redirection, et la définition d'une <acronym>URL</acronym>
                par défaut à utiliser lors d'une redirection.
            </para>

            <programlisting language="php"><![CDATA[
class SomeController extends Zend_Controller_Action
{
    /**
     * Redirector - défini pour l'auto-complétion
     *
     * @var Zend_Controller_Action_Helper_Redirector
     */
    protected $_redirector = null;

    public function init()
    {
        $this->_redirector = $this->_helper->getHelper('Redirector');

        // Régle les options par défaut pour le redirector
        // Puisque l'objet est enregistré dans le gestionnaire d'aide,
        // ceci sera effectif pour toutes les actions réalisées après
        // ce point
        $this->_redirector->setCode(303)
                          ->setExit(false)
                          ->setGotoSimple("this-action", "some-controller");
    }

    public function myAction()
    {
        /* Faire quelquechose */

        // Redirige vers une URL enregistrée précédemment,
        // et force une sortie pour finir
        $this->_redirector->redirectAndExit();
        return; // jamais atteint
    }
}
]]></programlisting>
        </example>

        <example id="zend.controller.actionhelper.redirector.basicusage.example-2">
            <title>Utiliser les valeurs par défaut</title>

            <para>
                Cet exemple suppose que vous utilisez les paramètres par défaut, ce qui
                inclut que toute redirection sera suivie d'un <methodname>exit()</methodname>
                immédiat.
            </para>

            <programlisting language="php"><![CDATA[
// EXEMPLE ALTERNATIF
class AlternativeController extends Zend_Controller_Action
{
    /**
     * Redirector - défini pour l'auto-complétion
     *
     * @var Zend_Controller_Action_Helper_Redirector
     */
    protected $_redirector = null;

    public function init()
    {
        $this->_redirector = $this->_helper->getHelper('Redirector');
    }

    public function myAction()
    {
        /* Faire quelquechose */

        $url = '/my-controller/my-action/param1/test/param2/test2';
        $this->_redirector->gotoUrl($url);
        return;
        // jamais atteint puisque les paramètres par défaut
        // sont à goto et exit
    }
}
]]></programlisting>
        </example>

        <example id="zend.controller.actionhelper.redirector.basicusage.example-3">
            <title>Utilisation de l'API _forward() de goto()</title>

            <para>
                L'<acronym>API</acronym> de <methodname>gotoSimple()</methodname> imite celle de
                <methodname>Zend_Controller_Action::_forward()</methodname>. La différence
                principale est qu'elle construit une <acronym>URL</acronym> à partir des paramètres
                fournis, et du format de route par défaut
                <filename>:module/:controller/:action/*</filename> du routeur. Il réalise
                alors une redirection au lieu d'enchaîner l'action.
            </para>

            <programlisting language="php"><![CDATA[
class ForwardController extends Zend_Controller_Action
{
    /**
     * Redirector - défini pour l'auto-complétion
     *
     * @var Zend_Controller_Action_Helper_Redirector
     */
    protected $_redirector = null;

    public function init()
    {
        $this->_redirector = $this->_helper->getHelper('Redirector');
    }

    public function myAction()
    {
        /* Faire quelquechose */

        // Redirige vers 'my-action' de 'my-controller' dans le module
        // courant en utilisant les paramètres :
        // param1 => test et param2 => test2
        $this->_redirector->gotoSimple('my-action',
                                       'my-controller',
                                       null,
                                       array('param1' => 'test',
                                             'param2' => 'test2'));
    }
}
]]></programlisting>
        </example>

        <example id="zend.controller.actionhelper.redirector.basicusage.example-4">
            <title>Utilisation de l'assemblage de la route avec gotoRoute()</title>

            <para>
                L'exemple suivant utilise la méthode <methodname>assemble()</methodname> du
                <link linkend="zend.controller.router">routeur</link>pour créer une
                <acronym>URL</acronym> basée sur un tableau associatif de paramètres fournis.
                Il suppose que la route suivante a été enregistrée&#160;:
            </para>

            <programlisting language="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'blog/:year/:month/:day/:id',
    array('controller' => 'archive',
          'module' => 'blog',
          'action' => 'view')
);
$router->addRoute('blogArchive', $route);
]]></programlisting>

            <para>
                En donnant un tableau avec l'année réglée à 2006, le mois à 4, le jour à 24
                et l'ID à 42, il construira l'<acronym>URL</acronym>
                <filename>/blog/2006/4/24/42</filename>.
            </para>

            <programlisting language="php"><![CDATA[
class BlogAdminController extends Zend_Controller_Action
{
    /**
     * Redirector - défini pour l'auto-complétion
     *
     * @var Zend_Controller_Action_Helper_Redirector
     */
    protected $_redirector = null;

    public function init()
    {
        $this->_redirector = $this->_helper->getHelper('Redirector');
    }

    public function returnAction()
    {
        /* Faire quelquechose */

        // Redirige vers les archives de blog. Construit l'URL suivante:
        // /blog/2006/4/24/42
        $this->_redirector->gotoRoute(
            array('year' => 2006, 'month' => 4, 'day' => 24, 'id' => 42),
            'blogArchive'
        );
    }
}
]]></programlisting>
        </example>
    </sect4>
</sect3>
