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

   1 <sect1 id="zend.controller.front">
   2     <title>前端控制器</title>
   3
   4     <sect2 id="zend.controller.front.overview">
   5         <title>概述</title>
   6
   7         <para>
   8             <code>Zend_Controller_Front</code>实现了<ulink url="http://en.wikipedia.org/wiki/Model-view-controller">模型-视图-控制器 (MVC)</ulink>应用程序的<ulink url="http://www.martinfowler.com/eaaCatalog/frontController.html">前端控制器模式</ulink>。目的在于初始化请求环境，并路由到来的请求，接着分发任何发现的动作；收集所有的响应，在整个过程完成时就其返回。
   9         </para>
  10
  11         <para>
  12             <code>Zend_Controller_Front</code>也实现了<ulink url="http://en.wikipedia.org/wiki/Singleton_pattern">单件（Singleton）模式</ulink>，意味着任何时候，都只可能有一个有效实例。这使得它可以作为注册表，供分发过程中的其他对象引用。
  13         </para>
  14
  15         <para>
  16             <code>Zend_Controller_Front</code>自己注册了一个<link linkend="zend.controller.plugins">插件经纪人（plugin broker）</link>，允许插件观测它所触发的各种事件。大多数情况下，这将使得开发人员有机会裁剪站点的分发过程，而无需通过扩展前端控制器增加功能。
  17         </para>
  18
  19         <para>
  20             前端控制器最至少需要一个或多个包含<link linkend="zend.controller.action">动作控制器</link>的目录的路径来完成工作。还有大量的方法可供调用，进一步裁剪前端控制器以及它的助手类环境。
  21         </para>
  22
  23         <note>
  24             <title>默认的行为</title>
  25             <para>
  26                 默认地，前端控制器加载<link linkend="zend.controller.plugins.standard.errorhandler">ErrorHandler</link>插件，以及<link linkend="zend.controller.actionhelpers.viewrenderer">ViewRenderer</link>动作助手，分别为了简化控制器中的错误处理和视图渲染。
  27             </para>
  28
  29             <para>
  30                 如需禁用<code>ErrorHandler</code>，调用<code>dispatch()</code>前执行下面代码：
  31             </para>
  32
  33             <programlisting role="php"><![CDATA[
  34 // Disable the ErrorHandler plugin:
  35 $front->setParam('noErrorHandler', true);
  36 ]]>
  37             </programlisting>
  38
  39             <para>
  40                 如需禁用<code>ViewRenderer</code>，调用<code>dispatch()</code>前执行下面代码：
  41             </para>
  42
  43             <programlisting role="php"><![CDATA[
  44 // Disable the ViewRenderer helper:
  45 $front->setParam('noViewRenderer', true);
  46 ]]>
  47             </programlisting>
  48         </note>
  49     </sect2>
  50
  51     <sect2 id="zend.controller.front.methods.primary">
  52         <title>主要方法</title>
  53
  54         <para>
  55             前端控制器有很多建立其环境的访问器。但是，有三个是开启前端控制器功能的主要方法：
  56         </para>
  57
  58         <sect3 id="zend.controller.front.methods.primary.getinstance">
  59             <title>getInstance()</title>
  60
  61             <para>
  62                 <code>getInstance()</code>方法用来获取前端控制器实例。因为前端控制器实现了单件模式，这可能是唯一创建前端控制器对象的方法。
  63             </para>
  64
  65             <programlisting role="php"><![CDATA[
  66 $front = Zend_Controller_Front::getInstance();
  67 ]]>
  68             </programlisting>
  69         </sect3>
  70
  71         <sect3 id="zend.controller.front.methods.primary.setcontrollerdirectory">
  72             <title>setControllerDirectory() 和 addControllerDirectory()</title>
  73
  74             <para>
  75                 <code>setControllerDirectory()</code>通知<link linkend="zend.controller.dispatcher">分发器</link>到哪查找动作控制器<link linkend="zend.controller.action">action controller</link>类文件。参数接受单一路径和模块/路径对关联数组。
  76             </para>
  77
  78             <para>
  79                 例如：
  80             </para>
  81
  82             <programlisting role="php"><![CDATA[
  83 // Set the default controller directory:
  84 $front->setControllerDirectory('../application/controllers');
  85
  86 // Set several module directories at once:
  87 $front->setControllerDirectory(array(
  88     'default' => '../application/controllers',
  89     'blog'    => '../modules/blog/controllers',
  90     'news'    => '../modules/news/controllers',
  91 ));
  92
  93 // Add a 'foo' module directory:
  94 $front->addControllerDirectory('../modules/foo/controllers', 'foo');
  95 ]]>
  96             </programlisting>
  97
  98             <note>
  99                 <para>
 100                     如果使用<code>addControllerDirectory()</code>时不带模块名，将会为<code>default</code>模块设定目录——如果目录已设定，就覆盖掉。
 101                 </para>
 102             </note>
 103
 104             <para>
 105                 可以通过<code>getControllerDirectory()</code>获取控制器目录的当前设置；它将返回一个模块/目录对关联数组。
 106             </para>
 107         </sect3>
 108
 109         <sect3 id="zend.controller.front.methods.primary.addmoduledirectory">
 110             <title>addModuleDirectory() and getModuleDirectory()</title>
 111
 112             <para>
 113                 前端控制器的一个功能是你可以
 114                 <link
 115                     linkend="zend.controller.modular">定义一个模块目录结构
 116                 </link>
 117                 来创建独立的组件，被叫做“模块”。
 118             </para>
 119
 120             <para>
 121                 每个模块位于自己的目录并和缺省模块的目录结构一样 － 例如，它至少
 122                 有个 "controllers" 字目录和 "views" 子目录以及其它应用子目录。
 123             </para>
 124
 125             <para>
 126                 <code>addModuleDirectory()</code> 让你传递一个包含一个或多个模块目录的目录名。
 127                 然后进行扫描并把它们作为控制器目录添加到前端控制器。
 128             </para>
 129
 130             <para>
 131                 然后，如果你想确定特定模块或当前模块路径，调用 <code>getModuleDirectory()</code>，
 132                 可选地传递模块名来获得模块目录。
 133             </para>
 134         </sect3>
 135
 136         <sect3 id="zend.controller.front.methods.primary.dispatch">
 137             <title>dispatch()</title>
 138
 139             <para>
 140                 <code>dispatch(Zend_Controller_Request_Abstract $request = null, Zend_Controller_Response_Abstract $response = null)</code>完成前端控制器最繁重的工作。该方法带有可选的参数<link linkend="zend.controller.request">请求对象</link>和/或<link linkend="zend.controller.response">响应对象</link>，允许开发人员为每一个传入定制的对象。
 141             </para>
 142
 143             <para>
 144                         如果没有请求或者响应对象传入，<code>dispatch()</code>将检查先前注册的对象并使用，如果没有发现则创建默认的对象版本（它们两个都默认使用HTTP对象）。
 145             </para>
 146
 147             <para>
 148                         类似的，<code>dispatch()</code>先检查已注册的<link linkend="zend.controller.router">路由器（router）</link>和<link linkend="zend.controller.dispatcher">分发器（dispatcher）</link>对象，如果没有发现则实例化它们的默认版本。
 149             </para>
 150
 151             <para>
 152                         分发过程有三个不同的事件：
 153             </para>
 154
 155             <itemizedlist>
 156                 <listitem><para>路由（Routing）</para></listitem>
 157                 <listitem><para>分发（Dispatching）</para></listitem>
 158                 <listitem><para>响应（Response）</para></listitem>
 159             </itemizedlist>
 160
 161             <para>
 162                         路由只发生一次，当调用<code>dispatch()</code>时利用请求对象中的值。分发发生在一个循环中;请求可能指示  分发多个动作，或者控制器或插件可能重置请求对象，强制分发附加的动作。所有都完成后，前端控制器返回响应对象。
 163             </para>
 164         </sect3>
 165
 166         <sect3 id="zend.controller.front.methods.primary.run">
 167             <title>run()</title>
 168
 169             <para>
 170                 <code>Zend_Controller_Front::run($path)</code>是静态方法，只带一个参数，就是指向包含控制器的目录的路径。它首先通过<link linkend="zend.controller.front.methods.primary.getinstance">getInstance()</link>获取前端控制器实例，然后通过<link linkend="zend.controller.front.methods.primary.setcontrollerdirectory">setControllerDirectory()</link>注册传入的路径，最后<link linkend="zend.controller.front.methods.primary.dispatch">分发</link>。
 171             </para>
 172
 173             <para>
 174                         基本上，如果不要求定制前端控制器环境，<code>run()</code>是一个很方便的建立前端控制器环境的方法。
 175             </para>
 176
 177             <programlisting role="php"><![CDATA[
 178 // Instantiate front controller, set controller directory, and dispatch in one
 179 // easy step:
 180 Zend_Controller_Front::run('../application/controllers');
 181 ]]>
 182             </programlisting>
 183         </sect3>
 184     </sect2>
 185
 186     <sect2 id="zend.controller.front.methods.environment">
 187         <title>环境访问器方法</title>
 188
 189         <para>
 190                   除了上面所列的方法以外，还有很多访问器方法可以影响前端控制器环境 —— 因而也影响前端控制器代理（delegate）的类的环境。
 191         </para>
 192
 193         <itemizedlist>
 194             <listitem>
 195                 <para>
 196                     <code>resetInstance()</code>方法清除当前的所有设置。主要用来测试，不过，在希望将几个前端控制器连锁的地方也是很有用的（but it can also be used for instances where you wish to chain together multiple front controllers）。
 197                 </para>
 198             </listitem>
 199
 200             <listitem>
 201                 <para>
 202                     <code>(set|get)DefaultControllerName()</code>方法可以为默认的控制器指定另外一个名字（否则使用'index'），以及获取当前值。它们将代理<link linkend="zend.controller.dispatcher">分发器</link>。
 203                 </para>
 204             </listitem>
 205
 206             <listitem>
 207                 <para>
 208                     <code>(set|get)DefaultAction()</code>方法可以为默认的动作指定另外一个名字（否则使用'index'）,以及获取当前值。它们将代理<link linkend="zend.controller.dispatcher">分发器</link>。
 209                 </para>
 210             </listitem>
 211
 212             <listitem>
 213                 <para>
 214                     <code>(set|get)Request()</code>方法指定分发过程中使用的<link linkend="zend.controller.request">请求</link>类或对象，以及获取当前的请求对象。设置请求对象时，可以传入一个请求类的名字，该方法将加载类文件并创建实例。
 215                 </para>
 216             </listitem>
 217
 218             <listitem>
 219                 <para>
 220                     <code>(set|get)Router()</code>方法指定分发过程中使用的<link linkend="zend.controller.router">路由器</link>类或对象，以及获取当前对象。设置路由器时，可以传入一个路由器类的名字，该方法将加载类文件并创建实例。
 221                 </para>
 222
 223                 <para>
 224                              获取路由器对象的时候，首先检查是否已有一个，如果没有，创建默认的路由器实例（rewrite路由器）。
 225                 </para>
 226             </listitem>
 227
 228             <listitem>
 229                 <para>
 230                     <code>(set|get)BaseUrl()</code>方法指定路由请求时剥离（strip）的<link linkend="zend.controller.request.http.baseurl">基地址（base URL）</link>，以及获取当前值。这个值将在路由前提供给路由器。
 231                         </para>
 232             </listitem>
 233
 234             <listitem>
 235                 <para>
 236                     <code>(set|get)Dispatcher()</code>方法指定分发过程中使用的<link linkend="zend.controller.dispatcher">分发器</link>类或对象，以及获取当前对象。设定分发器对象时，可以传入一个分发器类的名字，该方法将加载类文件并创建实例。
 237                 </para>
 238
 239                 <para>
 240                               获取分发器对象时，首先检查是否已有一个存在，如果没有，将创建一个默认的分发器实例。
 241                 </para>
 242             </listitem>
 243
 244             <listitem>
 245                 <para>
 246                     <code>(set|get)Response()</code>方法指定分发过程中使用的<link linkend="zend.controller.response">响应</link>类或对象，已经获取当前对象。设定响应对象时，可以传入一个响应类的名字，该方法将加载类文件并创建实例。
 247                 </para>
 248             </listitem>
 249
 250             <listitem>
 251                 <para>
 252                     <code>registerPlugin(Zend_Controller_Plugin_Abstract $plugin, $stackIndex = null)</code>方法允许注册一个<link linkend="zend.controller.plugins">插件对象</link>。通过设置可选参数<code>$stackIndex</code>，插件执行的顺序。
 253                 </para>
 254             </listitem>
 255
 256             <listitem>
 257                 <para>
 258                     <code>unregisterPlugin($plugin)</code>方法移除<link linkend="zend.controller.plugins">插件对象</link>。<code>$plugin</code>可以是一个插件对象或者代表移除插件类的字符串。
 259                 </para>
 260             </listitem>
 261
 262             <listitem>
 263                 <para>
 264                     <code>throwExceptions($flag)</code>方法用来开启或者关闭分发过程中抛出异常的能力。默认的，异常引起并放置在<link linkend="zend.controller.response">响应对象</link>中；开启<code>throwExceptions()</code>将覆盖这一行为。
 265                 </para>
 266
 267                 <para>
 268                               想知道更多信息的话，请阅读<xref linkend="zend.controller.exceptions" />。
 269                 </para>
 270             </listitem>
 271
 272             <listitem>
 273                 <para>
 274                     <code>returnResponse($flag)</code>方法通知前端控制器是否从<code>dispatch()</code>中返回请求对象（<code>true</code>），否则自动发送响应对象（<code>false</code>—）。默认的，响应对象被自动发送（通过调用<code>Zend_Controller_Response_Abstract::sendResponse()</code>）；开启<code>returnResponse()</code>将覆盖这一行为。
 275                 </para>
 276
 277                 <para>
 278                               返回响应对象的原因包括希望在发送响应前检查异常，记录响应的各种属性（例如消息头）等等。
 279                 </para>
 280             </listitem>
 281         </itemizedlist>
 282     </sect2>
 283
 284     <sect2 id="zend.controller.front.methods.params">
 285         <title>前端控制器参数</title>
 286
 287         <para>
 288                   介绍里曾提到前端控制器可以用作各种控制器组件的注册表。它通过一个"param"家族的方法来做到这些。这些方法允许通过前端控制器注册任意类型的数据 —— 对象和变量，可以在分发链中的任何时候获取。这些变量被传递到路由器，分发器，以及动作控制器。这些方法包括：
 289         </para>
 290
 291         <itemizedlist>
 292             <listitem>
 293                 <para>
 294                     <code>setParam($name, $value)</code>方法设定值为<code>$value</code>的单个参数<code>$name</code>。
 295                 </para>
 296             </listitem>
 297
 298             <listitem>
 299                 <para>
 300                     <code>setParams(array $params)</code>方法通过关联数组一次设定多个参数。
 301                 </para>
 302             </listitem>
 303
 304             <listitem>
 305                 <para>
 306                     <code>getParam($name)</code>方法通过<code>$name</code>标识符获取单个参数。
 307                 </para>
 308             </listitem>
 309
 310             <listitem>
 311                 <para>
 312                     <code>getParams()</code>方法一次获取整个参数列表。
 313                 </para>
 314             </listitem>
 315
 316             <listitem>
 317                 <para>
 318                     <code>clearParams()</code>方法可以清空一个参数（传入单个字符串标识符），清空多个参数（传入字符串标识符数组），清空整个参数栈（不传入参数）。
 319                 </para>
 320             </listitem>
 321         </itemizedlist>
 322
 323         <para>
 324                   有几个预定义的参数可供设定，它们在分发链中有特别的用途：
 325         </para>
 326
 327         <itemizedlist>
 328             <listitem>
 329                 <para>
 330                     <code>useDefaultControllerAlways</code>用来提示 <link linkend="zend.controller.dispatcher">分发器</link>遇到无法分发的请求时使用默认模块的默认控制器。这默认是关闭的。
 331                 </para>
 332
 333                 <para>
 334                     阅读<xref linkend="zend.controller.exceptions.internal" />获得使用该设定的更详尽信息。
 335                 </para>
 336             </listitem>
 337
 338             <listitem>
 339                 <para>
 340                     <code>disableOutputBuffering</code>用来提示 is used to hint to <link linkend="zend.controller.dispatcher">分发器</link>不使用输出缓冲来捕捉动作控制器产生的输出。默认的，分发器捕捉任何输出并追加到响应对象的主体内容。
 341                 </para>
 342             </listitem>
 343
 344             <listitem>
 345                 <para>
 346                     <code>noViewRenderer</code>用来禁用<link linkend="zend.controller.actionhelpers.viewrenderer">ViewRenderer</link>。设定该参数为true可以禁用该助手。
 347                 </para>
 348             </listitem>
 349
 350             <listitem>
 351                 <para>
 352                     <code>noErrorHandler</code> 用来禁用<link linkend="zend.controller.plugins.standard.errorhandler">错误处理器插件</link>。设定该参数为true可以禁用该插件。
 353                 </para>
 354             </listitem>
 355         </itemizedlist>
 356     </sect2>
 357
 358     <sect2 id="zend.controller.front.subclassing">
 359         <title>继承前端控制器</title>
 360
 361         <para>
 362                   要继承前端控制器，至少需要覆盖<code>getInstance()</code>方法：
 363         </para>
 364
 365         <programlisting role="php"><![CDATA[
 366 class My_Controller_Front extends Zend_Controller_Front
 367 {
 368     public static function getInstance()
 369     {
 370         if (null === self::$_instance) {
 371             self::$_instance = new self();
 372         }
 373
 374         return self::$_instance;
 375     }
 376 }
 377 ]]>
 378         </programlisting>
 379
 380         <para>
 381                   覆盖<code>getInstance()</code>保证后面调用<code>Zend_Controller_Front::getInstance()</code>会返回子类的实例，而不是<code>Zend_Controller_Front</code>实例 —— 这对于一些可替换的路由器和视图助手非常有用。
 382         </para>
 383
 384         <para>
 385                   通常不需要继承前端控制器，除非你需要增加新的功能（比如，一个插件自动加载器，或者一个方法来指定动作助手路径）。你想要改动的地方可能包括修改控制器目录的存储方式，使用的默认路由器以及分发器。
 386         </para>
 387     </sect2>
 388 </sect1>
 389 <!--
 390 vim:se ts=4 sw=4 et:
 391 -->