Routeur Standard
Zend_Controller
Programmer's Reference Guide

Le distributeur

Vue d'ensemble

La distribution est le processus de récupération de l'objet requête, Zend_Controller_Request_Abstract, d'extraction du nom de module, du nom de contrôleur, du nom d'action, et des paramètres facultatifs qui s'y trouvent, et enfin d'instanciation du contrôleur et de l'appel d'une action de ce contrôleur. Si le module, le contrôleur, ou l'action ne sont pas trouvés, il emploiera des valeurs par défaut pour eux. Zend_Controller_Dispatcher_Standard indique index pour le contrôleur et l'action par défaut et default pour le module par défaut, mais permet au développeur de changer ces valeurs par défaut pour chacun en utilisant les méthodes respectives setDefaultController(), setDefaultAction(), et setDefaultModule().

Note: Le module "Default"
 Quand vous créez des applications modulaires, vous pouvez constater que vous voulez aussi que votre module par défaut ait son espace de noms (dans la configuration par défaut, le module "default" n'a pas d'espace de noms). A partir de la version 1.5.0, vous pouvez spécifier le paramètre prefixDefaultModule à TRUE soit dans le contrôleur frontal soit dans le distributeur :

  1. // Dans le contrôleur frontal :
  2. $front->setParam('prefixDefaultModule', true);
  3.  
  4. // Dans le distributeur :
  5. $dispatcher->setParam('prefixDefaultModule', true);
Ceci vous permet de ré-utiliser un module existant en tant que module par défaut d'une application.

La distribution se produit dans une boucle dans le contrôleur frontal. Avant que le distribution ne se produise, le contrôleur frontal détermine la route de la requête pour récupérer les valeurs spécifiées par l'utilisateur pour le module, le contrôleur , l'action , et les paramètres optionnels. Il entre alors dans la boucle d'expédition, et distribue la requête.

Au début de chaque itération, il régle un drapeau dans l'objet requête indiquant que l'action a été distribuée. Si une action ou un plugin pre/postDispatch remet à zéro ce drapeau, la boucle de distribution continue et tente de distribuer la nouvelle requête. En changeant le contrôleur et/ou l'action dans la requête et en effaçant le drapeau de distribution, le développeur peut définir une chaîne de requêtes à réaliser.

La méthode du contrôleur d'action qui contrôle cette distribution est _forward() ; appelez cette méthode à partir de pre/postDispatch() ou d'une méthode d'action, en fournissant une action, un contrôleur, un module, et optionnellement des paramètres additionnels que vous souhaitez passer à la nouvelle action :

  1. public function fooAction()
  2. {
  3.     // Transférer la nouvelle action dans le contrôleur
  4.     // et le module courant :
  5.     $this->_forward('bar', null, null, array('baz' => 'bogus'));
  6. }
  7.  
  8. public function barAction()
  9. {
  10.     // Transférer vers une action dans un autre contrôleur,
  11.     // FooController::bazAction(), dans le module courant :
  12.     $this->_forward('baz', 'foo', null, array('baz' => 'bogus'));
  13. }
  14.  
  15. public function bazAction()
  16. {
  17.     // Transférer vers une action dans un autre contrôleur
  18.     // dans un autre module, Foo_BarController::bazAction():
  19.     $this->_forward('baz', 'bar', 'foo', array('baz' => 'bogus'));
  20. }

Sous-classer le distributeur

Zend_Controller_Front appelle en premier le routeur pour déterminer la première action dans la requête. Il entre ensuite dans la boucle de distribution, qui demande au distributeur de distribuer l'action.

Le distributeur a besoin de plusieurs données afin de réaliser son travail - il doit connaître le format des noms d'actions et de contrôleur, où chercher les fichiers de classe des contrôleurs, savoir si le nom de module fourni est valide, et il a besoin d'une API pour déterminer si une requête donnée est distribuable suivant les informations disponibles.

Zend_Controller_Dispatcher_Interface définit les méthodes suivantes nécessaires pour toute implémentation d'un distributeur :

  1. interface Zend_Controller_Dispatcher_Interface
  2. {
  3.     /**
  4.      * Formate une chaîne en un nom de classe de contrôleur
  5.      *
  6.      * @param string $unformatted
  7.      * @return string
  8.      */
  9.     public function formatControllerName($unformatted);
  10.  
  11.     /**
  12.      * Formate une chaîne en un nom de méthode d'action
  13.      *
  14.      * @param string $unformatted
  15.      * @return string
  16.      */
  17.     public function formatActionName($unformatted);
  18.  
  19.     /**
  20.      * Détermine si une requête est distribuable
  21.      *
  22.      * @param  Zend_Controller_Request_Abstract $request
  23.      * @return boolean
  24.      */
  25.     public function isDispatchable(
  26.                 Zend_Controller_Request_Abstract $request);
  27.  
  28.     /**
  29.      * Règle un paramètre utilisateur
  30.      * (via le contrôleur frontal, ou pour un usage local)
  31.      *
  32.      * @param string $name
  33.      * @param mixed $value
  34.      * @return Zend_Controller_Dispatcher_Interface
  35.      */
  36.     public function setParam($name, $value);
  37.  
  38.     /**
  39.      * Règle un tableau de paramètres utilisateur
  40.      *
  41.      * @param array $params
  42.      * @return Zend_Controller_Dispatcher_Interface
  43.      */
  44.     public function setParams(array $params);
  45.  
  46.     /**
  47.      * Récupère un paramètre utilisateur unique
  48.      *
  49.      * @param string $name
  50.      * @return mixed
  51.      */
  52.     public function getParam($name);
  53.  
  54.     /**
  55.      * Récupère tous les paramètres utilisateur
  56.      *
  57.      * @return array
  58.      */
  59.     public function getParams();
  60.  
  61.     /**
  62.      * Efface le tableau des paramètres utilisateur,
  63.      * ou un paramètre utilisateur unique :
  64.      *
  65.      * @param null|string|array single key or
  66.      *                          array of keys for params to clear
  67.      * @return Zend_Controller_Dispatcher_Interface
  68.      */
  69.     public function clearParams($name = null);
  70.  
  71.     /**
  72.      * Règle l'objet réponse à utiliser, s'il existe
  73.      *
  74.      * @param Zend_Controller_Response_Abstract|null $response
  75.      * @return void
  76.      */
  77.     public function setResponse(
  78.                 Zend_Controller_Response_Abstract $response = null);
  79.  
  80.     /**
  81.      * Récupère l'objet réponse, s'il existe
  82.      *
  83.      * @return Zend_Controller_Response_Abstract|null
  84.      */
  85.     public function getResponse();
  86.  
  87.     /**
  88.      * Ajoute un dossier de contrôleur dans le tableau
  89.      * des dossiers de contrôleurs
  90.      *
  91.      * @param string $path
  92.      * @param string $args
  93.      * @return Zend_Controller_Dispatcher_Interface
  94.      */
  95.     public function addControllerDirectory($path, $args = null);
  96.  
  97.     /**
  98.      * Règle le(s) dossier(s) où les fichiers de contrôleurs
  99.      * sont stockés
  100.      *
  101.      * @param string|array $dir
  102.      * @return Zend_Controller_Dispatcher_Interface
  103.      */
  104.     public function setControllerDirectory($path);
  105.  
  106.     /**
  107.      * Retourne le(s) dossier(s) où les fichiers de contrôleurs
  108.      * sont stockés
  109.      *
  110.      * @return array
  111.      */
  112.     public function getControllerDirectory();
  113.  
  114.     /**
  115.      * Distribue une requête vers un (module/)contrôleur/action.
  116.      *
  117.      * @param  Zend_Controller_Request_Abstract $request
  118.      * @param  Zend_Controller_Response_Abstract $response
  119.      * @return Zend_Controller_Request_Abstract|boolean
  120.      */
  121.     public function dispatch(Zend_Controller_Request_Abstract $request,
  122.                              Zend_Controller_Response_Abstract $response);
  123.  
  124.     /**
  125.      * Informe si un module donné est valide
  126.      *
  127.      * @param string $module
  128.      * @return boolean
  129.      */
  130.     public function isValidModule($module);
  131.  
  132.     /**
  133.      * Retourne le nom du module par défaut
  134.      *
  135.      * @return string
  136.      */
  137.     public function getDefaultModule();
  138.  
  139.     /**
  140.      * Retourne le nom du contrôleur par défaut
  141.      *
  142.      * @return string
  143.      */
  144.     public function getDefaultControllerName();
  145.  
  146.     /**
  147.      * Retourne le nom de l'action par défaut
  148.      *
  149.      * @return string
  150.      */
  151.     public function getDefaultAction();
  152. }

Cependant, dans la plupart des cas, vous devriez simplement étendre la classe abstraite Zend_Controller_Dispatcher_Abstract, dans laquelle chacune de ces méthodes a déjà été définie, ou Zend_Controller_Dispatcher_Standard pour modifier une fonctionnalité du distributeur standard.

Les raisons possibles au sous-classement du distributeur incluent un désir d'employer une classe ou un schéma différent de nommage des classes et/ou des méthodes dans vos contrôleurs d'action, ou un désir d'employer un paradigme de distribution différent tel que la distribution de fichiers de classe d'action dans des dossiers de contrôleur (au lieu de la distribution des méthodes de classes).

Routeur Standard
Zend_Controller
Programmer's Reference Guide