documentation/manual/en/module_specs/Zend_Controller-Plugins-ErrorHandler.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.controller.plugins.standard.errorhandler">
   4     <title>Zend_Controller_Plugin_ErrorHandler</title>
   5
   6     <para>
   7         <classname>Zend_Controller_Plugin_ErrorHandler</classname> provides a drop-in
   8         plugin for handling exceptions thrown by your application, including
   9         those resulting from missing controllers or actions; it is an
  10         alternative to the methods listed in the <link
  11             linkend="zend.controller.exceptions">MVC Exceptions section</link>.
  12     </para>
  13
  14     <para>
  15         The primary targets of the plugin are:
  16     </para>
  17
  18     <itemizedlist>
  19         <listitem>
  20             <para>Intercept exceptions raised when no route matched</para>
  21         </listitem>
  22
  23         <listitem>
  24             <para>Intercept exceptions raised due to missing controllers or action methods</para>
  25         </listitem>
  26
  27         <listitem>
  28             <para>Intercept exceptions raised within action controllers</para>
  29         </listitem>
  30     </itemizedlist>
  31
  32     <para>
  33         In other words, the <emphasis>ErrorHandler</emphasis> plugin is designed to
  34         handle <acronym>HTTP</acronym> 404-type errors (page missing) and 500-type errors (internal
  35         error). It is not intended to catch exceptions raised in other plugins.
  36     </para>
  37
  38     <para>
  39         By default, <classname>Zend_Controller_Plugin_ErrorHandler</classname> will
  40         forward to <methodname>ErrorController::errorAction()</methodname> in the default
  41         module. You may set alternate values for these by using the various
  42         accessors available to the plugin:
  43     </para>
  44
  45     <itemizedlist>
  46         <listitem>
  47             <para>
  48                 <methodname>setErrorHandlerModule()</methodname> sets the controller module to use.
  49             </para>
  50         </listitem>
  51
  52         <listitem>
  53             <para>
  54                 <methodname>setErrorHandlerController()</methodname> sets the controller to use.
  55             </para>
  56         </listitem>
  57
  58         <listitem>
  59             <para>
  60                 <methodname>setErrorHandlerAction()</methodname> sets the controller action to use.
  61             </para>
  62         </listitem>
  63
  64         <listitem>
  65             <para>
  66                 <methodname>setErrorHandler()</methodname> takes an associative array, which
  67                 may contain any of the keys 'module', 'controller', or 'action',
  68                 with which it will set the appropriate values.
  69             </para>
  70         </listitem>
  71     </itemizedlist>
  72
  73     <para>
  74         Additionally, you may pass an optional associative array to the
  75         constructor, which will then proxy to <methodname>setErrorHandler()</methodname>.
  76     </para>
  77
  78     <para>
  79         <classname>Zend_Controller_Plugin_ErrorHandler</classname> registers a
  80         <methodname>postDispatch()</methodname> hook and checks for exceptions registered in
  81         <link linkend="zend.controller.response">the response object</link>. If
  82         any are found, it attempts to forward to the registered error handler
  83         action.
  84     </para>
  85
  86     <para>
  87         If an exception occurs dispatching the error handler, the plugin will
  88         tell the front controller to throw exceptions, and rethrow the last
  89         exception registered with the response object.
  90     </para>
  91
  92     <sect4 id="zend.controller.plugins.standard.errorhandler.fourohfour">
  93         <title>Using the ErrorHandler as a 404 Handler</title>
  94
  95         <para>
  96             Since the <emphasis>ErrorHandler</emphasis> plugin captures not only
  97             application errors, but also errors in the controller chain arising
  98             from missing controller classes and/or action methods, it can be
  99             used as a 404 handler. To do so, you will need to have your error
 100             controller check the exception type.
 101         </para>
 102
 103         <para>
 104             Exceptions captured are logged in an object registered in the
 105             request. To retrieve it, use
 106             <methodname>Zend_Controller_Action::_getParam('error_handler')</methodname>:
 107         </para>
 108
 109         <programlisting language="php"><![CDATA[
 110 class ErrorController extends Zend_Controller_Action
 111 {
 112     public function errorAction()
 113     {
 114         $errors = $this->_getParam('error_handler');
 115     }
 116 }
 117 ]]></programlisting>
 118
 119         <para>
 120             Once you have the error object, you can get the type via
 121             <command>$errors->type;</command>. It will be one of the following:
 122         </para>
 123
 124         <itemizedlist>
 125             <listitem>
 126                 <para>
 127                     <constant>Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE</constant>,
 128                     indicating no route matched.
 129                 </para>
 130             </listitem>
 131
 132             <listitem>
 133                 <para>
 134                     <constant>Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER</constant>,
 135                     indicating the controller was not found.
 136                 </para>
 137             </listitem>
 138
 139             <listitem>
 140                 <para>
 141                     <constant>Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION</constant>,
 142                     indicating the requested action was not found.
 143                 </para>
 144             </listitem>
 145
 146             <listitem>
 147                 <para>
 148                     <constant>Zend_Controller_Plugin_ErrorHandler::EXCEPTION_OTHER</constant>,
 149                     indicating other exceptions.
 150                 </para>
 151             </listitem>
 152         </itemizedlist>
 153
 154         <para>
 155             You can then test for either of the first three types, and, if so,
 156             indicate a 404 page:
 157         </para>
 158
 159         <programlisting language="php"><![CDATA[
 160 class ErrorController extends Zend_Controller_Action
 161 {
 162     public function errorAction()
 163     {
 164         $errors = $this->_getParam('error_handler');
 165
 166         switch ($errors->type) {
 167             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
 168             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
 169             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
 170                 // 404 error -- controller or action not found
 171                 $this->getResponse()
 172                      ->setRawHeader('HTTP/1.1 404 Not Found');
 173
 174                 // ... get some output to display...
 175                 break;
 176             default:
 177                 // application error; display error page, but don't
 178                 // change status code
 179                 break;
 180         }
 181     }
 182 }
 183 ]]></programlisting>
 184
 185         <para>
 186             Finally, you can retrieve the exception that triggered the error
 187             handler by grabbing the <property>exception</property> property of the
 188             <emphasis>error_handler</emphasis> object:
 189         </para>
 190
 191         <programlisting language="php"><![CDATA[
 192 public function errorAction()
 193 {
 194         $errors = $this->_getParam('error_handler');
 195
 196         switch ($errors->type) {
 197             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
 198             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
 199             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
 200                 // 404 error -- controller or action not found
 201                 $this->getResponse()
 202                      ->setRawHeader('HTTP/1.1 404 Not Found');
 203
 204                 // ... get some output to display...
 205                 break;
 206             default:
 207                 // application error; display error page, but don't change
 208                 // status code
 209
 210                 // ...
 211
 212                 // Log the exception:
 213                 $exception = $errors->exception;
 214                 $log = new Zend_Log(
 215                     new Zend_Log_Writer_Stream(
 216                         '/tmp/applicationException.log'
 217                     )
 218                 );
 219                 $log->debug($exception->getMessage() . "\n" .
 220                             $exception->getTraceAsString());
 221                 break;
 222         }
 223 }
 224 ]]></programlisting>
 225     </sect4>
 226
 227     <sect4 id="zend.controller.plugins.standard.errorhandler.buffer">
 228         <title>Handling Previously Rendered Output</title>
 229
 230         <para>
 231             If you dispatch multiple actions in a request, or if your action
 232             makes multiple calls to <methodname>render()</methodname>, it's possible that the
 233             response object already has content stored within it. This can lead
 234             to rendering a mixture of expected content and error content.
 235         </para>
 236
 237         <para>
 238             If you wish to render errors inline in such pages, no changes will
 239             be necessary. If you do not wish to render such content, you should
 240             clear the response body prior to rendering any views:
 241         </para>
 242
 243         <programlisting language="php"><![CDATA[
 244 $this->getResponse()->clearBody();
 245 ]]></programlisting>
 246     </sect4>
 247
 248     <sect4 id="zend.controller.plugins.standard.errorhandler.examples">
 249         <title>Plugin Usage Examples</title>
 250
 251         <example id="zend.controller.plugins.standard.errorhandler.examples.example-1">
 252             <title>Standard Usage</title>
 253
 254             <programlisting language="php"><![CDATA[
 255 $front = Zend_Controller_Front::getInstance();
 256 $front->registerPlugin(new Zend_Controller_Plugin_ErrorHandler());
 257 ]]></programlisting>
 258         </example>
 259
 260         <example id="zend.controller.plugins.standard.errorhandler.examples.example-2">
 261             <title>Setting a Different Error Handler</title>
 262
 263             <programlisting language="php"><![CDATA[
 264 $front = Zend_Controller_Front::getInstance();
 265 $front->registerPlugin(new Zend_Controller_Plugin_ErrorHandler(array(
 266     'module'     => 'mystuff',
 267     'controller' => 'static',
 268     'action'     => 'error'
 269 )));
 270 ]]></programlisting>
 271         </example>
 272
 273         <example id="zend.controller.plugins.standard.errorhandler.examples.example-3">
 274             <title>Using Accessors</title>
 275
 276             <programlisting language="php"><![CDATA[
 277 $plugin = new Zend_Controller_Plugin_ErrorHandler();
 278 $plugin->setErrorHandlerModule('mystuff')
 279        ->setErrorHandlerController('static')
 280        ->setErrorHandlerAction('error');
 281
 282 $front = Zend_Controller_Front::getInstance();
 283 $front->registerPlugin($plugin);
 284 ]]></programlisting>
 285         </example>
 286     </sect4>
 287
 288     <sect4 id="zend.controller.plugins.standard.errorhandler.controllerexamples">
 289         <title>Error Controller Example</title>
 290
 291         <para>
 292             In order to use the Error Handler plugin, you need an error
 293             controller. Below is a simple example.
 294         </para>
 295
 296         <programlisting language="php"><![CDATA[
 297 class ErrorController extends Zend_Controller_Action
 298 {
 299     public function errorAction()
 300     {
 301         $errors = $this->_getParam('error_handler');
 302
 303         switch ($errors->type) {
 304             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
 305             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
 306             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
 307                 // 404 error -- controller or action not found
 308                 $this->getResponse()->setRawHeader('HTTP/1.1 404 Not Found');
 309
 310                 $content =<<<EOH
 311 <h1>Error!</h1>
 312 <p>The page you requested was not found.</p>
 313 EOH;
 314                 break;
 315             default:
 316                 // application error
 317                 $content =<<<EOH
 318 <h1>Error!</h1>
 319 <p>An unexpected error occurred. Please try again later.</p>
 320 EOH;
 321                 break;
 322         }
 323
 324         // Clear previous content
 325         $this->getResponse()->clearBody();
 326
 327         $this->view->content = $content;
 328     }
 329 }
 330 ]]></programlisting>
 331     </sect4>
 332 </sect3>
 333 <!--
 334 vim:se ts=4 sw=4 et:
 335 -->