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

   1 <sect1 id="zend.controller.response">
   2     <title>响应对象</title>
   3
   4     <sect2 id="zend.controller.response.usage">
   5         <title>用法</title>
   6
   7         <para>
   8             响应对象逻辑上是<link linkend="zend.controller.request">请求对象</link>的搭档.目的在于收集消息体和/或消息头，因而可能返回大批的结果。另外前端控制器可能传递任何异常到响应对象，允许开发人员优美的处理异常。可以通过设置            <code>Zend_Controller_Front::throwExceptions(true)</code>覆盖这项功能：
   9         </para>
  10
  11         <programlisting role="php"><![CDATA[
  12 $front->throwExceptions(true);
  13 ]]>
  14         </programlisting>
  15
  16         <para>
  17             如果要发送响应输出包括消息头，使用<code>sendResponse()</code>。
  18         </para>
  19
  20         <programlisting role="php"><![CDATA[
  21 $response->sendResponse();
  22 ]]>
  23         </programlisting>
  24
  25         <note>
  26             <para>
  27                         默认地，前端控制器完成分发请求后调用<code>sendResponse()</code>；一般地，你不需要调用它。但是，如果你想处理响应或者用它来测试你可以使用<code>Zend_Controller_Front::returnResponse(true)</code>设置<code>returnResponse</code> 标志覆盖默认行为：
  28             </para>
  29
  30             <programlisting role="php"><![CDATA[
  31 $front->returnResponse(true);
  32 $response = $front->dispatch();
  33
  34 // do some more processing, such as logging...
  35 // and then send the output:
  36 $response->sendResponse();
  37 ]]>
  38             </programlisting>
  39         </note>
  40
  41         <para>
  42                   开发人员可以在动作控制器中使用响应对象。把结果写进响应对象，而不是直接渲染输出和发送消息头：
  43         </para>
  44
  45         <programlisting role="php"><![CDATA[
  46 // Within an action controller action:
  47 // Set a header
  48 $this->getResponse()
  49     ->setHeader('Content-Type', 'text/html')
  50     ->appendBody($content);
  51 ]]>
  52         </programlisting>
  53
  54         <para>
  55             这样做，可以在显示内容之前，将所有消息头一次发送。
  56         </para>
  57
  58         <note>
  59             <para>
  60                 如果使用动作控制器的 <link linkend="zend.controller.action.viewintegration">视图集成(view integration)</link>，你不需要在相应对象中设置渲染的视图脚本，因为<code>Zend_Controller_Action::render()</code> 默认完成了这些。
  61             </para>
  62         </note>
  63
  64         <para>
  65                   如果程序中发生了异常，检查响应对象的<code>isException()</code> 标志，使用<code>getException()</code>获取异常。此外，可以创建定制的响应对象重定向到错误页面，记录异常消息，漂亮的格式化异常消息等。
  66         </para>
  67
  68         <para>
  69                   在前端控制器执行dispatch()后可以获得响应对象，或者请求前端控制器返回响应对象代替渲染输出。
  70         </para>
  71
  72         <programlisting role="php"><![CDATA[
  73 // retrieve post-dispatch:
  74 $front->dispatch();
  75 $response = $front->getResponse();
  76 if ($response->isException()) {
  77     // log, mail, etc...
  78 }
  79
  80 // Or, have the front controller dispatch() process return it
  81 $front->returnResponse(true);
  82 $response = $front->dispatch();
  83
  84 // do some processing...
  85
  86 // finally, echo the response
  87 $response->sendResponse();
  88 ]]>
  89         </programlisting>
  90
  91         <para>
  92                   默认地，异常消息是不显示的。可以通过调用<code>renderExceptions()</code>覆盖默认设置。或者启用前端控制器的throwExceptions():
  93         </para>
  94
  95         <programlisting role="php"><![CDATA[
  96 $response->renderExceptions(true);
  97 $front->dispatch($request, $response);
  98
  99 // or:
 100 $front->returnResponse(true);
 101 $response = $front->dispatch();
 102 $response->renderExceptions();
 103 $response->sendResponse();
 104
 105 // or:
 106 $front->throwExceptions(true);
 107 $front->dispatch();
 108 ]]>
 109         </programlisting>
 110     </sect2>
 111
 112     <sect2 id="zend.controller.response.headers">
 113         <title>处理消息头</title>
 114
 115         <para>
 116                   如上文所述，响应对象的一项重要职责是收集和发出HTTP响应消息头，相应地存在大量的方法:
 117         </para>
 118
 119         <itemizedlist>
 120             <listitem>
 121                 <para>
 122                     <code>canSendHeaders()</code> 用来判别消息头是否已发送，该方法带有一个可选的标志指示消息头已发出时是否抛出异常。可以通过设置<code>headersSentThrowsException</code> 属性为<code>false</code>来覆盖默认设置。
 123                 </para>
 124             </listitem>
 125
 126             <listitem>
 127                 <para>
 128                     <code>setHeader($name, $value, $replace = false)</code>用来设置单独的消息头。默认的不会替换已经存在的同名消息头，但可以设置<code>$replace</code> 为true强制替换.
 129                 </para>
 130
 131                 <para>
 132                               设置消息头前，该方法先检查<code>canSendHeaders()</code>看操作是否允许，并请求抛出异常。
 133                 </para>
 134             </listitem>
 135
 136             <listitem>
 137                 <para>
 138                     <code>setRedirect($url, $code = 302)</code> 设置HTTP定位消息头准备重定向，如果提供HTTP状态码，重定向将会使用该状态码。
 139                 </para>
 140
 141                 <para>
 142                               其内部调用<code>setHeader()</code>并使<code>$replace</code> 标志呈打开状态确保只发送一次定位消息头。
 143                 </para>
 144             </listitem>
 145
 146             <listitem>
 147                 <para>
 148                     <code>getHeaders()</code> 返回一个消息头数组，每个元素都是一个带有'name'和'value'键的数组。
 149                 </para>
 150             </listitem>
 151
 152             <listitem>
 153                 <para>
 154                     <code>clearHeaders()</code> 清除所有注册的键值消息头。
 155                 </para>
 156             </listitem>
 157
 158             <listitem>
 159                 <para>
 160                     <code>setRawHeader()</code> 设置没有键值对的原始消息头，比如HTTP状态消息头。
 161                 </para>
 162             </listitem>
 163
 164             <listitem>
 165                 <para>
 166                     <code>getRawHeaders()</code> 返回所有注册的原始消息头。
 167                      </para>
 168             </listitem>
 169
 170             <listitem>
 171                 <para>
 172                     <code>clearRawHeaders()</code>清除所有的原始消息头。
 173                 </para>
 174             </listitem>
 175
 176             <listitem>
 177                 <para>
 178                     <code>clearAllHeaders()</code> 清除所有的消息头，包括原始消息头和键值消息头。
 179                 </para>
 180             </listitem>
 181         </itemizedlist>
 182
 183         <para>
 184                   除了上述方法，还有获取和设置当前请求HTTP响应码的访问器，            <code>setHttpResponseCode()</code> 和            <code>getHttpResponseCode()</code>.
 185         </para>
 186     </sect2>
 187
 188     <sect2 id="zend.controller.response.namedsegments">
 189         <title>命名片段</title>
 190
 191         <para>
 192                   相应对象支持“命名片段”。允许你将消息体分割成不同的片段，并呈一定顺序排列。因此输出的是以特定次序返回的。在其内部，主体内容被存储为一个数组，大量的访问器方法可以用来指示数组内位置和名称。
 193         </para>
 194
 195         <para>
 196                   举例来说，你可以使用<code>preDispatch()</code> 钩子来向响应对象中加入页头，然后在动作控制器中加入主体内容，最后在<code>postDispatch()</code>钩子中加入页脚。
 197         </para>
 198
 199         <programlisting role="php"><![CDATA[
 200 // Assume that this plugin class is registered with the front controller
 201 class MyPlugin extends Zend_Controller_Plugin_Abstract
 202 {
 203     public function preDispatch(Zend_Controller_Request_Abstract $request)
 204     {
 205         $response = $this->getResponse();
 206         $view = new Zend_View();
 207         $view->setBasePath('../views/scripts');
 208
 209         $response->prepend('header', $view->render('header.phtml'));
 210     }
 211
 212     public function postDispatch(Zend_Controller_Request_Abstract $request)
 213     {
 214         $response = $this->getResponse();
 215         $view = new Zend_View();
 216         $view->setBasePath('../views/scripts');
 217
 218         $response->append('footer', $view->render('footer.phtml'));
 219     }
 220 }
 221
 222 // a sample action controller
 223 class MyController extends Zend_Controller_Action
 224 {
 225     public function fooAction()
 226     {
 227         $this->render();
 228     }
 229 }
 230 ]]>
 231         </programlisting>
 232
 233         <para>
 234                   上面的例子中，调用<code>/my/foo</code>会使得最终响应对象中的内容呈现下面的结构：
 235         </para>
 236
 237         <programlisting role="php"><![CDATA[
 238 array(
 239     'header'  => ..., // header content
 240     'default' => ..., // body content from MyController::fooAction()
 241     'footer'  => ...  // footer content
 242 );
 243 ]]>
 244         </programlisting>
 245
 246         <para>
 247             渲染响应时，会按照数组中元素顺序来渲染。
 248         </para>
 249
 250         <para>
 251             大量的方法可以用来处理命名片段：
 252         </para>
 253
 254         <itemizedlist>
 255             <listitem>
 256                 <para>
 257                     <code>setBody()</code> 和 <code>appendBody()</code> 都允许传入一个<code>$name</code>参数，指示一个命名片段。如果提供了这个参数，将会覆盖指定的命名片段，如果该片段不存在就创建一个。如果没有传入<code>$name</code>参数到<code>setBody()</code>，将会重置整个主体内容。如果没有传入<code>$name</code>参数到<code>appendBody()</code>，内容被附加到'default'命名片段。
 258                 </para>
 259             </listitem>
 260
 261             <listitem>
 262                 <para>
 263                     <code>prepend($name, $content)</code> 将创建一个<code>$name</code>命名片段并放置在数组的开始位置。如果该片段存在，将首先移除。
 264                 </para>
 265             </listitem>
 266
 267             <listitem>
 268                 <para>
 269                     <code>append($name, $content)</code> 将创建一个<code>$name</code>命名片段，并放置在数组的结尾位置。 如果该片段存在，将首先移除。
 270                 </para>
 271             </listitem>
 272
 273             <listitem>
 274                 <para>
 275                     <code>insert($name, $content, $parent = null, $before = false)</code> 将创建一个<code>$name</code>命名片段。如果提供<code>$parent</code>参数，新的片段视<code>$before</code>的值决定放置在       <code>$parent</code>的前面或者后面。如果该片段存在，将首先移除。
 276                 </para>
 277             </listitem>
 278
 279             <listitem>
 280                 <para>
 281                     <code>clearBody($name = null)</code> 如果<code>$name</code>参数提供，将删除该片段，否则删除全部。
 282                 </para>
 283             </listitem>
 284
 285             <listitem>
 286                 <para>
 287                     <code>getBody($spec = false)</code> 如果<code>$spec</code>参数为一个片段名称，将可以获取到该字段。若<code>$spec</code>参数为false，将返回字符串格式的命名片段顺序链。如果<code>$spec</code>参数为true,返回主体内容数组。
 288                 </para>
 289             </listitem>
 290         </itemizedlist>
 291     </sect2>
 292
 293     <sect2 id="zend.controller.response.exceptions">
 294         <title>在响应对象中测试异常</title>
 295
 296         <para>
 297                   如上文所述，默认的，分发过程中的异常发生会在响应对象中注册。异常会注册在一个堆中，允许你抛出所有异常--程序异常，分发异常，插件异常等。如果你要检查或者记录特定的异常，你可能想要使用响应对象的异常API：
 298         </para>
 299
 300         <itemizedlist>
 301             <listitem>
 302                 <para>
 303                     <code>setException(Exception $e)</code> 注册一个异常。
 304                 </para>
 305             </listitem>
 306
 307             <listitem>
 308                 <para>
 309                     <code>isException()</code> 判断该异常是否注册。
 310                 </para>
 311             </listitem>
 312
 313             <listitem>
 314                 <para>
 315                     <code>getException()</code> 返回整个异常堆。
 316                 </para>
 317             </listitem>
 318
 319             <listitem>
 320                 <para>
 321                     <code>hasExceptionOfType($type)</code> 判断特定类的异常是否在堆中。
 322                 </para>
 323             </listitem>
 324
 325             <listitem>
 326                 <para>
 327                     <code>hasExceptionOfMessage($message)</code> 判断带有指定消息的异常是否在堆中。
 328                 </para>
 329             </listitem>
 330
 331             <listitem>
 332                 <para>
 333                     <code>hasExceptionOfCode($code)</code> 判断带有指定代码的异常是否在堆中。
 334                 </para>
 335             </listitem>
 336
 337             <listitem>
 338                 <para>
 339                     <code>getExceptionByType($type)</code> 获取堆中特定类的所有异常。如果没有则返回false，否则返回数组。
 340                 </para>
 341             </listitem>
 342
 343             <listitem>
 344                 <para>
 345                     <code>getExceptionByMessage($message)</code> 获取堆中带有特定消息的所有异常。如果没有则返回false，否则返回数组。
 346                 </para>
 347             </listitem>
 348
 349             <listitem>
 350                 <para>
 351                     <code>getExceptionByCode($code)</code> 获取堆中带有特定编码的所有异常。如果没有则返回false，否则返回数组。
 352                 </para>
 353             </listitem>
 354
 355             <listitem>
 356                 <para>
 357                     <code>renderExceptions($flag)</code> 设置标志指示当发送响应时是否发送其中的异常。
 358                 </para>
 359             </listitem>
 360         </itemizedlist>
 361     </sect2>
 362
 363     <sect2 id="zend.controller.response.subclassing">
 364         <title>子类化响应对象</title>
 365
 366         <para>
 367                   响应对象的目的首先在于从大量的动作和插件中收集消息头和内容，然后返回到客户端；其次，响应对象也收集发生的任何异常，以处理或者返回这些异常，再或者对终端用户隐藏它们。
 368         </para>
 369
 370         <para>
 371                   响应的基类是<code>Zend_Controller_Response_Abstract</code>，创建的任何子类必须继承这个类或它的衍生类。前面的章节中已经列出了大量可用的方法。
 372         </para>
 373
 374         <para>
 375                   子类化响应对象的原因包括基于请求环境修改返回的内容的输出方式（例如：在CLI和PHP-GTK请求中不发送消息头）增加返回存储在命名片段中内容的最终视图的功能等等。
 376         </para>
 377     </sect2>
 378 </sect1>
 379
 380 <!--
 381 vim:se ts=4 sw=4 et:
 382 -->