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

    <para>
        En plus des routes par défaut, et statique, les routes exprimées par expression
        régulière sont acceptées. Ces routes sont plus puissantes que les autres, mais aussi plus
        complexes à mettre en oeuvre et un peu plus lentes en matière d'analyse.
    </para>

    <para>
        Comme les routes standards, cette route doit être initialisée avec une définition et
        des valeurs par défaut. Créons par exemple avec une route "archive" en utilisant les routes
        par expressions régulières&#160;:
    </para>

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

    <para>
        Chaque motif d'expression régulière sera injecté dans l'objet de requête. Avec
        l'exemple ci-dessus, en utilisant <code>http://domain.com/archive/2006</code>, la tableau
        résultat devrait ressembler à&#160;:
    </para>

    <programlisting language="php"><![CDATA[
$values = array(
    1            => '2006',
    'controller' => 'archive',
    'action'     => 'show'
);
]]></programlisting>

    <note>
        <para>
            Les slashs de début et de fin sont supprimés de l'URL dans le routeur (avant
            l'intervention de la route).Ainsi, pour faire correspondre l'URL
            <code>http://domain.com/foo/bar/</code>, il faudra une expression du style
            <code>foo/bar</code>, et non pas <code>/foo/bar</code>.
        </para>
    </note>

    <note>
        <para>
            Les caractères de spécification de début et fin d'expression sont automatiquement
            rajoutés au motif ('^' et '$', respectivement). De ce fait, vous ne devriez pas les
            utiliser manuellement.
        </para>
    </note>

    <note>
        <para>
            Cette classe de route utilise le séparateur <code>#</code> comme délimiteur de
            motif. Vous devrez donc échapper ce caractère si vous l'utilisez, et non pas le slash
            (par défaut pour un motif d'expression régulière). Le caractère "#" est cependant
            rarement utilisé dans une <acronym>URL</acronym>.
        </para>
    </note>

    <para>Vous pouvez retourner le contenu des sous-masques&#160;:</para>

    <programlisting language="php"><![CDATA[
public function showAction()
{
    $request = $this->getRequest();
    $year    = $request->getParam(1); // $year = '2006';
}
]]></programlisting>

    <note>
        <para>Attention, la clé est un entier (1), et non une chaîne ('1').</para>
    </note>

    <para>
        Cette route ne fonctionnera pas encore tout à fait comme la route standard, car la
        valeur par défaut pour "<code>year</code>" n'est pas indiquée. Attention par contre, vous
        risquez d'avoir un problème avec les slashs finaux même si nous déclarons une valeur par
        défaut pour "<code>year</code>" et que celui-ci est facultatif. La solution consiste à
        traiter ce slash, mais sans le capturer&#160;:
    </para>

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

    <para>
        Nous voyons apparaître tout de même un problème : gérer des chiffres, comme clés pour
        les paramètres n'est pas très intuitif. C'est là qu'entre en jeu le troisième paramètre du
        constructeur de <classname>Zend_Controller_Router_Route_Regex</classname>. Il accepte un
        tableau faisant correspondre les numéros des paramètres et leur nom respectif&#160;:
    </para>

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

    <para>Les valeurs suivantes seront injectées dans l'objet de requête&#160;:</para>

    <programlisting language="php"><![CDATA[
$values = array(
    'year'       => '2006',
    'controller' => 'archive',
    'action'     => 'show'
);
]]></programlisting>

    <para>Il est aussi possible d'inverser les clé et valeurs du tableau&#160;:</para>

    <programlisting language="php"><![CDATA[
$route = new Zend_Controller_Router_Route_Regex(
    'archive/(\d+)',
    array( ... ),
    array(1 => 'year')
);

// OU

$route = new Zend_Controller_Router_Route_Regex(
    'archive/(\d+)',
    array( ... ),
    array('year' => 1)
);
]]></programlisting>

    <note>
        <para>Attention de toujours manipuler des entiers (1 et non "1")</para>
    </note>

    <para>
        Si vous inversez comme dans le deuxième cas de l'exemple ci-dessus, la clé alors
        reçue par l'objet de requête ne représente plus un chiffre, mais le nom du paramètre. Vous
        pouvez évidemment mixer les comportements&#160;:
    </para>

    <programlisting language="php"><![CDATA[
$route = new Zend_Controller_Router_Route_Regex(
    'archive/(\d+)/page/(\d+)',
    array( ... ),
    array('year' => 1)
);
]]></programlisting>

    <para>
        Si nous appelons l'URL <code>http://domain.com/archive/2006/page/10</code> avec la
        route définie ci-dessus, les paramètres trouvés seront&#160;:
    </para>

    <programlisting language="php"><![CDATA[
$values = array(
    'year'       => '2006',
    2            => 10,
    'controller' => 'archive',
    'action'     => 'show'
);
]]></programlisting>

    <para>
        Étant donné que les route par expression régulière ne sont pas facilement réversible,
        vous devrez préparer le motif vous-même dans le but d'utiliser l'aide de vue "url". Ce
        chemin inverse doit être défini comme une chaîne traitable par la fonction
        <methodname>sprintf()</methodname> de <acronym>PHP</acronym>, et définie en quatrième paramètre du constructeur de la
        route Regex&#160;:
    </para>

    <programlisting language="php"><![CDATA[
$route = new Zend_Controller_Router_Route_Regex(
    'archive/(\d+)',
    array( ... ),
    array('year' => 1),
    'archive/%s'
);
]]></programlisting>

    <para>
        Quels sont donc les avantages des routes par expressions régulières (Regex)&#160;? C'est
        que vous pouvez décrire n'importe quelle <acronym>URL</acronym> avec. Imaginez un blog, vous voulez créer des
        <acronym>URL</acronym>s du type <code>http://domain.com/blog/archive/01-Using_the_Regex_Router.html</code>,
        afin de décomposer la dernière partie de l'URL en un ID d'article, et un cours texte
        descriptif (<code>01-Using_the_Regex_Router.html</code>). Ceci n'est pas possible avec la
        route standard. En revanche, avec la route Regex, vous pouvez écrire&#160;:
    </para>

    <programlisting language="php"><![CDATA[
$route = new Zend_Controller_Router_Route_Regex(
    'blog/archive/(\d+)-(.+)\.html',
    array(
        'controller' => 'blog',
        'action'     => 'view'
    ),
    array(
        1 => 'id',
        2 => 'description'
    ),
    'blog/archive/%d-%s.html'
);
$router->addRoute('blogArchive', $route);
]]></programlisting>

    <para>
        Comme vous le voyez, ce type de route ajoute une solution flexible concernant la
        gestion des <acronym>URL</acronym>s et leur routage.
    </para>
</sect3>