Introduction

Zend_Controller_Router_Rewrite est le routeur par défaut du framework. Le routage consiste à analyser l'URI définie (la partie après l'URL de base) et la décomposer en valeurs déterminant quels module, contrôleur et action doivent recevoir la requête. Ces valeurs sont encapsulées dans un objet de requête Zend_Controller_Request_Http qui est alors injecté dans Zend_Controller_Dispatcher_Standard pour y être traité Le routage n'est effectué qu'une seule fois par requête : juste avant que le premier contrôleur ne soit traité (distribué)

Zend_Controller_Router_Rewrite intervient pour fournir un environnement de requête similaire à "mod_rewrite", tout en utilisant uniquement du PHP. Il est désigné sur les principes de Ruby on Rails et ne requière pas de connaissances particulières en réécriture d'URL. Il est destiné à fonctionner avec une seule règle de réécriture Apache, dont voici des exemples :

RewriteEngine on
RewriteRule !\.(js|ico|gif|jpg|png|css|html)$ index.php

ou (recommandé) :

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ index.php [NC,L]

Le routeur de réécriture peut aussi être utilisé avec un serveur Web IIS (versions <= 7.0) si » Isapi_Rewrite a été installée comme une extension Isap avec la règle suivante :

RewriteRule ^[\w/\%]*(?:\.(?!(?:js|ico|gif|jpg|png|css|html)$)[\w\%]*$)? /index.php [I]

Note: IIS Isapi_Rewrite
Lorsque IIS est utilisé, $_SERVER['REQUEST_URI'] n'existera pas ou vaudra une chaîne vide. Dans ce cas, Zend_Controller_Request_Http essaiera d'utiliser la valeur de $_SERVER['HTTP_X_REWRITE_URL'], initialisée par l'extension Isapi_Rewrite.

IIS 7.0 introduit un moodule de réécriture d'URL natif, et il peut être configuré comme ceci :

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
     <system.webServer>
         <rewrite>
             <rules>
                 <rule name="Imported Rule 1" stopProcessing="true">
                     <match url="^.*$" />
                     <conditions logicalGrouping="MatchAny">
                         <add input="{REQUEST_FILENAME}"
                             matchType="IsFile" pattern=""
                             ignoreCase="false" />
                         <add input="{REQUEST_FILENAME}"
                             matchType="IsDirectory"
                             pattern="" ignoreCase="false" />
                     </conditions>
                     <action type="None" />
                 </rule>
                 <rule name="Imported Rule 2" stopProcessing="true">
                     <match url="^.*$" />
                     <action type="Rewrite" url="index.php" />
                 </rule>
             </rules>
         </rewrite>
     </system.webServer>
</configuration>

Si vous utilisez Lighttpd, la règle de réécriture suivante est valide :

url.rewrite-once = (
    ".*\?(.*)$" => "/index.php?$1",
    ".*\.(js|ico|gif|jpg|png|css|html)$" => "$0",
    "" => "/index.php"
)

Utilisation d'un routeur

Pour utiliser un routeur et le configurer, vous devez le récupérer et ajouter des routes :

/* Créer un routeur */
$router = $frontctrl->getRouter();
// retourne un routeur de réécriture par défaut
$router->addRoute(
    'user',
    new Zend_Controller_Router_Route('user/:username',
                                     array('controller' => 'user',
                                           'action' => 'info'))
);

Utilisation basique du routeur de réécriture

Le coeur de ce routeur repose sur le concept de routes personnalisées. Les routes sont ajoutées en appelant la méthode addRoute() et en lui passant une instance implémentant Zend_Controller_Router_Route_Interface. Exemple :

$router->addRoute('user',
                  new Zend_Controller_Router_Route('user/:username'));

Le routeur de réécriture est fourni avec six types de route, dont une spéciale :

Chaque route peut être utilisée plusieurs fois pour créer un chaîne de routes représentant un schéma de routage personnalisé. La route du module, en revanche, ne devrait être utilisée qu'une seule fois, elle est en générale la route la plus générique (par défaut). Chaque route sera définie un peu plus tard.

Le premier paramètre de addRoute est le nom de la route. Il sera utilisé plus tard pour la sélectionner (par exemple pour générer un URL. Le deuxième paramètre étant l'objet route lui-même.

Note: L'utilisation la plus plausible du nom de la route est illustrée dans l'aide vue "url" :

<a href="<?php echo $this->url(array('username' => 'martel'), 'user') ?>">

Martel

</a>
Ce qui donnera un "href" : user/martel.

Le routage consiste simplement à itérer toutes les routes reçues et à les faire correspondre à l'URI de la requête courante. Dès qu'une correspondance est établie, les variables sont injectées dans l'objet Zend_Controller_Request utilisé après dans le distributeur et dans les contrôleurs. Si aucune correspondance n'est trouvée, la route suivante dans la pile est analysée.

Si vous devez déterminer quelle route a été trouvée, vous pouvez utilisez la méthode getCurrentRouteName(), qui vous retournera l'identifiant utilisé pour enregistrer la route dans le routeur. Si vous souhaitez récupérer l'objet de la route actuelle, vous pouvez utiliser getCurrentRoute().

Note: Pile LIFO
Les routes sont analysées dans l'ordre LIFO : dernière fournie, première analysée. Veillez à définir les routes les génériques en premier donc.

Note: Paramètres de la requête
Les paramètres de la requête proviennent de l'utilisateur, ou des routes définies. Ils seront plus tard accessibles via Zend_Controller_Request::getParam() ou la méthode Zend_Controller_Action::_getParam().

Il y a trois valeurs spéciales qui peuvent être utilisées dans la définition de vos routes : - "module", "controller" et "action" -. Ces valeurs sont utilisées par Zend_Controller_Dispatcher pour trouver les contrôleurs et action à distribuer.

Note: Valeurs spéciales
Le nom de ces valeurs peut être changé dans Zend_Controller_Request_Http avec les méthodes setControllerKey et setActionKey.

Routes par défaut

Zend_Controller_Router_Rewrite possède des routes par défaut qui vont correspondre pour des URI du type controller/action. De plus, un nom de module peut être spécifié comme premier élément du chemin, autorisant ainsi des URI du type module/controller/action. Enfin, chaque paramètres de la requête sera trouvé à la fin de la requête, comme controller/action/var1/value1/var2/value2.

Exemples avec ces routes :

// Considérons :
$ctrl->setControllerDirectory(
    array(
        'default' => '/path/to/default/controllers',
        'news'    => '/path/to/news/controllers',
        'blog'    => '/path/to/blog/controllers'
    )
);
 
Module seulement:
http://example/news
    module == news
 
Un module invalide dirige vers le contrôleur:
http://example/foo
    controller == foo
 
Module + controller:
http://example/blog/archive
    module     == blog
    controller == archive
 
Module + controller + action:
http://example/blog/archive/list
    module     == blog
    controller == archive
    action     == list
 
Module + controller + action + params:
http://example/blog/archive/list/sort/alpha/date/desc
    module     == blog
    controller == archive
    action     == list
    sort       == alpha
    date       == desc

La route par défaut est simplement un objet Zend_Controller_Router_Route_Module, stocké sous le nom "default" dans le routeur de réécriture(RewriteRouter). Il est conçu comme ceci :

$compat = new Zend_Controller_Router_Route_Module(array(),
                                                  $dispatcher,
                                                  $request);
$this->addRoute('default', $compat);

Si vous ne souhaitez pas cette route par défaut, créez en une et stocker la avec le nom "default" (écrasement), ou supprimez la route avec removeDefaultRoutes() :

// Supprime les routes par défaut
$router->removeDefaultRoutes();

Base URL et sous dossiers

Le routeur de réécriture peut être utilisé dans des sous dossiers (comme http://domain.com/~user/application-root/), dans un tél cas, l'URL de base de l'application (/~user/application-root) devrait être automatiquement détectée par Zend_Controller_Request_Http et utilisée ensuite.

Si ça n'était pas le cas, vous pouvez spécifier votre propre base URL dans Zend_Controller_Request_Http en appelant setBaseUrl() (voyez Base de l'URL et sous-dossiers) :

$request->setBaseUrl('/~user/application-root/');

Paramètres globaux

Vous pouvez régler des paramètres globaux dans un routeur, qui sont automatiquement fournis à la route lors de son assemblage, grâce à la fonction setGlobalParam(). Si un paramètre global est réglé mais qu'il est aussi fourni directement à la méthode d'assemblage, le paramètre utilisateur écrase le paramètre global. Vous pouvez régler un paramètre global de cette manière :

$router->setGlobalParam('lang', 'en');

Types de route

Zend_Controller_Router_Route

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

Variables par défaut

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 Zend_Controller_Router_Route. Il s'agit d'un tableau avec comme clés les noms des variables, et comme valeurs, leurs valeurs par défaut :

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

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

L'exemple ci-dessus injecte ainsi un paramètre représentant une année (annee). 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 Zend_Controller_Dispatcher_Abstract). Pour que l'exemple soit plus intuitif, spécifions des paires contrôleur et action par défaut dans notre route :

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

Cette route va alors donner une distribution vers la méthode showAction() de ArchiveController.

Obligations et contraintes des variables

Vous pouvez ajouter un troisième paramètre au constructeur de Zend_Controller_Router_Route pour spécifier une variable obligatoire. Ceci s'effectue au moyen d'expressions régulières :

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

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

Zend_Controller_Router_Route_Static

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.

Zend_Controller_Router_Route_Regex

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

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

Zend_Controller_Router_Route_Chain est une route permettant le chainage d'autres routes. Ceci permet de chainer des routes hostnames à des routes de chemin, ou de multiples routes de chemin entre elles, par exemple. Le chainage se configure via des méthodes ou un fichier de configuration.

Note: Priorité des paramètres
En chainant des routes entre elles, les paramètres de la route la plus externe (la plus proche) ont une prioprité supérieure aux paramètres des routes les plus internes (encapsulées). Définir un contrôleur dans la route externe, puis dans la route interne, c'est celui de la route externe qui sera sélectionné.

En réalisant le chainage via les méthodes, il existe 2 manières de procéder. La première est de créer un objet Zend_Controller_Router_Route_Chain puis d'appeler la méthode chain() plusieurs fois en lui passant les routes à chainer. La deuxième méthode consiste à créer la première route, par exemple une route hostname, puis d'appeler sa méthode chain() en passant comme paramètre la route qui devrait être ajoutée. Ceci ne modifiera pas la route hostname, mais retournera une instance de Zend_Controller_Router_Route_Chain possédant les 2 routes chainées:

// Créer deux routes
$hostnameRoute = new Zend_Controller_Router_Route_Hostname(...);
$pathRoute     = new Zend_Controller_Router_Route(...);
 
// Première méthode, utiliser l'objet de chainage
$chainedRoute = new Zend_Controller_Router_Route_Chain();
$chainedRoute->chain($hostnameRoute)
             ->chain($pathRoute);
 
// Deuxième méthode, chainage direct
$chainedRoute = $hostnameRoute->chain($pathRoute);

Le chainage utilise le slash comme séparateur par défaut entre les routes. Pour utiliser un séparateur différent, procédez comme suite:

// Créer deux routes
$firstRoute  = new Zend_Controller_Router_Route('foo');
$secondRoute = new Zend_Controller_Router_Route('bar');
 
// Chainer les routes avec un séparateur particulier
$chainedRoute = $firstRoute->chain($secondRoute, '-');
 
// Assemble la route: "foo-bar"
echo $chainedRoute->assemble();

Chainer des routes via Zend_Config

Pour chainer les route grâce à un fichier de configuration, il faut considérer des paramètres additionnels. L'approche la plus simple consiste à utiliser les paramètres de la section chains. Il s'agit simplement d'une liste de routes qui seront chainées à la route parente. Ce n'est ni le parent, ni un des enfants qui sera ajouté au routeur, mais bien le résultat de la chaine générale. Le nom de cette chaine dans le routeur sera constitué du nom de la route parente séparé du nom des enfants par un tiret (-) par défaut. Voici un exemple:

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

Le résultat sera 3 routes www-language-index, www-language-imprint et users-language-profile qui seront utilisées en fonction du nom d'hote et de la route misc, qui elle sera utilisée pour tout nom d'hôte.

Autre manière de faire : utiliser les nom des routes directement. Cela ne peut se faire que pour le niveau racine:

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

On peut aussi passer un tableau à chain plutôt que les noms de route séparés par des virgules:

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

Pour spécifier le séparateur de routes avec Zend_Config , agissez comme suit:

$config = new Zend_Config(array(
    'chainName' => array(
        'type'   => 'Zend_Controller_Router_Route_Static',
        'route'  => 'foo',
        'chains' => array(
            'subRouteName' => array(
                'type'     => 'Zend_Controller_Router_Route_Static',
                'route'    => 'bar',
                'defaults' => array(
                    'module'      => 'module',
                     'controller' => 'controller',
                     'action'     => 'action'
                )
            )
        )
    )
));
 
// Affecte un séparateur avant configuration
$router->setChainNameSeparator('_separator_')
 
// Ajoute la configuration
$router->addConfig($config);
 
// La nom de notre route est maintenant: chainName_separator_subRouteName
echo $this->_router->assemble(array(), 'chainName_separator_subRouteName');
 
// La preuve: cela affiche /foo/bar

Zend_Rest_Route

Le composant Zend_Rest contient une route RESTful pour Zend_Controller_Router_Rewrite. Cette route permet un schéma de routage fonction de la méthode HTTP et de l'URI afin d'y faire correspondre un module, contrôleur, et action. Le tableau suivant vous donne un aperçu du schéma de routage en fonction de l'URI.

**Comportement de Zend_Rest_Route**
Méthode	URI	Module_Controller::action
`GET`	`/product/ratings/`	Product_RatingsController::indexAction()
`GET`	`/product/ratings/:id`	Product_RatingsController::getAction()
`POST`	`/product/ratings`	Product_RatingsController::postAction()
`PUT`	`/product/ratings/:id`	Product_RatingsController::putAction()
`DELETE`	`/product/ratings/:id`	Product_RatingsController::deleteAction()
`POST`	`/product/ratings/:id?_method=PUT`	Product_RatingsController::putAction()
`POST`	`/product/ratings/:id?_method=DELETE`	Product_RatingsController::deleteAction()

Utilisation de Zend_Rest_Route

Pour activer Zend_Rest_Route pour une application entière, construisez en un objet sans paramètre spécifique et ajoutez le comme route par défaut dans le contrôleur frontal:

$front     = Zend_Controller_Front::getInstance();
$restRoute = new Zend_Rest_Route($front);
$front->getRouter()->addRoute('default', $restRoute);

Note: Si Zend_Rest_Route ne trouve aucun module, contrôleur, action valides, il retournera FALSE et la route suivante sera alors analysée par le routeur.

Pour activer Zend_Rest_Route pour des modules spécifiques, construisez l'objet avec comme troisième paramètre, un tableau de noms de modules :

$front     = Zend_Controller_Front::getInstance();
$restRoute = new Zend_Rest_Route($front, array(), array('product'));
$front->getRouter()->addRoute('rest', $restRoute);

Pour activer Zend_Rest_Route pour des contrôleurs spécifiques, construisez l'objet avec comme troisième paramètre, un tableau de noms de contrôleurs en correspondance avec des noms de modules.

$front     = Zend_Controller_Front::getInstance();
$restRoute = new Zend_Rest_Route($front, array(), array(
    'product' => array('ratings')
));
$front->getRouter()->addRoute('rest', $restRoute);

Zend_Rest_Route avec Zend_Config_Ini

To use Zend_Rest_Route from an INI config file, use a route type parameter and set the config options:

routes.rest.type = Zend_Rest_Route
routes.rest.defaults.controller = object
routes.rest.mod = project,user

The 'type' option designates the RESTful routing config type. The 'defaults' option is used to specify custom default module, controller, and/or actions for the route. All other options in the config group are treated as RESTful module names, and their values are RESTful controller names. The example config defines Mod_ProjectController and Mod_UserController as RESTful controllers.

Then use the addConfig() method of the Rewrite router object:

$config = new Zend_Config_Ini('path/to/routes.ini');
$router = new Zend_Controller_Router_Rewrite();
$router->addConfig($config, 'routes');

Zend_Rest_Controller

Pour vous aidez à utiliser des contrôleurs avec Zend_Rest_Route, faites les étendre Zend_Rest_Controller. Zend_Rest_Controller définit les 5 opérations RESTful les plus connues sous forme de méthodes abstraites.

indexAction() - Devrait récupérer un index des ressources et le passer à la vue.
getAction() - Devrait récupérer des données d'une ressource définie par URI et les passer à la vue.
postAction() - Devrait accepter une nouvelle ressource et la faire persister (la sauvegarder).
putAction() - Devrait accepter une ressource indentifiée par URI et la faire persister (la sauvegarder).
deleteAction() - Devrait supprimer la ressource identifiée par URI.

Utiliser Zend_Config avec le RewriteRouter

Il arrive qu'il soit plus commode d'éditer un fichier de configuration de routes, plutôt que d'éditer un code source. Ceci est rendu possible par la méthode addConfig(). Vous créez un objet compatible Zend_Config et vous le passez à cette méthode.

Par exemple, voyons un fichier INI :

[production]
routes.archive.route = "archive/:year/*"
routes.archive.defaults.controller = archive
routes.archive.defaults.action = show
routes.archive.defaults.year = 2000
routes.archive.reqs.year = "\d+"
 
routes.news.type = "Zend_Controller_Router_Route_Static"
routes.news.route = "news"
routes.news.defaults.controller = "news"
routes.news.defaults.action = "list"
 
routes.archive.type = "Zend_Controller_Router_Route_Regex"
routes.archive.route = "archive/(\d+)"
routes.archive.defaults.controller = "archive"
routes.archive.defaults.action = "show"
routes.archive.map.1 = "year"
; OU: routes.archive.map.year = 1

Ce fichier INI peut être lu dans grâce à un objet Zend_Config comme suit :

$config = new Zend_Config_Ini('/path/to/config.ini', 'production');
$router = new Zend_Controller_Router_Rewrite();
$router->addConfig($config, 'routes');

Nous indiquons au routeur d'utiliser la section "routes" du fichier INI. Chaque clé de premier niveau représente le nom de la route, ainsi nous avons dans l'exemple ci dessus "archive" et "news". Chaque route attend alors au moins une entrée "route" avec une ou plusieurs entrées "defaults" ; optionnellement nous pouvons rajouter des paramètres obligatoires. Tout ceci correspond aux trois arguments fournis par l'objet implémentant Zend_Controller_Router_Route_Interface. Une entrée optionnelle "type" peut être utilisée pour indiquer le type de classe de routage à utiliser, il s'agit par défaut de Zend_Controller_Router_Route. Dans l'exemple au dessus, la route "news" va utiliser Zend_Controller_Router_Route_Static.

Dérivation de l'objet Router

Le routeur par défaut, dit de réécriture, devrait suffire dans la majorité des projets. Tout ce qu'il peut être nécessaire de faire, est d'ajouter des routes particulières selon vos besoins.

Cependant, si vous voulez utiliser votre propre logique de routage, une interface est disponible. Zend_Controller_Router_Interface ne définit qu'une seule méthode :

interface Zend_Controller_Router_Interface
{
  /**
   * @param  Zend_Controller_Request_Abstract $request
   * @throws Zend_Controller_Router_Exception
   * @return Zend_Controller_Request_Abstract
   */
  public function route(Zend_Controller_Request_Abstract $request);
}

Le processus de routage n'intervient qu'une fois : lorsque la requête est reçue par le système. Le routeur doit alors déterminer un contrôleur, une action et de paramètres optionnel et les spécifier dans un objet de requête, qui est ensuite passé au distributeur. Si il n'est pas possible de router une requête, alors l'objet de requête devrait être laissé tel-quel.

Routeur Standard