Aides d'action (Helper)
Zend_Controller
Programmer's Reference Guide

Objet de réponse

Utilisation

L'objet de réponse équilibre la balance du modèle MVC avec l'objet de requête. Son but est de collecter du contenu et des en-têtes, afin d'être rendue. De plus, le contrôleur frontal passe les exceptions qu'il a rencontré à l'objet de réponse, vous offrant une possibilité élégante de les gérer. Ce comportement peut être changé avec Zend_Controller_Front::throwExceptions(true) :

  1. $front->throwExceptions(true);

Pour rendre toute la réponse : corps et en-têtes, utilisez sendResponse().

  1. $response->sendResponse();

Note: Par défaut le contrôleur frontal appelle sendResponse() lorsque la distribution est terminée. Vous pouvez changer ce comportement avec Zend_Controller_Front::returnResponse(true) :

  1. $front->returnResponse(true);
  2. $response = $front->dispatch();
  3.  
  4. // opérations, comme une historisation...
  5. // et rendu de la réponse:
  6. $response->sendResponse();

Vous ne devriez pas afficher du contenu directement dans un contrôleur. Empiler plutôt les affichages dans l'objet de réponse :

  1. // Dans une action d'un contrôleur:
  2. $this->getResponse()
  3.     ->setHeader('Content-Type', 'text/html')
  4.     ->appendBody($content);

Grâce à cela, tous les en-têtes sont envoyés d'un coup, juste avant l'affichage du contenu.

Note: Si vous utilisez des vues dans vos action, vous n'avez pas besoin d'ajouter le rendu de la vue dans la réponse, car Zend_Controller_Action::render() le fait par défaut.

Si une exception est ajoutée par le contrôleur frontal à la réponse, utilisez isException() pour vérifier ceci, et récupérez les exceptions avec getException(). Vous pourriez par exemple créer un objet de réponse d'erreur, comme un 404, et journaliser l'exception, etc.

Pour prendre la main sur l'objet de réponse, demandez le au contrôleur frontal via un accesseur, ou commandez lui de vous retourner la celle-ci lors après la distribution.

  1. // récupère la réponse après distribution et affichage:
  2. $front->dispatch();
  3. $response = $front->getResponse();
  4. if ($response->isException()) {
  5.     // log, mail, etc...
  6. }
  7.  
  8. // Demande au contrôleur frontal de ne pas afficher, mais retourner :
  9. $front->returnResponse(true);
  10. $response = $front->dispatch();
  11.  
  12. // du code ici
  13.  
  14. // enfin, affichage:
  15. $response->sendResponse();

Par défaut, les messages d'exceptions ne sont pas affichés. Utilisez renderExceptions() si vous le voulez. Aussi, vous pouvez activer leur rendu grâce à Zend_Controller_Front::throwExceptions() :

  1. $response->renderExceptions(true);
  2. $front->dispatch($request, $response);
  3.  
  4. // ou:
  5. $front->returnResponse(true);
  6. $response = $front->dispatch();
  7. $response->renderExceptions();
  8. $response->sendResponse();
  9.  
  10. // ou:
  11. $front->throwExceptions(true);
  12. $front->dispatch();

Manipulation des en-têtes

Comme nous l'avons vu, un des rôles de l'objet de réponse est de gérer les en-têtes HTTP. Une variété de méthodes permet de contrôler cette gestion :

  • canSendHeaders($throw = false) est utilisée pour déterminer si les en-têtes n'ont pas déjà été envoyés. Si le paramètre optionnel $throw est à TRUE, alors une exception sera envoyée si c'est le cas. L'attribut headersSentThrowsException permet aussi de gérer ce comportement.

  • setHeader($name, $value, $replace = false) est utilisée pour affecter un en-tête unique. Par défaut, il n'écrase un éventuel précédent du même nom, sauf si $replace est mis à TRUE.

    Avant d'affecter un en-tête, cette méthode utilise canSendHeaders() pour voir si à ce point l'en-tête peut être envoyé.

  • setRedirect($url, $code = 302) envoie un en-tête HTTP Location indiquant une redirection. Si un code de statut est passé, il sera utilisé.

    En interne, cette méthode appelle setHeader() avec $replace à TRUE, pour s'assurer de l'unicité de cet en-tête.

  • getHeaders() retourne un tableau contenant tous les en-têtes. Chaque élément est un tableau "nom" 'valeur.

  • clearHeaders() efface tous les en-têtes enregistrés.

  • setRawHeader() s'utilise pour affecter un en-tête brut, n'utilisant pas la syntaxe clé/valeur, comme un statut.

  • getRawHeaders() retourne tous les en-têtes bruts enregistrés.

  • clearRawHeaders() efface tous les en-têtes bruts enregistrés.

  • clearAllHeaders() efface tous les en-têtes bruts et réguliers enregistrés.

De plus, des accesseurs spéciaux sont disponibles pour manipuler le code de réponse HTTP : setHttpResponseCode() et getHttpResponseCode().

Segments nommés

L'objet de réponse propose une fragmentation par segments. Ceci permet de séparer le corps de la réponse dans plusieurs segments réceptacles, que vous pouvez afficher dans un ordre précis. En interne, il s'agit d'un tableau namespacé qui dispose de méthodes de manipulation.

Par exemple, vous pourriez utiliser l'évènement preDispatch() pour rajouter un bandeau de header au corps de la réponse, et l'évènement postDispatch() pour en ajouter un bandeau de footer :

  1. // Considérons ce plugin comme étant enregistré
  2. // auprès du contrôleur frontal
  3. class MyPlugin extends Zend_Controller_Plugin_Abstract
  4. {
  5.     public function preDispatch(Zend_Controller_Request_Abstract $request)
  6.     {
  7.         $response = $this->getResponse();
  8.         $view = new Zend_View();
  9.         $view->setBasePath('../views/scripts');
  10.  
  11.         $response->prepend('header', $view->render('header.phtml'));
  12.     }
  13.  
  14.     public function postDispatch(Zend_Controller_Request_Abstract $request)
  15.     {
  16.         $response = $this->getResponse();
  17.         $view = new Zend_View();
  18.         $view->setBasePath('../views/scripts');
  19.  
  20.         $response->append('footer', $view->render('footer.phtml'));
  21.     }
  22. }
  23.  
  24. // un contrôleur d'action
  25. class MyController extends Zend_Controller_Action
  26. {
  27.     public function fooAction()
  28.     {
  29.         $this->render();
  30.     }
  31. }

Un appel à /my/foo dans ce cas là, générera un objet de réponse ressemblant à ceci :

  2.     'header'  => ..., // contenu du segment header
  3.     'default' => ..., // corps, contenu de MyController::fooAction()
  4.     'footer'  => ...  // contenu du segment footer
  5. );

Lorsque ceci est rendu, ça l'est dans l'ordre dans lequel les segments sont rangés dans la réponse.

Voici quelques méthodes permettant de manipuler les segments de la réponse :

  • setBody() et appendBody() effacent et écrivent, ou rajoutent un contenu à un segment qu'on leur indique en deuxième paramètre ($name). Si celui-ci n'existe pas, il sera crée en fin de pile. Si le paramètre segment n'est pas défini, alors le segment "default"est utilisé.

  • prepend($name, $content) va créer un segment appelé $name et le placé au début du tableau. Si le segment existe, il sera écrasé.

  • append($name, $content) va créer un segment appelé $name et le placer à la fin du tableau. Si le segment existe, il sera écrasé.

  • insert($name, $content, $parent = null, $before = false) va créer un segment appelé $name. Si $parent est renseigné, le nouveau segment sera placé avant ou après le segment $parent, ceci dépendant de la valeur de $before. Si le segment existe, il sera écrasé.

  • clearBody($name = null) va vider le contenu du segment qui lui est passé en paramètre via $name. Par défaut, il vide tout le tableau (détruit tous les segments).

  • getBody($spec = false) retourne le contenu du segment $spec. Si $spec vaut FALSE, il retourne le contenu de tous les segments. Si TRUE, c'est le tableau de segments qui est retourné.

Manipulation des exceptions dans l'objet de réponse

Comme déjà mentionné, par défaut, les exceptions rencontrées durant le processus MVC de distribution, sont ajoutées à l'objet de réponse. Elles le sont dans une pile, ce qui vous permet de toutes les garder -- les exceptions d'application, les exceptions de distribution, les exceptions de plugin -- etc... Si vous voulez manipuler finement celles-ci, voyez plutôt les méthodes ci-après :

  • setException(Exception $e) enregistre une exception.

  • isException() est utilisée pour déterminer si il existe au moins une exception.

  • getException() retourne toutes les exceptions sous forme de tableau.

  • hasExceptionOfType($type) sert à déterminer si des exceptions d'une classe spécifique existent.

  • hasExceptionOfMessage($message) sert à déterminer si des exceptions ayant un message spécifique existent.

  • hasExceptionOfCode($code) sert à déterminer si des exceptions ayant un code spécifique existent.

  • getExceptionByType($type) retourne toutes les exceptions d'une classe spécifique. Un tableau est retourné, ou FALSE si aucun exception ne correspond

  • getExceptionByMessage($message) retourne toutes les exceptions ayant un message spécifique. Un tableau est retourné, ou FALSE si aucun exception ne correspond

  • getExceptionByCode($code) retourne toutes les exceptions ayant un code spécifique. Un tableau est retourné, ou FALSE si aucun exception ne correspond.

  • renderExceptions($flag) vous permet de définir si les exceptions doivent être envoyées lorsque la réponse est rendue.

Dériver l'objet de réponse

L'objet de réponse sert à collecter les en-têtes HTTP de la réponse, ainsi que son contenu, depuis le système MVC mais aussi de l'afficher au client. De plus, l'objet collecte les exceptions et permet de les gérer, de les retourner, ou de les garder sous silence.

La classe de base est Zend_Controller_Response_Abstract, et toute dérivation devra en hériter directement ou indirectement. Les méthodes qu'elle propose ont été vues dans les sections précédentes.

Vous pouvez dériver l'objet de réponse pour plusieurs raisons, incluant la volonté de modifier le retour de la sortie, pour ne pas envoyer d'en-têtes dans un environnement de requête CLI ou PHP-GTK, la gestion de templates, etc.

Aides d'action (Helper)
Zend_Controller
Programmer's Reference Guide