# Zend_Http_Response

## Introduction

`Zend_Http_Response` provides easy access to an HTTP responses message, as well as a set of static methods for parsing HTTP response messages. Usually, `Zend_Http_Response` is used as an object returned by a `Zend_Http_Client` request.

In most cases, a `Zend_Http_Response` object will be instantiated using the fromString() method, which reads a string containing a HTTP response message, and returns a new `Zend_Http_Response` object:

### Instantiating a Zend_Http_Response Object Using the Factory Method

    $str = '';
    $sock = fsockopen('www.example.com', 80);
    $req =     "GET / HTTP/1.1\r\n" .
            "Host: www.example.com\r\n" .
            "Connection: close\r\n" .
            "\r\n";

    fwrite($sock, $req);
    while ($buff = fread($sock, 1024))
        $str .= $sock;

    $response = Zend_Http_Response::fromString($str);

You can also use the contractor method to create a new response object, by specifying all the parameters of the response:

`public function __construct($code, $headers, $body = null, $version = '1.1', $message = null)`

- `$code`: The HTTP response code (eg. 200, 404, etc.)

- `$headers`: An associative array of HTTP response headers (eg. 'Host' => 'example.com')

- `$body`: The response body as a string

- `$version`: The HTTP response version (usually 1.0 or 1.1)

- `$message`: The HTTP response message (eg 'OK', 'Internal Server Error'). If not specified, the message will be set according to the response code

## Boolean Tester Methods

Once a `Zend_Http_Response` object is instantiated, it provides several methods that can be used to test the type of the response. These all return Boolean `TRUE` or `FALSE`:

- `isSuccessful()`: Whether the request was successful or not. Returns `TRUE` for HTTP 1xx and 2xx response codes

- `isError()`: Whether the response code implies an error or not. Returns `TRUE` for HTTP 4xx (client errors) and 5xx (server errors) response codes

- `isRedirect()`: Whether the response is a redirection response or not. Returns `TRUE` for HTTP 3xx response codes

### Using the isError() method to validate a response

    if ($response->isError()) {
      echo "Error transmitting data.\n"
      echo "Server reply was: " . $response->getStatus() .
           " " . $response->getMessage() . "\n";
    }
    // .. process the response here...

## Accessor Methods

The main goal of the response object is to provide easy access to various response parameters.

- `getStatus()`: Get the HTTP response status code (eg. 200, 504, etc.)

- `getMessage()`: Get the HTTP response status message (eg. "Not Found", "Authorization Required")

- `getBody()`: Get the fully decoded HTTP response body

- `getRawBody()`: Get the raw, possibly encoded HTTP response body. if the body was decoded using GZIP encoding for example, it will not be decoded.

- `getHeaders()`: Get the HTTP response headers as an associative array (eg. 'Content-type' => 'text/html')

- `getHeader($header)`: Get a specific HTTP response header, specified by $header

- `getHeadersAsString($status_line, $br)`: Get the entire set of headers as a string. If `$status_line` is `TRUE` (default), the first status line (eg. "HTTP/1.1 200 OK") will also be returned. Lines are broken with the `$br` parameter (Can be, for example, "<br />". Default "\n")

- `asString($br)`: Get the entire response message as a string. Lines are broken with the $br parameter (Can be, for example, "<br />". Default "\n"). You can also use the magic method `__toString()` when casting the object as a string. It will then proxy to `asString()`.

### Using Zend_Http_Response Accessor Methods

    if ($response->getStatus() == 200) {
      echo "The request returned the following information:<br />";
      echo $response->getBody();
    } else {
      echo "An error occurred while fetching data:<br />";
      echo $response->getStatus() . ": " . $response->getMessage();
    }

### Always check return value

Since a response can contain several instances of the same header, the getHeader() method and getHeaders() method may return either a single string, or an array of strings for each header. You should always check whether the returned value is a string or array.

### Accessing Response Headers

    $ctype = $response->getHeader('Content-type');
    if (is_array($ctype)) $ctype = $ctype[0];

    $body = $response->getBody();
    if ($ctype == 'text/html' || $ctype == 'text/xml') {
      $body = htmlentities($body);
    }

    echo $body;

## Static HTTP Response Parsers

The `Zend_Http_Response` class also includes several internally-used methods for processing and parsing HTTP response messages. These methods are all exposed as static methods, which means they can be used externally, even if you do not need to instantiate a response object, and just want to extract a specific part of the response.

- `Zend_Http_Response::extractCode($response_str)`: Extract and return the HTTP response code (eg. 200 or 404) from `$response_str`

- `Zend_Http_Response::extractMessage($response_str)`: Extract and return the HTTP response message (eg. "OK" or "File Not Found") from `$response_str`

- `Zend_Http_Response::extractVersion($response_str)`: Extract and return the HTTP version (eg. 1.1 or 1.0) from `$response_str`

- `Zend_Http_Response::extractHeaders($response_str)`: Extract and return the HTTP response headers from `$response_str` as an array

- `Zend_Http_Response::extractBody($response_str)`: Extract and return the HTTP response body from `$response_str`

- `Zend_Http_Response::responseCodeAsText($code, $http11)`: Get the standard HTTP response message for a response code $code. For example, will return "Internal Server Error" if `$code` is 500. If `$http11` is `TRUE` (default), will return HTTP/1.1 standard messages - otherwise HTTP/1.0 messages will be returned. If `$code` is not specified, this method will return all known HTTP response codes as an associative (code => message) array.

Apart from parser methods, the class also includes a set of decoders for common HTTP response transfer encodings:

- `Zend_Http_Response::decodeChunkedBody($body)`: Decode a complete "Content-Transfer-Encoding: Chunked" body

- `Zend_Http_Response::decodeGzip($body)`: Decode a "Content-Encoding: gzip" body

- `Zend_Http_Response::decodeDeflate($body)`: Decode a "Content-Encoding: deflate" body