documentation/manual/fr/module_specs/Zend_Controller-Dispatcher.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!-- EN-Revision: 16658 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.controller.dispatcher">
   5     <title>Le distributeur</title>
   6
   7     <sect2 id="zend.controller.dispatcher.overview">
   8         <title>Vue d'ensemble</title>
   9
  10         <para>
  11             La distribution est le processus de récupération de l'objet requête,
  12             <classname>Zend_Controller_Request_Abstract</classname>, d'extraction du nom de module,
  13             du nom de contrôleur, du nom d'action, et des paramètres facultatifs qui s'y trouvent,
  14             et enfin d'instanciation du contrôleur et de l'appel d'une action de ce contrôleur. Si
  15             le module, le contrôleur, ou l'action ne sont pas trouvés, il emploiera des valeurs par
  16             défaut pour eux. <classname>Zend_Controller_Dispatcher_Standard</classname> indique
  17             <code>index</code> pour le contrôleur et l'action par défaut et <code>default</code>
  18             pour le module par défaut, mais permet au développeur de changer ces valeurs par défaut
  19             pour chacun en utilisant les méthodes respectives <methodname>setDefaultController()</methodname>,
  20             <methodname>setDefaultAction()</methodname>, et <methodname>setDefaultModule()</methodname>.
  21         </para>
  22
  23         <note>
  24             <title>Le module "Default"</title>
  25             <para>
  26                 Quand vous créez des applications modulaires, vous pouvez constater que vous
  27                 voulez aussi que votre module par défaut ait son espace de noms (dans la
  28                 configuration par défaut, le module "<code>default</code>"
  29                 <emphasis>n'a pas</emphasis> d'espace de noms). A partir de la version 1.5.0, vous
  30                 pouvez spécifier le paramètre <code>prefixDefaultModule</code> à <constant>TRUE</constant>
  31                 soit dans le contrôleur frontal soit dans le distributeur&#160;:
  32             </para>
  33             <programlisting language="php"><![CDATA[
  34 // Dans le contrôleur frontal :
  35 $front->setParam('prefixDefaultModule', true);
  36
  37 // Dans le distributeur :
  38 $dispatcher->setParam('prefixDefaultModule', true);
  39 ]]></programlisting>
  40             <para>
  41                 Ceci vous permet de ré-utiliser un module existant en tant que module par
  42                 défaut d'une application.
  43             </para>
  44         </note>
  45
  46         <para>
  47             La distribution se produit dans une boucle dans le contrôleur frontal. Avant que
  48             le distribution ne se produise, le contrôleur frontal détermine la route de la requête
  49             pour récupérer les valeurs spécifiées par l'utilisateur pour le module, le contrôleur ,
  50             l'action , et les paramètres optionnels. Il entre alors dans la boucle d'expédition, et
  51             distribue la requête.
  52         </para>
  53
  54         <para>
  55             Au début de chaque itération, il régle un drapeau dans l'objet requête indiquant
  56             que l'action a été distribuée. Si une action ou un plugin <code>pre/postDispatch</code>
  57             remet à zéro ce drapeau, la boucle de distribution continue et tente de distribuer la
  58             nouvelle requête. En changeant le contrôleur et/ou l'action dans la requête et en
  59             effaçant le drapeau de distribution, le développeur peut définir une chaîne de requêtes
  60             à réaliser.
  61         </para>
  62
  63         <para>
  64             La méthode du contrôleur d'action qui contrôle cette distribution est
  65             <methodname>_forward()</methodname>&#160;; appelez cette méthode à partir de
  66             <code>pre/postDispatch()</code> ou d'une méthode d'action, en fournissant une action,
  67             un contrôleur, un module, et optionnellement des paramètres additionnels que vous
  68             souhaitez passer à la nouvelle action&#160;:
  69         </para>
  70
  71         <programlisting language="php"><![CDATA[
  72 public function fooAction()
  73 {
  74     // Transférer la nouvelle action dans le contrôleur
  75     // et le module courant :
  76     $this->_forward('bar', null, null, array('baz' => 'bogus'));
  77 }
  78
  79 public function barAction()
  80 {
  81     // Transférer vers une action dans un autre contrôleur,
  82     // FooController::bazAction(), dans le module courant :
  83     $this->_forward('baz', 'foo', null, array('baz' => 'bogus'));
  84 }
  85
  86 public function bazAction()
  87 {
  88     // Transférer vers une action dans un autre contrôleur
  89     // dans un autre module, Foo_BarController::bazAction():
  90     $this->_forward('baz', 'bar', 'foo', array('baz' => 'bogus'));
  91 }
  92 ]]></programlisting>
  93     </sect2>
  94
  95     <sect2 id="zend.controller.dispatcher.subclassing">
  96         <title>Sous-classer le distributeur</title>
  97
  98         <para>
  99             <classname>Zend_Controller_Front</classname> appelle en premier le routeur pour
 100             déterminer la première action dans la requête. Il entre ensuite dans la boucle de
 101             distribution, qui demande au distributeur de distribuer l'action.
 102         </para>
 103
 104         <para>
 105             Le distributeur a besoin de plusieurs données afin de réaliser son travail - il
 106             doit connaître le format des noms d'actions et de contrôleur, où chercher les fichiers
 107             de classe des contrôleurs, savoir si le nom de module fourni est valide, et il a besoin
 108             d'une <acronym>API</acronym> pour déterminer si une requête donnée est distribuable suivant les
 109             informations disponibles.
 110         </para>
 111
 112         <para>
 113             <classname>Zend_Controller_Dispatcher_Interface</classname> définit les méthodes
 114             suivantes nécessaires pour toute implémentation d'un distributeur&#160;:
 115         </para>
 116
 117         <programlisting language="php"><![CDATA[
 118 interface Zend_Controller_Dispatcher_Interface
 119 {
 120     /**
 121      * Formate une chaîne en un nom de classe de contrôleur
 122      *
 123      * @param string $unformatted
 124      * @return string
 125      */
 126     public function formatControllerName($unformatted);
 127
 128     /**
 129      * Formate une chaîne en un nom de méthode d'action
 130      *
 131      * @param string $unformatted
 132      * @return string
 133      */
 134     public function formatActionName($unformatted);
 135
 136     /**
 137      * Détermine si une requête est distribuable
 138      *
 139      * @param  Zend_Controller_Request_Abstract $request
 140      * @return boolean
 141      */
 142     public function isDispatchable(
 143                 Zend_Controller_Request_Abstract $request);
 144
 145     /**
 146      * Règle un paramètre utilisateur
 147      * (via le contrôleur frontal, ou pour un usage local)
 148      *
 149      * @param string $name
 150      * @param mixed $value
 151      * @return Zend_Controller_Dispatcher_Interface
 152      */
 153     public function setParam($name, $value);
 154
 155     /**
 156      * Règle un tableau de paramètres utilisateur
 157      *
 158      * @param array $params
 159      * @return Zend_Controller_Dispatcher_Interface
 160      */
 161     public function setParams(array $params);
 162
 163     /**
 164      * Récupère un paramètre utilisateur unique
 165      *
 166      * @param string $name
 167      * @return mixed
 168      */
 169     public function getParam($name);
 170
 171     /**
 172      * Récupère tous les paramètres utilisateur
 173      *
 174      * @return array
 175      */
 176     public function getParams();
 177
 178     /**
 179      * Efface le tableau des paramètres utilisateur,
 180      * ou un paramètre utilisateur unique :
 181      *
 182      * @param null|string|array single key or
 183      *                          array of keys for params to clear
 184      * @return Zend_Controller_Dispatcher_Interface
 185      */
 186     public function clearParams($name = null);
 187
 188     /**
 189      * Règle l'objet réponse à utiliser, s'il existe
 190      *
 191      * @param Zend_Controller_Response_Abstract|null $response
 192      * @return void
 193      */
 194     public function setResponse(
 195                 Zend_Controller_Response_Abstract $response = null);
 196
 197     /**
 198      * Récupère l'objet réponse, s'il existe
 199      *
 200      * @return Zend_Controller_Response_Abstract|null
 201      */
 202     public function getResponse();
 203
 204     /**
 205      * Ajoute un dossier de contrôleur dans le tableau
 206      * des dossiers de contrôleurs
 207      *
 208      * @param string $path
 209      * @param string $args
 210      * @return Zend_Controller_Dispatcher_Interface
 211      */
 212     public function addControllerDirectory($path, $args = null);
 213
 214     /**
 215      * Règle le(s) dossier(s) où les fichiers de contrôleurs
 216      * sont stockés
 217      *
 218      * @param string|array $dir
 219      * @return Zend_Controller_Dispatcher_Interface
 220      */
 221     public function setControllerDirectory($path);
 222
 223     /**
 224      * Retourne le(s) dossier(s) où les fichiers de contrôleurs
 225      * sont stockés
 226      *
 227      * @return array
 228      */
 229     public function getControllerDirectory();
 230
 231     /**
 232      * Distribue une requête vers un (module/)contrôleur/action.
 233      *
 234      * @param  Zend_Controller_Request_Abstract $request
 235      * @param  Zend_Controller_Response_Abstract $response
 236      * @return Zend_Controller_Request_Abstract|boolean
 237      */
 238     public function dispatch(Zend_Controller_Request_Abstract $request,
 239                              Zend_Controller_Response_Abstract $response);
 240
 241     /**
 242      * Informe si un module donné est valide
 243      *
 244      * @param string $module
 245      * @return boolean
 246      */
 247     public function isValidModule($module);
 248
 249     /**
 250      * Retourne le nom du module par défaut
 251      *
 252      * @return string
 253      */
 254     public function getDefaultModule();
 255
 256     /**
 257      * Retourne le nom du contrôleur par défaut
 258      *
 259      * @return string
 260      */
 261     public function getDefaultControllerName();
 262
 263     /**
 264      * Retourne le nom de l'action par défaut
 265      *
 266      * @return string
 267      */
 268     public function getDefaultAction();
 269 }
 270 ]]></programlisting>
 271
 272         <para>
 273             Cependant, dans la plupart des cas, vous devriez simplement étendre la classe
 274             abstraite <classname>Zend_Controller_Dispatcher_Abstract</classname>, dans laquelle
 275             chacune de ces méthodes a déjà été définie, ou
 276             <classname>Zend_Controller_Dispatcher_Standard</classname> pour modifier une
 277             fonctionnalité du distributeur standard.
 278         </para>
 279
 280         <para>
 281             Les raisons possibles au sous-classement du distributeur incluent un désir
 282             d'employer une classe ou un schéma différent de nommage des classes et/ou des méthodes
 283             dans vos contrôleurs d'action, ou un désir d'employer un paradigme de distribution
 284             différent tel que la distribution de fichiers de classe d'action dans des dossiers de
 285             contrôleur (au lieu de la distribution des méthodes de classes).
 286         </para>
 287     </sect2>
 288 </sect1>