Zend_Controller_Router_Route 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'URL, statique ou dynamique, et des valeurs par défaut peuvent être fournies, de même que des valeurs obligatoires.

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

$route = new Zend_Controller_Router_Route(
    'auteur/:username',
    array(
        'controller' => 'profile',
        'action'     => 'userinfo'
    )
);

$router->addRoute('user', $route);

Le premier paramètre du constructeur de Zend_Controller_Router_Route est la définition de la route à analyser avec l'URL. 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 : auteur. Les dynamiques, appelées variables, sont repérées grâce à un caractère deux-points (:) devant la variable : :username.

Note: Utilisation des caractères
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 PHP comprend comme étant des noms de variables valides. Les implémentations futures de ce comportement peuvent changer, altérant ainsi votre code.

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

$values = array(
    'username'   => 'martel',
    'controller' => 'profile',
    'action'     => 'userinfo'
);

Plus tard, Zend_Controller_Dispatcher_Standard va distribuer vers la méthode userinfoAction() de ProfileController (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 à Zend_Controller_Action::_getParam() ou Zend_Controller_Request::getParam() :

public function userinfoAction()
{
    $request = $this->getRequest();
    $username = $request->getParam('username');

    $username = $this->_getParam('username');
}

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" :

$route = new Zend_Controller_Router_Route(
    ':module/:controller/:action/*',
    array('module' => 'default')
);
$router->addRoute('default', $route);

$route = new Zend_Controller_Router_Route(
    'archive/:annee',
    array('annee' => 2006)
);
$router->addRoute('archive', $route);

$route = new Zend_Controller_Router_Route(
    'archive/:annee',
    array(
        'annee'       => 2006,
        'controller' => 'archive',
        'action'     => 'show'
    )
);
$router->addRoute('archive', $route);

$route = new Zend_Controller_Router_Route(
    'archive/:annee',
    array(
        'annee'       => 2006,
        'controller' => 'archive',
        'action'     => 'show'
    ),
    array('year' => '\d+')
);
$router->addRoute('archive', $route);

Les exemples ci-dessus utilisent des routes dynamiques - routes qui contiennent des motifs pour chercher des correspondances. Seulement, parfois, une route particulière est marquée en dur, et mettre en marche le moteur d'expression régulière serait inutile. La réponse à cette situation est l'utilisation de routes statiques :

$route = new Zend_Controller_Router_Route_Static(
    'login',
    array('controller' => 'auth', 'action' => 'login')
);
$router->addRoute('login', $route);

La route ci-dessus correspond à l'URL http://domain.com/login, et distribue l'action AuthController::loginAction().

Note: ATTENTION : Les routes statiques doivent contenir des valeurs par défaut saines
Puisqu'une route statique ne fournit aucune partie de l'URL à l'objet de requête en tant que paramètres, vous devez fournir par défaut pour la route tous les paramètres nécessaires à la distribution de la requête. Oubliez les valeurs par défaut de "controller" ou "action" entraînera des résultats non attendus, et peut-être une requête non-distribuable.
En général, fournissez toujours chacune des valeurs par défaut suivantes :

• controller

• action

• module (si différent de "default")

Optionnellement, vous pouvez activer le paramètre "useDefaultControllerAlways" du contrôleur frontal lors de l'amorçage :

$front->setParam('useDefaultControllerAlways', true);

Cependant, ceci est considéré comme un contournement ; il vaut toujours mieux définir explicitement des valeurs par défaut saines.

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.

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 :

$route = new Zend_Controller_Router_Route_Regex(
    'archive/(\d+)',
    array(
        'controller' => 'archive',
        'action'     => 'show'
    )
);
$router->addRoute('archive', $route);

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

$values = array(
    1            => '2006',
    'controller' => 'archive',
    'action'     => 'show'
);

Note: 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 http://domain.com/foo/bar/, il faudra une expression du style foo/bar, et non pas /foo/bar.

Note: 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.

Note: Cette classe de route utilise le séparateur # 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 URL.

Vous pouvez retourner le contenu des sous-masques :

public function showAction()
{
    $request = $this->getRequest();
    $year    = $request->getParam(1); // $year = '2006';
}

Note: Attention, la clé est un entier (1), et non une chaîne ('1').

Cette route ne fonctionnera pas encore tout à fait comme la route standard, car la valeur par défaut pour "year" 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 "year" et que celui-ci est facultatif. La solution consiste à traiter ce slash, mais sans le capturer :

$route = new Zend_Controller_Router_Route_Regex(
    'archive(?:/(\d+))?',
    array(
        1    '       => '2006',
        'controller' => 'archive',
        'action'     => 'show'
    )
);
$router->addRoute('archive', $route);

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 Zend_Controller_Router_Route_Regex. Il accepte un tableau faisant correspondre les numéros des paramètres et leur nom respectif :

$route = new Zend_Controller_Router_Route_Regex(
    'archive/(\d+)',
    array(
        'controller' => 'archive',
        'action' => 'show'
    ),
    array(
        1 => 'year'
    )
);
$router->addRoute('archive', $route);

Les valeurs suivantes seront injectées dans l'objet de requête :

$values = array(
    'year'       => '2006',
    'controller' => 'archive',
    'action'     => 'show'
);

Il est aussi possible d'inverser les clé et valeurs du tableau :

$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)
);

Note: Attention de toujours manipuler des entiers (1 et non "1")

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 :

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

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

$values = array(
    'year'       => '2006',
    2            => 10,
    'controller' => 'archive',
    'action'     => 'show'
);

É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 sprintf() de PHP, et définie en quatrième paramètre du constructeur de la route Regex :

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

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

$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);

Comme vous le voyez, ce type de route ajoute une solution flexible concernant la gestion des URLs et leur routage.

Zend_Controller_Router_Route_Hostname est la route par nom d'hôte du framework. Elle fonctionne de la même manière que la route standard, mais elle utilise le nom d'hôte de l'URL appelé au lieu du chemin.

Utilisons l'exemple d'une route standard et regardons ce que cela donnerais en utilisant le nom d'hôte. Au lieu d'appeler l'utilisateur par le chemin, nous voulons être capable d'appeler http://toto.users.example.com pour voir les informations concernant l'utilisateur "toto" 

$hostnameRoute = new Zend_Controller_Router_Route_Hostname(
    ':username.users.example.com',
    array(
        'controller' => 'profile',
        'action'     => 'userinfo'
    )
);

$plainPathRoute = new Zend_Controller_Router_Route_Static('');

$router->addRoute('user', $hostnameRoute->chain($plainPathRoute);

Le premier paramètre dans le constructeur Zend_Controller_Router_Route_Hostname est la définition d'une route qui correspondra à un nom d'hôte. Les définitions de route consistent en des parties statiques et des parties dynamiques séparées par le caractère point ("."). Les parties dynamiques, appelées variables, sont marquées en précédant le nom de variable par le caractère deux-points (":") : :username. Les parties statiques sont de simples textes : user.

Les routes par nom d'hôtes peuvent, mais ne devraient pas être utilisées comme ceci. La raison à cela est que qu'une route par nom d'hôte seule ne correspondra à aucun chemin. Donc vous devez donc chaîner le chemin d'une route à une route par nom d'hôte. Ceci est réalisé comme dans l'exemple ci-dessous en appelant $hostnameRoute->chain($pathRoute);. En faisant ceci, $hostnameRoute n'est pas modifié, mais une nouvelle route (Zend_Controller_Router_Route_Chain) est retournée, qui peut ainsi être fournie au routeur.

Zend_Controller_Router_Route_Chain is a route which allows to chain multiple routes together. This allows you to chain hostname-routes and path routes, or multiple path routes for example. Chaining can be done either programatically or within a configuration file.

Note: Parameter Priority
When chaining routes together, the parameters of the outer route have a higher priority than the parameters of the inner route. Thus if you define a controller in the outer and in the inner route, the controller of the outer route will be selected.

When chaining programatically, there are two ways to achieve this. The first one is to create a new Zend_Controller_Router_Route_Chain instance and then calling the chain method multiple times with all routes which should be chained together. The other way is to take the first route, e.g. a hostname route, and calling the chain method on it with the route which should be appended to it. This will not modify the hostname route, but return a new instance of Zend_Controller_Router_Route_Chain, which then has both routes chained together:

// Create two routes
$hostnameRoute = new Zend_Controller_Router_Route_Hostname(...);
$pathRoute     = new Zend_Controller_Router_Route(...);

// First way, chain them via the chain route
$chainedRoute = new Zend_Controller_Router_Route_Chain();
$chainedRoute->chain($hostnameRoute)
             ->chain($pathRoute);

// Second way, chain them directly
$chainedRoute = $hostnameRoute->chain($pathRoute);

When chaining routes together, their default separator is a slash by default. There may be cases when you want to have a different separator:

// Create two routes
$firstRoute  = new Zend_Controller_Router_Route('foo');
$secondRoute = new Zend_Controller_Router_Route('bar');

// Chain them together with a different separator
$chainedRoute = $firstRoute->chain($secondRoute, '-');

// Assemble the route: "foo-bar"
echo $chainedRoute->assemble();

<routes>
    <www type="Zend_Controller_Router_Route_Hostname">
        <route>www.example.com</route>
        <chains>
            <language type="Zend_Controller_Router_Route">
                <route>:language</route>
                <reqs language="[a-z]{2}">
                <chains>
                    <index type="Zend_Controller_Router_Route_Static">
                        <route></route>
                        <defaults module="default" controller="index" action="index" />
                    </index>
                    <imprint type="Zend_Controller_Router_Route_Static">
                        <route>imprint</route>
                        <defaults module="default" controller="index" action="index" />
                    </imprint>
                </chains>
            </language>
        </chains>
    </www>
    <users type="Zend_Controller_Router_Route_Hostname">
        <route>users.example.com</route>
        <chains>
            <profile type="Zend_Controller_Router_Route">
                <route>:username</route>
                <defaults module="users" controller="profile" action="index" />
            </profile>
        </chains>
    </users>
    <misc type="Zend_Controller_Router_Route_Static">
        <route>misc</route>
    </misc>
</routes>

<routes>
    <www type="Zend_Controller_Router_Route_Chain">
        <route>www.example.com</route>
    </www>
    <language type="Zend_Controller_Router_Route">
        <route>:language</route>
        <reqs language="[a-z]{2}">
    </language>
    <index type="Zend_Controller_Router_Route_Static">
        <route></route>
        <defaults module="default" controller="index" action="index" />
    </index>
    <imprint type="Zend_Controller_Router_Route_Static">
        <route>imprint</route>
        <defaults module="default" controller="index" action="index" />
    </imprint>

    <www-index type="Zend_Controller_Router_Route_Chain">
        <chain>www, language, index</chain>
    </www-index>
    <www-imprint type="Zend_Controller_Router_Route_Chain">
        <chain>www, language, imprint</chain>
    </www-imprint>
</routes>

<routes>
    <www-index type="Zend_Controller_Router_Route_Chain">
        <chain>www</chain>
        <chain>language</chain>
        <chain>index</chain>
    </www-index>
    <www-imprint type="Zend_Controller_Router_Route_Chain">
        <chain>www</chain>
        <chain>language</chain>
        <chain>imprint</chain>
    </www-imprint>
</routes>