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

   1 <sect1 id="zend.controller.dispatcher">
   2     <title>分发器</title>
   3
   4     <sect2 id="zend.controller.dispatcher.overview">
   5         <title>概述</title>
   6
   7         <para>
   8             分发是取得请求对象，提取其中的模块名，控制器名，动作名以及可选参数，然后实例化控制器并调用其中的动作的整过过程。如果其中的模块、控制器或者动作没能找到，将使用它们的默认值。<code>Zend_Controller_Dispatcher_Standard</code>指定每个控制器和动作的默认值为 <code>index</code>，模块的默认值为<code>default</code>，允许开发人通过<code>setDefaultController()</code>、<code>setDefaultAction()</code>和<code>setDefaultModule()</code>改变默认值设定。
   9         </para>
  10
  11         <note>
  12             <title>缺省模块</title>
  13
  14             <para>
  15                 当创建模块程序，你可能也需要缺省模块的命名空间（缺省配置中，缺省模块<emphasis>没有</emphasis>命名空间）。从 1.5.0 开始，可以在前端控制器或你的派遣器里通过指定 <code>prefixDefaultModule</code>  为 true 来实现。
  16              </para>
  17
  18             <programlisting role="php"><![CDATA[
  19 // 在你的前端控制器中：
  20 $front->setParam('prefixDefaultModule', true);
  21
  22 // 在你的分发器中：
  23 $dispatcher->setParam('prefixDefaultModule', true);
  24 ]]>
  25             </programlisting>
  26
  27             <para>
  28                 这允许你重定义一个已存在的模块为程序的缺省模块。
  29             </para>
  30         </note>
  31
  32         <para>
  33             分发发生在前端控制器中的一个循环（loop）中。分发之前，前端控制器通过路由请求，找到用户指定的模块、控制器、动作和可选参数。然后进入分发循环，分发请求。
  34         </para>
  35
  36         <para>
  37            每次迭代（iteration）过程开始时，在请求对象中设置一个标志指示该动作已分发。如果在动作或者前/后分发（pre/postDispatch）插件重置了该标志，分发循环将继续下去并试图分发新的请求。通过改变请求中的控制器或者动作并重置已分发标志，开发人员可以定制执行一个请求链。
  38         </para>
  39
  40         <para>
  41            控制这种分发过程的动作控制器方法是<code>_forward()</code>；在任意的<code>pre/postDispatch()</code>或者动作中调用该方法，并传入动作、控制器、模块、以及可选的附加参数，就可以进入新的动作。
  42         </para>
  43
  44         <programlisting role="php"><![CDATA[
  45 public function fooAction()
  46 {
  47     // forward to another action in the current controller and module:
  48     $this->_forward('bar', null, null, array('baz' => 'bogus'));
  49 }
  50
  51 public function barAction()
  52 {
  53     // forward to an action in another controller:
  54     // FooController::bazAction(),
  55     // in the current module:
  56     $this->_forward('baz', 'foo', null, array('baz' => 'bogus'));
  57 }
  58
  59 public function bazAction()
  60 {
  61     // forward to an action in another controller in another module,
  62     // Foo_BarController::bazAction():
  63     $this->_forward('baz', 'bar', 'foo', array('baz' => 'bogus'));
  64 }
  65 ]]>
  66         </programlisting>
  67     </sect2>
  68
  69     <sect2 id="zend.controller.dispatcher.subclassing">
  70         <title>子类化分发器</title>
  71
  72         <para>
  73             <code>Zend_Controller_Front</code>首先调用路由器找到请求中的第一个动作，然后进入分发循环，调用分发器分发动作。
  74         </para>
  75
  76         <para>
  77             分发器需要大量数据完成任务——它需要知道如何格式化控制器和动作的名称，到哪儿找到控制器类文件，模块名是否有效，以及基于其它可用信息判定请求是否能分发的API。
  78         </para>
  79
  80         <para>
  81             <code>Zend_Controller_Dispatcher_Interface</code>定义了下列所有分发器需要实现的方法。
  82         </para>
  83
  84         <programlisting role="php"><![CDATA[
  85 interface Zend_Controller_Dispatcher_Interface
  86 {
  87     /**
  88      * Format a string into a controller class name.
  89      *
  90      * @param string $unformatted
  91      * @return string
  92      */
  93     public function formatControllerName($unformatted);
  94
  95     /**
  96      * Format a string into an action method name.
  97      *
  98      * @param string $unformatted
  99      * @return string
 100      */
 101     public function formatActionName($unformatted);
 102
 103     /**
 104      * Determine if a request is dispatchable
 105      *
 106      * @param  Zend_Controller_Request_Abstract $request
 107      * @return boolean
 108      */
 109     public function isDispatchable(
 110         Zend_Controller_Request_Abstract $request
 111     );
 112
 113     /**
 114      * Set a user parameter (via front controller, or for local use)
 115      *
 116      * @param string $name
 117      * @param mixed $value
 118      * @return Zend_Controller_Dispatcher_Interface
 119      */
 120     public function setParam($name, $value);
 121
 122     /**
 123      * Set an array of user parameters
 124      *
 125      * @param array $params
 126      * @return Zend_Controller_Dispatcher_Interface
 127      */
 128     public function setParams(array $params);
 129
 130     /**
 131      * Retrieve a single user parameter
 132      *
 133      * @param string $name
 134      * @return mixed
 135      */
 136     public function getParam($name);
 137
 138     /**
 139      * Retrieve all user parameters
 140      *
 141      * @return array
 142      */
 143     public function getParams();
 144
 145     /**
 146      * Clear the user parameter stack, or a single user parameter
 147      *
 148      * @param null|string|array single key or array of keys for
 149      *        params to clear
 150      * @return Zend_Controller_Dispatcher_Interface
 151      */
 152     public function clearParams($name = null);
 153
 154     /**
 155      * Set the response object to use, if any
 156      *
 157      * @param Zend_Controller_Response_Abstract|null $response
 158      * @return void
 159      */
 160     public function setResponse(
 161         Zend_Controller_Response_Abstract $response = null
 162     );
 163
 164     /**
 165      * Retrieve the response object, if any
 166      *
 167      * @return Zend_Controller_Response_Abstract|null
 168      */
 169     public function getResponse();
 170
 171     /**
 172      * Add a controller directory to the controller directory stack
 173      *
 174      * @param string $path
 175      * @param string $args
 176      * @return Zend_Controller_Dispatcher_Interface
 177      */
 178     public function addControllerDirectory($path, $args = null);
 179
 180     /**
 181      * Set the directory (or directories) where controller files are
 182      * stored
 183      *
 184      * @param string|array $dir
 185      * @return Zend_Controller_Dispatcher_Interface
 186      */
 187     public function setControllerDirectory($path);
 188
 189     /**
 190      * Return the currently set directory(ies) for controller file
 191      * lookup
 192      *
 193      * @return array
 194      */
 195     public function getControllerDirectory();
 196
 197     /**
 198      * Dispatch a request to a (module/)controller/action.
 199      *
 200      * @param  Zend_Controller_Request_Abstract $request
 201      * @param  Zend_Controller_Response_Abstract $response
 202      * @return Zend_Controller_Request_Abstract|boolean
 203      */
 204     public function dispatch(
 205         Zend_Controller_Request_Abstract $request,
 206         Zend_Controller_Response_Abstract $response
 207     );
 208
 209     /**
 210      * Whether or not a given module is valid
 211      *
 212      * @param string $module
 213      * @return boolean
 214      */
 215     public function isValidModule($module);
 216
 217     /**
 218      * Retrieve the default module name
 219      *
 220      * @return string
 221      */
 222     public function getDefaultModule();
 223
 224     /**
 225      * Retrieve the default controller name
 226      *
 227      * @return string
 228      */
 229     public function getDefaultControllerName();
 230
 231     /**
 232      * Retrieve the default action
 233      *
 234      * @return string
 235      */
 236     public function getDefaultAction();
 237 }
 238 ]]>
 239         </programlisting>
 240
 241         <para>
 242            不过大多数情况下，只需要简单地扩展抽象类<code>Zend_Controller_Dispatcher_Abstract</code>，其中已经定义好了上面的大部分方法。或者扩展<code>Zend_Controller_Dispatcher_Standard</code>类，基于标准分发器来修改功能。
 243         </para>
 244
 245         <para>
 246             需要子类化分发器的可能原因包括：期望在动作控制器中使用不同的类和方法命名模式，或者期望使用不同的分发方式，比如分发到控制器目录下的动作文件，而不是控制器类的动作方法。
 247         </para>
 248     </sect2>
 249 </sect1>
 250 <!--
 251 vim:se ts=4 sw=4 et:
 252 -->