ZF Zend Framework

Behind the Site

Programmer's Reference Guide

8.9. The Response Object
Prev  Chapter 8. Zend_Controller  Next

8.9. The Response Object

8.9.1. Usage

The response object is the logical counterpart to the request object. Its purpose is to collate content and/or headers so that they may be returned en masse. Additionally, the front controller will pass any caught exceptions to the response object, allowing the developer to gracefully handle exceptions. This functionality may be overridden by setting Zend_Controller_Front::throwExceptions(true): 


$front->throwExceptions(true);

To send the response output, including headers, use sendResponse(). 


$response->sendResponse();
[Note] Note

By default, the front controller calls sendResponse() when it has finished dispatching the request; typically you will never need to call it. However, if you wish to manipulate the response or use it in testing, you can override this behaviour by setting the returnResponse flag with Zend_Controller_Front::returnResponse(true): 


<?php
$front->returnResponse(true);
$response = $front->dispatch();

// do some more processing, such as logging...
// and then send the output:
$response->sendResponse();

Developers should make use of the response object in their action controllers. Instead of directly rendering output and sending headers, push them to the response object: 


// Within an action controller action:
// Set a header
$this->getResponse()
    ->setHeader('Content-Type', 'text/html')
    ->appendBody($content);

By doing this, all headers get sent at once, just prior to displaying the content.

[Note] Note

If using the action controller view integration, you do not need to set the rendered view script content in the response object, as Zend_Controller_Action::render() does this by default.

Should an exception occur in an application, check the response object's isException() flag, and retrieve the exception using getException(). Additionally, one may create custom response objects that redirect to error pages, log exception messages, do pretty formatting of exception messages (for development environments), etc.

You may retrieve the response object following the front controller dispatch(), or request the front controller to return the response object instead of rendering output. 


// retrieve post-dispatch:
$front->dispatch();
$response = $front->getResponse();
if ($response->isException()) {
    // log, mail, etc...
}

// Or, have the front controller dispatch() process return it
$front->returnResponse(true);
$response = $front->dispatch();

// do some processing...

// finally, echo the response
$response->sendResponse();

By default, exception messages are not displayed. This behaviour may be overridden by calling renderExceptions(), or enabling the front controller to throwExceptions(), as shown above: 


$response->renderExceptions(true);
$front->dispatch($request, $response);

// or:
$front->returnResponse(true);
$response = $front->dispatch();
$response->renderExceptions();
$response->sendResponse();

// or:
$front->throwExceptions(true);
$front->dispatch();

8.9.2. Manipulating Headers

As stated previously, one aspect of the response object's duties is to collect and emit HTTP response headers. A variety of methods exist for this:

  • canSendHeaders() is used to determine if headers have already been sent. It takes an optional flag indicating whether or not to throw an exception if headers have already been sent. This can be overridden by setting the property headersSentThrowsException to false.

  • setHeader($name, $value, $replace = false) is used to set an individual header. By default, it does not replace existing headers of the same name in the object; however, setting $replace to true will force it to do so.

    Before setting the header, it checks with canSendHeaders() to see if this operation is allowed at this point, and requests that an exception be thrown.

  • setRedirect($url, $code = 302) sets an HTTP Location header for a redirect. If an HTTP status code has been provided, it will use that status code.

    Internally, it calls setHeader() with the $replace flag on to ensure only one such header is ever sent.

  • getHeaders() returns an array of all headers. Each array element is an array with the keys 'name' and 'value'.

  • clearHeaders() clears all registered headers.

  • setRawHeader() can be used to set headers that are not key/value pairs, such as an HTTP status header.

  • getRawHeaders() returns any registered raw headers.

  • clearRawHeaders() clears any registered raw headers.

  • clearAllHeaders() clears both regular key/value headers as well as raw headers.

In addition to the above methods, there are accessors for setting and retrieving the HTTP response code for the current request, setHttpResponseCode() and getHttpResponseCode().

8.9.3. Named Segments

The response object has support for "named segments". This allows you to segregate body content into different segments and order those segments so output is returned in a specific order. Internally, body content is saved as an array, and the various accessor methods can be used to indicate placement and names within that array.

As an example, you could use a preDispatch() hook to add a header to the response object, then have the action controller add body content, and a postDispatch() hook add a footer: 


<?php
// Assume that this plugin class is registered with the front controller
class MyPlugin extends Zend_Controller_Plugin_Abstract
{
    public function preDispatch(Zend_Controller_Request_Abstract $request)
    {
        $response = $this->getResponse();
        $view = new Zend_View();
        $view->setBasePath('../views/scripts');

        $response->prepend('header', $view->render('header.phtml'));
    }

    public function postDispatch(Zend_Controller_Request_Abstract $request)
    {
        $response = $this->getResponse();
        $view = new Zend_View();
        $view->setBasePath('../views/scripts');

        $response->append('footer', $view->render('footer.phtml'));
    }
}

// a sample action controller
class MyController extends Zend_Controller_Action
{
    public function fooAction()
    {
        $this->render();
    }
}

In the above example, a call to /my/foo will cause the final body content of the response object to have the following structure: 


<?php
array(
    'header'  => ..., // header content
    'default' => ..., // body content from MyController::fooAction()
    'footer'  => ...  // footer content
);

When this is rendered, it will render in the order in which elements are arranged in the array.

A variety of methods can be used to manipulate the named segments:

  • setBody() and appendBody() both allow you to pass a second value, $name, indicating a named segment. In each case, if you provide this, it will overwrite that specific named segment or create it if it does not exist (appending to the array by default). If no named segment is passed to setBody(), it resets the entire body content array. If no named segment is passed to appendBody(), the content is appended to the value in the 'default' name segment.

  • prepend($name, $content) will create a segment named $name and place it at the beginning of the array. If the segment exists already, it will be removed prior to the operation (i.e., overwritten and replaced).

  • append($name, $content) will create a segment named $name and place it at the end of the array. If the segment exists already, it will be removed prior to the operation (i.e., overwritten and replaced).

  • insert($name, $content, $parent = null, $before = false) will create a segment named $name. If provided with a $parent segment, the new segment will be placed either before or after that segment (based on the value of $before) in the array. If the segment exists already, it will be removed prior to the operation (i.e., overwritten and replaced).

  • clearBody($name = null) will remove a single named segment if a $name is provided (and the entire array otherwise).

  • getBody($spec = false) can be used to retrieve a single array segment if $spec is the name of a named segment. If $spec is false, it returns a string formed by concatenating all named segments in order. If $spec is true, it returns the body content array.

8.9.4. Testing for Exceptions in the Response Object

As mentioned earlier, by default, exceptions caught during dispatch are registered with the response object. Exceptions are registered in a stack, which allows you to keep all exceptions thrown -- application exceptions, dispatch exceptions, plugin exceptions, etc. Should you wish to check for particular exceptions or to log exceptions, you'll want to use the response object's exception API:

  • setException(Exception $e) allows you to register an exception.

  • isException() will tell you if an exception has been registered.

  • getException() returns the entire exception stack.

  • hasExceptionOfType($type) allows you to determine if an exception of a particular class is in the stack.

  • hasExceptionOfMessage($message) allows you to determine if an exception with a specific message is in the stack.

  • hasExceptionOfCode($code) allows you to determine if an exception with a specific code is in the stack.

  • getExceptionByType($type) allows you to retrieve all exceptions of a specific class from the stack. It will return false if none are found, and an array of exceptions otherwise.

  • getExceptionByMessage($message) allows you to retrieve all exceptions with a specific message from the stack. It will return false if none are found, and an array of exceptions otherwise.

  • getExceptionByCode($code) allows you to retrieve all exceptions with a specific code from the stack. It will return false if none are found, and an array of exceptions otherwise.

  • renderExceptions($flag) allows you to set a flag indicating whether or not exceptions should be emitted when the response is sent.

8.9.5. Subclassing the Response Object

The purpose of the response object is to collect headers and content from the various actions and plugins and return them to the client; secondarily, it also collects any errors (exceptions) that occur in order to process them, return them, or hide them from the end user.

The base response class is Zend_Controller_Response_Abstract, and any subclass you create should extend that class or one of its derivatives. The various methods available have been listed in the previous sections.

Reasons to subclass the response object include modifying how output is returned based on the request environment (e.g., not sending headers for CLI or PHP-GTK requests), adding functionality to return a final view based on content stored in named segments, etc.


Prev  Up  Next
8.8. Action Helpers  Home  8.10. Plugins

Search the Manual

Components

Languages Available

Translation Status Reports

View the current status report of Zend Framework manual translations.