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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.http.client">
    <title>導入</title>

    <para>
        <classname>Zend_Http_Client</classname> は、Hyper-Text Transfer Protocol (<acronym>HTTP</acronym>)
        リクエストを簡単に扱うためのインターフェイスを提供します。
        <classname>Zend_Http_Client</classname> は、<acronym>HTTP</acronym> クライアントとしての最低限の機能をサポートしているだけでなく、
        <acronym>HTTP</acronym> 認証やファイルのアップロードといった高度な機能もサポートしています。
        リクエストに成功すると (失敗しても) <classname>Zend_Http_Response</classname>
        オブジェクトを返します。これを使用すると、レスポンスのヘッダや本文にアクセスできます
        (<link linkend="zend.http.response">このセクション</link>を参照して下さい)。
    </para>

    <sect2 id="zend.http.client.usage">
        <title>Zend_Http_Client の使用法</title>

        <para>
            クラスのコンストラクタには、オプションの引数として URL を指定できます
            (文字列か <classname>Zend_Uri_Http</classname> オブジェクトのどちらでも可能です)。
            また、配列あるいは <classname>Zend_Config</classname> オブジェクトで設定オプションを指定することもできます。
            どちらも省略することが可能で、その場合は後から
            setUri() メソッドや setConfig() メソッドで指定します。

            <example id="zend.http.client.introduction.example-1">
                <title>Zend_Http_Client のインスタンスの作成</title>

                <programlisting language="php"><![CDATA[
$client = new Zend_Http_Client('http://example.org', array(
    'maxredirects' => 0,
    'timeout'      => 30));

// これは、上とまったく同じことです
$client = new Zend_Http_Client();
$client->setUri('http://example.org');
$client->setConfig(array(
    'maxredirects' => 0,
    'timeout'      => 30));

// Zend_Config オブジェクトを使ってクライアントの設定を行うこともできます
$config = new Zend_Config_Ini('httpclient.ini', 'secure');
$client->setConfig($config);
]]></programlisting>
            </example>

            <note>
                <para>
                    <classname>Zend_Http_Client</classname> は <classname>Zend_Uri_Http</classname> を用いて URL を検証します。
                    つまり、URL 中にあるパイプ記号 ('|') やキャレット記号 ('^')
                    などの特殊文字はデフォルトでは許可されないということです。
                    これを変更するには、<classname>Zend_Uri</classname> のオプション 'allow_unwise' を
                    '<constant>TRUE</constant>' に設定します。詳細は <link
                        linkend="zend.uri.validation.allowunwise">このセクション</link>
                    を参照ください。
                </para>
            </note>
        </para>
    </sect2>

    <sect2 id="zend.http.client.configuration">
        <title>設定パラメータ</title>

        <para>
            コンストラクタおよび setConfig() メソッドでは、
            設定パラメータの連想配列あるいは <classname>Zend_Config</classname> オブジェクトを受け取ります。
            これらのパラメータは、設定してもしなくてもかまいません。
            すべてのパラメータにはデフォルト値があります。

            <table id="zend.http.client.configuration.table">
                <title>Zend_Http_Client の設定パラメータ</title>

                <tgroup cols="4">
                    <thead>
                        <row>
                            <entry>パラメータ</entry>
                            <entry>説明</entry>
                            <entry>期待する値</entry>
                            <entry>デフォルト値</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry>maxredirects</entry>
                            <entry>リダイレクトをたどる最大数 (0 = たどらない)</entry>
                            <entry>integer</entry>
                            <entry>5</entry>
                        </row>

                        <row>
                            <entry>strict</entry>
                            <entry>
                                ヘッダ名の検証を行うかどうか。
                                <constant>FALSE</constant> に設定すると、検証関数をスキップします。
                                通常はこれを変更してはいけません。
                            </entry>
                            <entry>boolean</entry>
                            <entry><constant>TRUE</constant></entry>
                        </row>

                        <row>
                            <entry>strictredirects</entry>
                            <entry>
                                リダイレクトの際に RFC に厳密に従うかどうか (<link
                                    linkend="zend.http.client.redirections">このセクション</link>を参照ください)
                            </entry>
                            <entry>boolean</entry>
                            <entry><constant>FALSE</constant></entry>
                        </row>

                        <row>
                            <entry>useragent</entry>
                            <entry>ユーザエージェントを表す文字列 (リクエストヘッダに付加されます)</entry>
                            <entry>string</entry>
                            <entry>'Zend_Http_Client'</entry>
                        </row>

                        <row>
                            <entry>timeout</entry>
                            <entry>接続タイムアウト秒数</entry>
                            <entry>integer</entry>
                            <entry>10</entry>
                        </row>

                        <row>
                            <entry>httpversion</entry>
                            <entry><acronym>HTTP</acronym> プロトコルのバージョン (通常は '1.1' あるいは '1.0')</entry>
                            <entry>string</entry>
                            <entry>'1.1'</entry>
                        </row>

                        <row>
                            <entry>adapter</entry>
                            <entry>
                                使用する接続アダプタクラス (<link
                                    linkend="zend.http.client.adapters">このセクション</link>を参照ください)
                            </entry>
                            <entry>mixed</entry>
                            <entry>'Zend_Http_Client_Adapter_Socket'</entry>
                        </row>

                        <row>
                            <entry>keepalive</entry>
                            <entry>
                                 サーバとの keep-alive 接続を有効にするかどうか。
                                 同一サーバに連続してリクエストが発生する場合などに便利で、
                                 性能を向上させるでしょう。
                            </entry>
                            <entry>boolean</entry>
                            <entry><constant>FALSE</constant></entry>
                        </row>

                        <row>
                            <entry>storeresponse</entry>
                            <entry>
                                直近のレスポンスを保存して後から
                                <methodname>getLastResponse()</methodname> で取得できるようにするかどうか。
                                <constant>FALSE</constant> の場合、
                                <methodname>getLastResponse()</methodname> は <constant>NULL</constant> を返します。
                            </entry>
                            <entry>boolean</entry>
                            <entry><constant>TRUE</constant></entry>
                        </row>

                        <row>
                            <entry>encodecookies</entry>
                            <entry>
                                クッキー値を urlencode/urldecode を介して渡すべきかどうか。
                                これを有効にすると、一部の Web サーバーでサポートを壊します。
                                これを無効にすると、クッキーが含むことができる値の範囲を制限します。
                            </entry>
                            <entry>boolean</entry>
                            <entry><constant>TRUE</constant></entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </para>
    </sect2>

    <sect2 id="zend.http.client.basic-requests">
        <title>基本的な HTTP リクエストの処理</title>

        <para>
            シンプルな <acronym>HTTP</acronym> リクエストを実行するのは非常に簡単で、単に
            request() メソッドを実行するだけです。たったの三行ですんでしまいます。

            <example id="zend.http.client.basic-requests.example-1">
                <title>シンプルな GET リクエストの処理</title>

                <programlisting language="php"><![CDATA[
$client = new Zend_Http_Client('http://example.org');
$response = $client->request();
]]></programlisting>
            </example>

            request() メソッドには、オプションでパラメータを指定できます。
            このパラメータはリクエストメソッドで、<acronym>HTTP</acronym> プロトコルで定義されている
            <property>GET</property>、<property>POST</property>、<property>PUT</property>、
            <property>HEAD</property>、<property>DELETE</property>、<property>TRACE</property>、
            <property>OPTIONS</property> そして <property>CONNECT</property>
            のいずれかを指定可能です。

            <footnote>
              <para>
                RFC 2616 - <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html" /> を参照ください。
              </para>
            </footnote>

            利便性を高めるため、これらはすべてクラス定数として定義されています。たとえば
            Zend_Http_Client::GET、Zend_Http_Client::POST などのようになっています。
        </para>

        <para>
            メソッドを指定しない場合は、直近の <methodname>setMethod()</methodname> コールで指定されたメソッドを使用します。
            <methodname>setMethod()</methodname> もコールされていない場合は、デフォルトのリクエストメソッドとして
            <property>GET</property> を使用します (上の例を参照ください)。

            <example id="zend.http.client.basic-requests.example-2">
                <title>GET 以外のリクエストメソッドの使用</title>

                <programlisting language="php"><![CDATA[
// POST リクエストを実行します
$response = $client->request('POST');

// POST リクエストを実行するためのもうひとつの方法です
$client->setMethod(Zend_Http_Client::POST);
$response = $client->request();
]]></programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.http.client.parameters">
        <title>GET や POST へのパラメータの追加</title>

        <para>
            <property>GET</property> パラメータを <acronym>HTTP</acronym> リクエストに追加するのは簡単です。
            URL の一部として指定するか、あるいは setParameterGet() メソッドを使用します。
            このメソッドは、<property>GET</property> パラメータの名前を最初の引数、そして
            <property>GET</property> パラメータの値を二番目の引数として受け取ります。
            さらに便利に使用するため、setParameterGet()
            メソッドでは name => value 形式の連想配列で <property>GET</property> 変数を指定することもできます。
            これは、複数の <property>GET</property> パラメータを指定する必要がある場合に便利です。

            <example id="zend.http.client.parameters.example-1">
                <title>GET パラメータの設定</title>

                <programlisting language="php"><![CDATA[
// setParameterGet メソッドで GET パラメータを指定します
$client->setParameterGet('knight', 'lancelot');

// このような URL を指定するのと同じことです
$client->setUri('http://example.com/index.php?knight=lancelot');

// 複数のパラメータを一度に追加します
$client->setParameterGet(array(
    'first_name'  => 'Bender',
    'middle_name' => 'Bending'
    'made_in'     => 'Mexico',
));
]]></programlisting>
            </example>
        </para>

        <para>
            <property>GET</property> パラメータはあらゆるリクエストメソッドで送信できますが、
            POST パラメータは POST リクエストの本文としてしか送信できません。
            POST パラメータをリクエストに追加する方法は、<property>GET</property>
            パラメータを追加する場合と非常に似ています。
            使用するのは setParameterPost() メソッドで、このメソッドの使用法は
            setParameterGet() メソッドと同じです。

            <example id="zend.http.client.parameters.example-2">
                <title>POST パラメータの設定</title>

                <programlisting language="php"><![CDATA[
// POST パラメータを設定します
$client->setParameterPost('language', 'fr');

// 複数の POST パラメータを設定します。そのうちのひとつは複数の値を持ちます。
$client->setParameterPost(array(
    'language'  => 'es',
    'country'   => 'ar',
    'selection' => array(45, 32, 80)
));
]]></programlisting>
            </example>

            POST リクエストを送信する際には、<property>GET</property> パラメータと POST
            パラメータの両方を設定できることに注意しましょう。
            一方、POST パラメータを POST 以外のリクエストで指定しても何のエラーも発生しませんが、
            これは無意味です。POST 以外のリクエストでは、
            POST パラメータを指定しても無視されます。
        </para>
    </sect2>

    <sect2 id="zend.http.client.accessing_last">
        <title>直近のリクエストやレスポンスへのアクセス</title>

        <para>
            <classname>Zend_Http_Client</classname> では、そのクライアントオブジェクトが
            直近に送信したリクエストおよび
            直近に受信したレスポンスにアクセスするためのメソッドを提供しています。
            <classname>Zend_Http_Client->getLastRequest()</classname>
            は何もパラメータを受け取らず、クライアントが直近に送信した
            <acronym>HTTP</acronym> リクエストを文字列で返します。同様に
            <classname>Zend_Http_Client->getLastResponse()</classname> は、
            クライアントが直近に受信した <acronym>HTTP</acronym> レスポンスを
            <link linkend="zend.http.response">Zend_Http_Response</link>
            オブジェクトで返します。
        </para>
    </sect2>

</sect1>

<!--
vim:se ts=4 sw=4 et:
-->