repo_zf1/documentation/manual/en/module_specs/Zend_Http_Response.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.http.response">
    <title>Zend_Http_Response</title>

    <sect2 id="zend.http.response.introduction">
        <title>Introduction</title>

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

        <para>
            In most cases, a Zend_Http_Response object will be instantiated
            using the fromString() method, which reads a string containing an HTTP
            response message, and returns a new Zend_Http_Response object:
            <example id="zend.http.response.introduction.example-1">
                <title>Instantiating a Zend_Http_Response Object Using the Factory Method</title>

                <programlisting language="php"><![CDATA[
$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);
]]></programlisting>
            </example>
        </para>

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

        <para>
            <code>public function __construct($code, $headers, $body = null, $version = '1.1',
                $message = null)</code>
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <varname>$code</varname>: The <acronym>HTTP</acronym> response code (eg. 200,
                    404, etc.)
                </para>
            </listitem>

            <listitem>
                <para>
                    <varname>$headers</varname>: An associative array of <acronym>HTTP</acronym>
                    response headers (eg. 'Host' => 'example.com')
                </para>
            </listitem>

            <listitem>
                <para>
                    <varname>$body</varname>: The response body as a string
                </para>
            </listitem>

            <listitem>
                <para>
                    <varname>$version</varname>: The <acronym>HTTP</acronym> response version
                    (usually 1.0 or 1.1)
                </para>
            </listitem>

            <listitem>
                <para>
                    <varname>$message</varname>: The <acronym>HTTP</acronym> response message (eg
                    'OK', 'Internal Server Error'). If not specified, the message will be set
                    according to the response code
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.http.response.testers">
        <title>Boolean Tester Methods</title>

        <para>
            Once a <classname>Zend_Http_Response</classname> object is instantiated, it provides
            several methods that can be used to test the type of the response. These all
            return Boolean <constant>TRUE</constant> or <constant>FALSE</constant>:
            <itemizedlist>
                <listitem>
                    <para>
                        <code>Boolean isSuccessful()</code>: Whether the request was successful or
                        not. Returns <constant>TRUE</constant> for <acronym>HTTP</acronym> 1xx and
                        2xx response codes
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>Boolean isError()</code>: Whether the response code implies an error
                        or not. Returns <constant>TRUE</constant> for <acronym>HTTP</acronym> 4xx
                        (client errors) and 5xx (server errors) response codes
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>Boolean isRedirect()</code>: Whether the response is a redirection
                        response or not. Returns <constant>TRUE</constant> for
                        <acronym>HTTP</acronym> 3xx response codes
                    </para>
                </listitem>
            </itemizedlist>

            <example id="zend.http.response.testers.example-1">
                <title>Using the isError() method to validate a response</title>

                <programlisting language="php"><![CDATA[
if ($response->isError()) {
  echo "Error transmitting data.\n"
  echo "Server reply was: " . $response->getStatus() .
       " " . $response->getMessage() . "\n";
}
// .. process the response here...
]]></programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.http.response.acessors">
        <title>Accessor Methods</title>

        <para>
            The main goal of the response object is to provide easy access to
            various response parameters.
            <itemizedlist>
                <listitem>
                    <para>
                        <code>int getStatus()</code>: Get the <acronym>HTTP</acronym> response
                        status code (eg. 200, 504, etc.)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>string getMessage()</code>: Get the <acronym>HTTP</acronym> response
                        status message (eg. "Not Found", "Authorization Required")
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>string getBody()</code>: Get the fully decoded <acronym>HTTP</acronym>
                        response body
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>string getRawBody()</code>: Get the raw, possibly encoded
                        <acronym>HTTP</acronym> response body. if the body was decoded using GZIP
                        encoding for example, it will not be decoded.
                    </para>
                </listitem>

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

                <listitem>
                    <para>
                        <code>string|array getHeader($header)</code>: Get a specific
                        <acronym>HTTP</acronym> response header, specified by $header
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>string getHeadersAsString($status_line = true, $br = "\n")</code>: Get
                        the entire set of headers as a string. If $status_line is
                        <constant>TRUE</constant> (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, "&lt;br /&gt;")
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>string asString($br = "\n")</code>: Get the entire response message as
                        a string. Lines are broken with the $br parameter (Can be, for example,
                        "&lt;br /&gt;"). You can also use the magic method __toString() when casting
                        the object as a string. It will then proxy to asString()
                    </para>
                </listitem>
            </itemizedlist>

            <example id="zend.http.response.acessors.example-1">
                <title>Using Zend_Http_Response Accessor Methods</title>

                <programlisting language="php"><![CDATA[
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();
}
]]></programlisting>
            </example>

            <note>
                <title>Always check return value</title>

                <para>
                    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.
                </para>
            </note>

            <example id="zend.http.response.acessors.example-2">
                <title>Accessing Response Headers</title>

                <programlisting language="php"><![CDATA[
$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;
]]></programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.http.response.static_parsers">
        <title>Static HTTP Response Parsers</title>

        <para>
            The <classname>Zend_Http_Response</classname> class also includes several
            internally-used methods for processing and parsing <acronym>HTTP</acronym> 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.

            <itemizedlist>
                <listitem>
                    <para>
                        <code>int Zend_Http_Response::extractCode($response_str)</code>: Extract
                        and return the <acronym>HTTP</acronym> response code (eg. 200 or 404) from
                        $response_str
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>string Zend_Http_Response::extractMessage($response_str)</code>:
                        Extract and return the <acronym>HTTP</acronym> response message (eg. "OK" or
                        "File Not Found") from $response_str
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>string Zend_Http_Response::extractVersion($response_str)</code>:
                        Extract and return the <acronym>HTTP</acronym> version (eg. 1.1 or 1.0) from
                        $response_str
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>array Zend_Http_Response::extractHeaders($response_str)</code>:
                        Extract and return the <acronym>HTTP</acronym> response headers from
                        $response_str as an array
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>string Zend_Http_Response::extractBody($response_str)</code>: Extract
                        and return the <acronym>HTTP</acronym> response body from $response_str
                    </para>
                </listitem>

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

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

            <itemizedlist>
                <listitem>
                    <para>
                        <code>string Zend_Http_Response::decodeChunkedBody($body)</code>: Decode
                        a complete "Content-Transfer-Encoding: Chunked" body
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>string Zend_Http_Response::decodeGzip($body)</code>: Decode
                        a "Content-Encoding: gzip" body
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>string Zend_Http_Response::decodeDeflate($body)</code>: Decode
                        a "Content-Encoding: deflate" body
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->