<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect3 id="zend.controller.router.routes.standard">
    <title>Zend_Controller_Router_Route</title>

    <para>
        <classname>Zend_Controller_Router_Route</classname> est la route par défaut intégrée
        dans le routeur de réécriture (RewriteRouter). Ce routeur combine les deux avantages que
        sont la simplicité d'utilisation et la flexibilité. Chaque route est définie par une
        correspondance d'<acronym>URL</acronym>, statique ou dynamique, et des valeurs par défaut
        peuvent être fournies, de même que des valeurs obligatoires.
    </para>

    <para>
        Imaginons une application ayant besoin de posséder une page en décrivant l'auteur.
        Nous voulons que lorsque le navigateur pointe vers
        <filename>http://domaine.fr/auteur/martel</filename>, la page d'informations en question
        puisse apparaître, au sujet de "martel". La route pour une telle <acronym>URL</acronym>
        pourrait être&#160;:
    </para>

    <programlisting language="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'auteur/:username',
    array(
        'controller' => 'profile',
        'action'     => 'userinfo'
    )
);

$router->addRoute('user', $route);
]]></programlisting>

    <para>
        Le premier paramètre du constructeur de <classname>Zend_Controller_Router_Route</classname>
        est la définition de la route à analyser avec l'<acronym>URL</acronym>. Les définitions
        des routes sont des parties statiques et dynamiques, séparées par des slashs ("/").
        Les parties statiques sont juste du texte brut&#160;: <emphasis>auteur</emphasis>. Les
        dynamiques, appelées variables, sont repérées grâce à un caractère
        deux-points (:) devant la variable&#160;: <emphasis>:username</emphasis>.
    </para>

    <note>
        <title>Utilisation des caractères</title>
        <para>
            Pour identifier une variable dans un schéma de routage (après le deux-points), en
            théorie n'importe quel caractère fait l'affaire (sauf le slash "/"). Cependant il est
            conseillé de n'utiliser que des caractères que <acronym>PHP</acronym> comprend comme
            étant des noms de variables valides. Les implémentations futures de ce comportement
            peuvent changer, altérant ainsi votre code.
        </para>
    </note>

    <para>
        Cette route exemple devrait être utilisée lorsque le navigateur pointe vers
        <filename>http://domaine.fr/auteur/martel</filename>, et dans un tel cas, tous les
        paramètres de la requête seront injectés dans l'objet
        <classname>Zend_Controller_Request</classname> et
        seront accessibles à travers votre <classname>ProfileController</classname>. Les variables
        retournées par cet exemple peuvent être représentées par le tableau suivant&#160;:
    </para>

    <programlisting language="php"><![CDATA[
$values = array(
    'username'   => 'martel',
    'controller' => 'profile',
    'action'     => 'userinfo'
);
]]></programlisting>

    <para>
        Plus tard, <classname>Zend_Controller_Dispatcher_Standard</classname> va distribuer
        vers la méthode <methodname>userinfoAction()</methodname> de
        <classname>ProfileController</classname> (dans le module par défaut) selon ces valeurs.
        A cet endroit, il sera possible d'accéder à toutes les variables de la requête grâce à
        <methodname>Zend_Controller_Action::_getParam()</methodname> ou
        <methodname>Zend_Controller_Request::getParam()</methodname>&#160;:
    </para>

    <programlisting language="php"><![CDATA[
public function userinfoAction()
{
    $request = $this->getRequest();
    $username = $request->getParam('username');

    $username = $this->_getParam('username');
}
]]></programlisting>

    <para>
        La définition des routes peut contenir un ou plusieurs caractères spéciaux - des
        jokers - représentés par le symbole '*'. Il est utilisé pour collecter des paramètres.
        L'exemple suivant représente plus ou moins le comportement par défaut de la route
        "Module"&#160;:
    </para>

    <programlisting language="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    ':module/:controller/:action/*',
    array('module' => 'default')
);
$router->addRoute('default', $route);
]]></programlisting>

    <sect4 id="zend.controller.router.routes.standard.variable-defaults">

        <title>Variables par défaut</title>

        <para>
            Chaque variable dynamique dans la définition des routes peut avoir une valeur par
            défaut. C'est à cela que sert le second paramètre du constructeur de
            <classname>Zend_Controller_Router_Route</classname>. Il s'agit d'un tableau avec comme
            clés les noms des variables, et comme valeurs, leurs valeurs par défaut&#160;:
        </para>

        <programlisting language="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'archive/:annee',
    array('annee' => 2006)
);
$router->addRoute('archive', $route);
]]></programlisting>

        <para>
            L'exemple ci-dessus établira une correspondance avec les <acronym>URL</acronym> comme
            <filename>http://domaine.fr/archive/2005</filename> et
            <filename>http://exemple.fr/archive</filename>. Dans ce dernier cas, la variable de
            l'année (<emphasis>annee</emphasis>) aura la valeur 2006.
        </para>

        <para>
            L'exemple ci-dessus injecte ainsi un paramètre représentant une année
            (<emphasis>annee</emphasis>). Si aucune information de contrôleur ou d'actions n'est
            présente, alors ceux par défaut seront utilisés (ils sont définis dans
            <classname>Zend_Controller_Dispatcher_Abstract</classname>). Pour que l'exemple soit
            plus intuitif, spécifions des paires contrôleur et action par défaut dans notre
            route&#160;:
        </para>

        <programlisting language="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'archive/:annee',
    array(
        'annee'       => 2006,
        'controller' => 'archive',
        'action'     => 'show'
    )
);
$router->addRoute('archive', $route);
]]></programlisting>

        <para>
            Cette route va alors donner une distribution vers la méthode
            <methodname>showAction()</methodname> de <classname>ArchiveController</classname>.
        </para>

    </sect4>

    <sect4 id="zend.controller.router.routes.standard.variable-requirements">

        <title>Obligations et contraintes des variables</title>

        <para>
            Vous pouvez ajouter un troisième paramètre au constructeur de
            <classname>Zend_Controller_Router_Route</classname> pour spécifier une variable
            obligatoire. Ceci s'effectue au moyen d'expressions régulières&#160;:
        </para>

        <programlisting language="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'archive/:annee',
    array(
        'annee'       => 2006,
        'controller' => 'archive',
        'action'     => 'show'
    ),
    array('year' => '\d+')
);
$router->addRoute('archive', $route);
]]></programlisting>

        <para>
            Avec une telle définition de route, comme ci-dessus, le routeur n'établira une
            correspondance que si la variable "<emphasis>annee</emphasis>" contient une donnée
            numérique&#160;: <filename>http://domaine.fr/archive/2345</filename>. Une
            <acronym>URL</acronym> comme <filename>http://exemple.annee/archive/test</filename>
            ne sera pas captée (matchée) par cette route, et le contrôle sera passé à la route
            suivante, etc.
        </para>
    </sect4>

    <sect4 id="zend.controller.router.routes.standard.translated-segments">
        <title>Translated segments</title>

        <para>
            The standard route supports translated segments. To use this
            feature, you have to define at least a translator (an instance
            of <classname>Zend_Translate</classname>) via one of the following ways:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Put it into the registry with the key <classname>Zend_Translate</classname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    Set it via the static method
                    <methodname>Zend_Controller_Router_Route::setDefaultTranslator()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    Pass it as fourth parameter to the constructor.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            By default, the locale specified in the <classname>Zend_Translate</classname>
            instance will be used. To override it, you set it
            (an instance of <classname>Zend_Locale</classname> or a locale string) in one
            of the following ways:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Put it into the registry with the key <classname>Zend_Locale</classname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    Set it via the static method
                    <methodname>Zend_Controller_Router_Route::setDefaultLocale()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    Pass it as fifth parameter to the constructor.
                </para>
            </listitem>

            <listitem>
                <para>
                    Pass it as <command>@locale</command> parameter to the assemble
                    method.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Translated segments are separated into two parts. Fixed segments
            are prefixed by a single <emphasis>@</emphasis>-sign, and will be
            translated to the current locale when assembling and reverted
            to the message ID when matching again. Dynamic segments
            are prefixed by <command>:@</command>. When assembling, the given
            parameter will be translated and inserted into the parameter
            position. When matching, the translated parameter from the
            <acronym>URL</acronym> will be reverted to the message ID again.
        </para>

        <note>
            <title>Message IDs and separate language file</title>

            <para>
                Occasionally a message ID which you want to use in one
                of your routes is already used in a view script or somewhere
                else. To have full control over safe <acronym>URL</acronym>s, you should use
                a separate language file for the messages used in the route.
            </para>
        </note>

        <para>
            The following is the simplest way to prepare the standard route for
            translated segment usage:
        </para>

        <programlisting language="php"><![CDATA[
// Prepare the translator
$translator = new Zend_Translate(
    array(
        'adapter' => 'array',
        'content' => array(),
        'locale'  => 'en'
    )
);
$translator->addTranslation(
    array(
        'content' =>
            array(
                'archive' => 'archiv',
                'year'    => 'jahr',
                'month'   => 'monat',
                'index'   => 'uebersicht'
            ),
        'locale'  => 'de'
    )
);

// Set the current locale for the translator
$translator->setLocale('en');

// Set it as default translator for routes
Zend_Controller_Router_Route::setDefaultTranslator($translator);
]]></programlisting>

        <para>
            This example demonstrates the usage of static segments:
        </para>

        <programlisting language="php"><![CDATA[
// Create the route
$route = new Zend_Controller_Router_Route(
    '@archive',
    array(
        'controller' => 'archive',
        'action'     => 'index'
    )
);
$router->addRoute('archive', $route);

// Assemble the URL in default locale: archive
$route->assemble(array());

// Assemble the URL in german: archiv
$route->assemble(array());
]]></programlisting>

        <para>
            You can use the dynamic segments to create a module-route like
            translated version:
        </para>

        <programlisting language="php"><![CDATA[
// Create the route
$route = new Zend_Controller_Router_Route(
    ':@controller/:@action/*',
    array(
        'controller' => 'index',
        'action'     => 'index'
    )
);
$router->addRoute('archive', $route);

// Assemble the URL in default locale: archive/index/foo/bar
$route->assemble(array('controller' => 'archive', 'foo' => 'bar'));

// Assemble the URL in german: archiv/uebersicht/foo/bar
$route->assemble(array('controller' => 'archive', 'foo' => 'bar'));
]]></programlisting>

        <para>
            You can also mix static and dynamic segments:
        </para>

        <programlisting language="php"><![CDATA[
// Create the route
$route = new Zend_Controller_Router_Route(
    '@archive/:@mode/:value',
    array(
        'mode'       => 'year'
        'value'      => 2005,
        'controller' => 'archive',
        'action'     => 'show'
    ),
    array('mode'  => '(month|year)'
          'value' => '\d+')
);
$router->addRoute('archive', $route);

// Assemble the URL in default locale: archive/month/5
$route->assemble(array('mode' => 'month', 'value' => '5'));

// Assemble the URL in german: archiv/monat/5
$route->assemble(array('mode' => 'month', 'value' => '5', '@locale' => 'de'));
]]></programlisting>
    </sect4>
</sect3>