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

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

    <sect2 id="zend.http.response.introduction">
        <title>導入</title>
        <para>
            <classname>Zend_Http_Response</classname> は、<acronym>HTTP</acronym> レスポンスに簡単にアクセスできるようにします。
            また、<acronym>HTTP</acronym> レスポンスメッセージをパースするための静的メソッド群も提供します。
            通常は、<classname>Zend_Http_Response</classname> は <classname>Zend_Http_Client</classname>
            リクエストの返す結果として使用します。
        </para>
        <para>
            ほとんどの場合は、Zend_Http_Response オブジェクトのインスタンスを作成するには
            factory() メソッドを使用します。これは、<acronym>HTTP</acronym>
            レスポンスメッセージを含む文字列を受け取って新しい
            Zend_Http_Response オブジェクトを返します。
            <example id="zend.http.response.introduction.example-1">
                <title>ファクトリメソッドを使用した Zend_Http_Response オブジェクトの作成</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::factory($str);
]]></programlisting>
            </example>
        </para>
        <para>
            コンストラクタを使用して新しいオブジェクトを作成することもできます。
            その際には、レスポンスの全パラメータを指定します。
        </para>
        <para>
            <code>
                public function __construct($code, $headers, $body = null, $version = '1.1', $message = null)
            </code>
        </para>
        <itemizedlist>
            <listitem>
                <para>
                    <varname>$code</varname>: <acronym>HTTP</acronym> レスポンスコード (たとえば 200 や 404 など)。
                </para>
            </listitem>
            <listitem>
                <para>
                    <varname>$headers</varname>: <acronym>HTTP</acronym> レスポンスヘッダの連想配列 (たとえば 'Host' => 'example.com' など)。
                </para>
            </listitem>
            <listitem>
                <para>
                    <varname>$body</varname>: レスポンス本文の文字列。
                </para>
            </listitem>
            <listitem>
                <para>
                    <varname>$version</varname>: <acronym>HTTP</acronym> レスポンスのバージョン (通常は 1.0 あるいは 1.1)。
                </para>
            </listitem>
            <listitem>
                <para>
                    <varname>$message</varname>: <acronym>HTTP</acronym> レスポンスメッセージ (たとえば 'OK' や 'Internal Server Error' など)。
                    指定しなかった場合は、レスポンスコードに応じたメッセージが設定されます。
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
    <sect2 id="zend.http.response.testers">
        <title>真偽チェック用のメソッド</title>
        <para>
            <classname>Zend_Http_Response</classname> のインスタンスを取得すると、
            レスポンスの種類を調べるためのメソッドが使用できるようになります。
            これらのメソッドは、すべて true あるいは false を返します。
            <itemizedlist>
                <listitem>
                    <para>
                        <code>Boolean isSuccessful()</code>: リクエストが成功したかどうかを調べます。
                        <acronym>HTTP</acronym> レスポンスコードが 1xx か 2xx であった場合に TRUE を返します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>Boolean isError()</code>: レスポンスコードがエラーを意味しているかどうかを調べます。
                        <acronym>HTTP</acronym> レスポンスコードが 4xx (クライアントのエラー) あるいは
                        5xx (サーバのエラー) であった場合に TRUE を返します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>Boolean isRedirect()</code>: レスポンスがリダイレクトされているかどうかを調べます。
                        <acronym>HTTP</acronym> レスポンスコードが 3xx であった場合に TRUE を返します。
                    </para>
                </listitem>
            </itemizedlist>
            <example id="zend.http.response.testers.example-1">
                <title>isError() メソッドの使用によるレスポンスの検証</title>
                <programlisting language="php"><![CDATA[
if ($response->isError()) {
  echo "データ転送エラー。\n"
  echo "サーバからの応答: " . $response->getStatus() .
       " " . $response->getMessage() . "\n";
}
// .. ここでレスポンスを処理します...
]]></programlisting>
            </example>
        </para>
    </sect2>
    <sect2 id="zend.http.response.acessors">
        <title>アクセス用メソッド群</title>
        <para>
            レスポンスオブジェクトの本来の目的は、レスポンスパラメータに簡単にアクセスすることです。
            <itemizedlist>
                <listitem>
                    <para>
                        <code>int getStatus()</code>: <acronym>HTTP</acronym> レスポンスステータスコード
                        (たとえば 200 や 504 など) を取得します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>string getMessage()</code>: <acronym>HTTP</acronym> レスポンスステータスのメッセージ
                        (たとえば "Not Found" や "Authorization Required" など) を取得します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>string getBody()</code>: <acronym>HTTP</acronym> レスポンス本文をデコードしたものを取得します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>string getRawBody()</code>: そのままの状態の、おそらくエンコードされている
                        <acronym>HTTP</acronym> レスポンス本文を取得します。たとえば GZIP などでエンコードされていたとしても、
                        それはデコードされません。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>array getHeaders()</code>: <acronym>HTTP</acronym> レスポンスヘッダを、連想配列形式
                        (たとえば 'Content-type' => 'text/html' など) で取得します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>string|array getHeader($header)</code>: $header で指定した、
                        特定の <acronym>HTTP</acronym> レスポンスヘッダを取得します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>string getHeadersAsString($status_line = true, $br = "\n")</code>:
                        ヘッダ全体を文字列として取得します。$status_line が true の場合 (デフォルト) は、
                        最初のステータス行 (たとえば "HTTP/1.1 200 OK" など) も返されます。
                        改行は $br パラメータで指定します (たとえば "&lt;br /&gt;" などにもできます)。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>string asString($br = "\n")</code>: レスポンスメッセージ全体を文字列として取得します。
                        改行は $br パラメータで指定します (たとえば "&lt;br /&gt;" などにもできます)。
                        マジックメソッド __toString()
                        を使ってオブジェクトを文字列にキャストすることができます。
                        これは asString() へのプロキシとなります。
                    </para>
                </listitem>
            </itemizedlist>
            <example id="zend.http.response.acessors.example-1">
                <title>Zend_Http_Response へのアクセス用メソッドの使用</title>
                <programlisting language="php"><![CDATA[
if ($response->getStatus() == 200) {
  echo "リクエストの結果は次のようになりました。<br />";
  echo $response->getBody();
} else {
  echo "データの取得時にエラーが発生しました。<br />";
  echo $response->getStatus() . ": " . $response->getMessage();
}
]]></programlisting>
            </example>
            <note>
                <title>常に返り値をチェックする</title>
                <para>
                    レスポンスには同じヘッダを複数含めることができるので、
                    getHeader() メソッドや getHeaders() メソッドの返す結果は
                    文字列の場合もあれば文字列の配列となる場合もあります。
                    返された値が文字列なのか配列なのかを常にチェックするようにしましょう。
                </para>
            </note>
            <example id="zend.http.response.acessors.example-2">
                <title>レスポンスヘッダへのアクセス</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>静的 HTTP レスポンスパーサ</title>
        <para>
            <classname>Zend_Http_Response</classname> クラスには、内部で使用するメソッドもいくつか含まれています。
            これは、<acronym>HTTP</acronym> レスポンスメッセージを処理したりパースしたりするためのものです。
            これらのメソッドは静的メソッドとして公開されています。
            つまり外部からでも使用できるということです。特にインスタンスを作成しなくても、
            レスポンスの一部を抽出したりなどといった目的で使用可能です。
            <itemizedlist>
                <listitem>
                    <para>
                        <code>int Zend_Http_Response::extractCode($response_str)</code>:
                        <acronym>HTTP</acronym> レスポンスコード (たとえば 200 や 404 など)
                        を $response_str から抽出し、それを返します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>string Zend_Http_Response::extractMessage($response_str)</code>:
                        <acronym>HTTP</acronym> レスポンスメッセージ (たとえば "OK" や "File Not Found" など)
                        を $response_str から抽出し、それを返します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>string Zend_Http_Response::extractVersion($response_str)</code>:
                        <acronym>HTTP</acronym> バージョン (たとえば 1.1 や 1.0 など)
                        を $response_str から抽出し、それを返します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>array Zend_Http_Response::extractHeaders($response_str)</code>:
                        <acronym>HTTP</acronym> レスポンスヘッダを $response_str から抽出し、それを配列で返します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>string Zend_Http_Response::extractBody($response_str)</code>:
                        <acronym>HTTP</acronym> レスポンス本文を $response_str から抽出し、それを返します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>string Zend_Http_Response::responseCodeAsText($code = null, $http11 = true)</code>:
                        レスポンスコード $code に対応する、標準的な <acronym>HTTP</acronym> レスポンスメッセージを取得します。
                        たとえば $code が 500 の場合は "Internal Server Error" を返します。
                        $http11 が true の場合 (デフォルト) は <acronym>HTTP</acronym>/1.1 のメッセージを、
                        そうでない場合は <acronym>HTTP</acronym>/1.0 のメッセージを返します。
                        $code を省略した場合は、このメソッドは、すべての既知の <acronym>HTTP</acronym>
                        レスポンスコードを連想配列 (code => message) で返します。
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            パーサメソッド以外にも、このクラスには
            一般的な <acronym>HTTP</acronym> レスポンスエンコーディングに対応したデコーダが含まれています。
            <itemizedlist>
                <listitem>
                    <para>
                        <code>string Zend_Http_Response::decodeChunkedBody($body)</code>:
                        "Content-Transfer-Encoding: Chunked" の本文をデコードします。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>string Zend_Http_Response::decodeGzip($body)</code>:
                        "Content-Encoding: gzip" の本文をデコードします。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>string Zend_Http_Response::decodeDeflate($body)</code>:
                        "Content-Encoding: deflate" の本文をデコードします。
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->