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

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!-- EN-Revision: 20765 -->
   3 <!-- Reviewed: no -->
   4 <sect3 id="zend.controller.plugins.standard.errorhandler">
   5     <title>Zend_Controller_Plugin_ErrorHandler</title>
   6
   7     <para>
   8         <classname>Zend_Controller_Plugin_ErrorHandler</classname> est un plugin intégré par défaut
   9         pour gérer les exceptions levées par votre application, il sert à gérer les exceptions
  10         envoyées par l'application, en particulier celles concernant des contrôleurs ou des actions
  11         manquants. C'est une manière rejoignant la section
  12         <link linkend="zend.controller.exceptions">Exceptions MVC</link>.
  13     </para>
  14
  15     <para>Les principaux objectifs de ce plugin sont&#160;:</para>
  16
  17     <itemizedlist>
  18          <listitem>
  19             <para>Intercepter les exceptions envoyées si aucune route ne correspond</para>
  20         </listitem>
  21         <listitem>
  22             <para>
  23                 Intercepter les exceptions envoyées si un contrôleur ou une action ne peuvent
  24                 être trouvés
  25             </para>
  26         </listitem>
  27         <listitem>
  28             <para>Intercepte les exceptions envoyées dans les contrôleurs</para>
  29         </listitem>
  30     </itemizedlist>
  31
  32     <para>
  33         Globalement, <emphasis>ErrorHandler</emphasis> sert à gérer les erreurs
  34         <acronym>HTTP</acronym> 404 ou 500. Attention, le plugin n'est pas destiné à intervenir sur
  35         les exceptions envoyées dans d'autres plugins. Des effets de bords peuvent apparaître,
  36         veillez à les gérer.
  37     </para>
  38
  39     <para>
  40         Par défaut, <classname>Zend_Controller_Plugin_ErrorHandler</classname> redirige vers
  41         <methodname>ErrorController::errorAction()</methodname> dans le module par défaut. Vous
  42         pouvez passer d'autres valeurs via les accesseurs du plugin&#160;:
  43     </para>
  44
  45     <itemizedlist>
  46         <listitem>
  47             <para>
  48                 <methodname>setErrorHandlerModule()</methodname> définit le module à utiliser.
  49             </para>
  50         </listitem>
  51         <listitem>
  52             <para>
  53                 <methodname>setErrorHandlerController()</methodname> définit le contrôleur à
  54                 utiliser.
  55             </para>
  56         </listitem>
  57         <listitem>
  58             <para>
  59                 <methodname>setErrorHandlerAction()</methodname> définit l'action à utiliser.
  60             </para>
  61         </listitem>
  62         <listitem>
  63             <para>
  64                 <methodname>setErrorHandler()</methodname> est un raccourci des trois précédantes.
  65                 Passez un tableau avec les clés "module", "controller", or "action", et leurs
  66                 valeurs appropriées.
  67             </para>
  68         </listitem>
  69     </itemizedlist>
  70
  71     <para>
  72         Ce comportement fonctionne aussi avec le constructeur du plugin. Celui-ci agit comme
  73         un proxy vers <methodname>setErrorHandler()</methodname>.
  74     </para>
  75
  76     <para>
  77         <classname>Zend_Controller_Plugin_ErrorHandler</classname> agit en
  78         <methodname>postDispatch()</methodname> et analyse
  79         <link linkend="zend.controller.response">l'objet de réponse</link>à la recherche
  80         d'éventuelles exceptions. Si il y en a, alors le plugin modifie la requête pour distribuer
  81         le contrôleur et l'action d'erreur.
  82     </para>
  83
  84     <para>
  85         Si une exception arrive lorsque le plugin agit, alors celui-ci ordonne au contrôleur
  86         frontal de renvoyer l'exception, et relance la dernière exception enregistrée dans l'objet
  87         de réponse.
  88     </para>
  89
  90     <sect4 id="zend.controller.plugins.standard.errorhandler.fourohfour">
  91         <title>Utilisation de ErrorHandler pour gérer les erreurs 404</title>
  92
  93         <para>
  94             Comme <emphasis>ErrorHandler</emphasis> capture les exceptions relatives à un problème
  95             de contrôleur ou action manquants, vous pouvez donc l'utiliser comme un gestionnaire
  96             d'erreurs 404. Pour cela, il faut analyser le type d'exception ayant mené à l'erreur.
  97         </para>
  98
  99         <para>
 100             Les exceptions capturées sont enregistrées en tant que paramètre d'action.
 101             <methodname>Zend_Controller_Action::_getParam('error_handler')</methodname>:
 102         </para>
 103
 104         <programlisting language="php"><![CDATA[
 105 class ErrorController extends Zend_Controller_Action
 106 {
 107     public function errorAction()
 108     {
 109         $errors = $this->_getParam('error_handler');
 110     }
 111 }
 112 ]]></programlisting>
 113
 114         <para>
 115             Une fois que vous possédez l'objet contenant l'exception, inspectez son type avec
 116             <command>$errors->type;</command>. Des constantes sont à votre disposition&#160;:
 117         </para>
 118
 119         <itemizedlist>
 120              <listitem>
 121                  <para>
 122                     <constant>Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE</constant>,
 123                     indique qu'aucune route correspondante n'a été trouvée.
 124                 </para>
 125             </listitem>
 126             <listitem>
 127                 <para>
 128                     <constant>Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER</constant>,
 129                     indique un contrôleur non trouvé.
 130                 </para>
 131             </listitem>
 132             <listitem>
 133                 <para>
 134                     <constant>Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION</constant>,
 135                     indique qu'une action est absente.
 136                 </para>
 137             </listitem>
 138             <listitem>
 139                 <para>
 140                     <constant>Zend_Controller_Plugin_ErrorHandler::EXCEPTION_OTHER</constant>,
 141                     indique une autre exception.
 142                 </para>
 143             </listitem>
 144         </itemizedlist>
 145
 146         <para>Les trois premiers types pourraient mener à une erreur 404&#160;:</para>
 147
 148         <programlisting language="php"><![CDATA[
 149 class ErrorController extends Zend_Controller_Action
 150 {
 151     public function errorAction()
 152     {
 153         $errors = $this->_getParam('error_handler');
 154
 155         switch ($errors->type) {
 156             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
 157             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
 158             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
 159                 // erreur 404 -- contrôleur ou action introuvable
 160                 $this->getResponse()->setRawHeader('HTTP/1.1 404 Not Found');
 161
 162                 // ... ici, de l'affichage (du rendu)
 163                 break;
 164             default:
 165                 // erreur applicative; affiche une page d'erreur,
 166                 // mais sans changer le code de retour HTTP
 167                 break;
 168         }
 169     }
 170 }
 171 ]]></programlisting>
 172
 173         <para>
 174             Enfin, il est possible de récupérer l'exception ayant menée au contrôleur
 175             d'erreur. Ceci afin de l'analyser. L'attribut <property>exception</property> de
 176             l'objet <emphasis>error_handler</emphasis> le permet&#160;:
 177         </para>
 178
 179         <programlisting language="php"><![CDATA[
 180 public function errorAction()
 181 {
 182         $errors = $this->_getParam('error_handler');
 183
 184         switch ($errors->type) {
 185             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
 186             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
 187             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
 188                 // erreur 404 -- contrôleur ou action introuvable
 189                 $this->getResponse()->setRawHeader('HTTP/1.1 404 Not Found');
 190
 191                 // ... ici, de l'affichage (du rendu)
 192                 break;
 193             default:
 194                 // erreur applicative; affiche une page d'erreur,
 195                 // mais sans changer le code de retour HTTP
 196
 197                 // ...
 198
 199                 // Sauve l'exception en log:
 200                 $exception = $errors->exception;
 201                 $log =
 202                     new Zend_Log(
 203                         new Zend_Log_Writer_Stream(
 204                             '/tmp/applicationException.log')
 205                     );
 206                 $log->debug($exception->getMessage()
 207                           . "\n"
 208                           . $exception->getTraceAsString());
 209                 break;
 210         }
 211 }
 212 ]]></programlisting>
 213     </sect4>
 214
 215     <sect4 id="zend.controller.plugins.standard.errorhandler.buffer">
 216         <title>Gestion des rendus précédants de la réponse</title>
 217
 218         <para>
 219             Si vous décomposez vos processus en plusieurs actions ou plusieurs appels à
 220             <methodname>render()</methodname>, il est possible que la réponse contienne déjà des
 221             éléments. Ceci peut introduire un mélange entre le rendu attendu et le contenu de
 222             l'erreur.
 223         </para>
 224
 225         <para>
 226             Si vous désirez rendre votre contrôleur d'erreur dans ce contenu, alors il n'y a
 227             rien à faire de spécial. En revanche, il peut aussi être judicieux de vider totalement
 228             la réponse afin de rendre le contrôleur d'erreurs. Procédez alors comme suit&#160;:
 229         </para>
 230
 231         <programlisting language="php"><![CDATA[
 232 $this->getResponse()->clearBody();
 233 ]]></programlisting>
 234     </sect4>
 235
 236     <sect4 id="zend.controller.plugins.standard.errorhandler.examples">
 237         <title>Exemples d'utilisation</title>
 238
 239         <example id="zend.controller.plugins.standard.errorhandler.examples.example-1">
 240             <title>Utilisation standard et désactivation</title>
 241
 242             <programlisting language="php"><![CDATA[
 243 $front = Zend_Controller_Front::getInstance();
 244 $front->registerPlugin(new Zend_Controller_Plugin_ErrorHandler());
 245 ]]></programlisting>
 246         </example>
 247
 248         <example id="zend.controller.plugins.standard.errorhandler.examples.example-2">
 249             <title>Paramétrage du plugin</title>
 250
 251             <programlisting language="php"><![CDATA[
 252 $front = Zend_Controller_Front::getInstance();
 253 $front->registerPlugin(new Zend_Controller_Plugin_ErrorHandler(array(
 254     'module'     => 'mystuff',
 255     'controller' => 'static',
 256     'action'     => 'error'
 257 )));
 258 ]]></programlisting>
 259         </example>
 260
 261         <example id="zend.controller.plugins.standard.errorhandler.examples.example-3">
 262             <title>Utilisation des accesseurs</title>
 263
 264             <programlisting language="php"><![CDATA[
 265 $plugin = new Zend_Controller_Plugin_ErrorHandler();
 266 $plugin->setErrorHandlerModule('mystuff')
 267        ->setErrorHandlerController('static')
 268        ->setErrorHandlerAction('error');
 269
 270 $front = Zend_Controller_Front::getInstance();
 271 $front->registerPlugin($plugin);
 272 ]]></programlisting>
 273         </example>
 274     </sect4>
 275
 276     <sect4 id="zend.controller.plugins.standard.errorhandler.controllerexamples">
 277         <title>Exemple de contrôleur d'erreurs</title>
 278
 279         <para>
 280             Pour utiliser le plugin de gestion d'erreurs, un contrôleur d'erreurs est
 281             requis. En voici un exemple&#160;:
 282         </para>
 283
 284         <programlisting language="php"><![CDATA[
 285 class ErrorController extends Zend_Controller_Action
 286 {
 287     public function errorAction()
 288     {
 289         $errors = $this->_getParam('error_handler');
 290
 291         switch ($errors->type) {
 292             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
 293             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
 294             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
 295                 // 404 error -- controller or action not found
 296                 $this->getResponse()->setRawHeader('HTTP/1.1 404 Not Found');
 297
 298                 $content =<<<EOH
 299 <h1>Erreur !</h1>
 300 <p>Page introuvable.</p>
 301 EOH;
 302                 break;
 303             default:
 304                 // application error
 305                 $content =<<<EOH
 306 <h1>Erreur !</h1>
 307 <p>Une erreur innatendue est survenue</p>
 308 EOH;
 309                 break;
 310         }
 311
 312         // Vide le contenu de la réponse
 313         $this->getResponse()->clearBody();
 314
 315         $this->view->content = $content;
 316     }
 317 }
 318 ]]></programlisting>
 319     </sect4>
 320 </sect3>