repo_zf1/documentation/manual/ja/module_specs/Zend_Http_Cookie-Handling.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24856 -->
<sect1 id="zend.http.cookies">
    <title>Zend_Http_Cookie および Zend_Http_CookieJar</title>

    <sect2 id="zend.http.cookies.introduction">
        <title>導入</title>
        <para>
            <classname>Zend_Http_Cookie</classname> は、お察しのとおり、<acronym>HTTP</acronym> クッキーを表すクラスです。
            <acronym>HTTP</acronym> レスポンス文字列をパースしたりクッキーを収集したり、
            そしてプロパティに簡単にアクセスしたりするためのメソッドがあります。
            また、クッキーが所定の条件にマッチしているかどうかを調べることもできます。
            たとえばリクエスト <acronym>URL</acronym>、有効期限、セキュア接続か否かなどを調べます。
        </para>
        <para>
            <classname>Zend_Http_CookieJar</classname> は主に <classname>Zend_Http_Client</classname> で用いられ、ひとつあるいは複数の
            <classname>Zend_Http_Cookie</classname> オブジェクトを保持します。
            <classname>Zend_Http_CookieJar</classname> オブジェクトを <classname>Zend_Http_Client</classname>
            オブジェクトにアタッチすると、
            クライアントから <acronym>HTTP</acronym> リクエストで送られるクッキーや
            クライアントが <acronym>HTTP</acronym> レスポンスで受け取るクッキーがすべて
            CookieJar オブジェクトに保存されます。そして、
            クライアントが別のリクエストを送信する際には、まず CookieJar
            オブジェクトを調べてリクエストにマッチするクッキーがあるかどうかを確認します。
            あった場合は、それが自動的にリクエストヘッダに追加されます。
            これは、連続した <acronym>HTTP</acronym> リクエストでユーザのセッションを保持し続けたい場合に便利です。
            セッション ID が保存されたクッキーを、必要に応じて自動的に送信することができます。
            さらに、必要に応じて <classname>Zend_Http_CookieJar</classname> オブジェクトをシリアライズし、
            $_SESSION に格納することもできます。
        </para>
    </sect2>

    <sect2 id="zend.http.cookies.cookie.instantiating">
        <title>Zend_Http_Cookie のインスタンスの作成</title>
        <para>
            クッキーオブジェクトのインスタンスを作成する方法は二通りあります。
            <itemizedlist>
                <listitem>
                    <para>
                    コンストラクタで以下のような構文を使用します。
                    <command>new <classname>Zend_Http_Cookie</classname>(string $name, string $value, string $domain, [int $expires, [string $path, [boolean $secure]]]);</command>
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                            <code>$name</code>: クッキーの名前 (例 'PHPSESSID') (必須)
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$value</code>: クッキーの値 (必須)
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$domain</code>: クッキーのドメイン (例 '.example.com') (必須)
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$expires</code>: クッキーの有効期限を表す UNIX タイムスタンプ (任意。既定値は <constant>NULL</constant>)。
                            設定しなかった場合は、有効期限なしの 'セッションクッキー' として扱われます。
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$path</code>: クッキーのパス。たとえば '/foo/bar/' (任意。既定値は '/')
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$secure</code>: クッキーの送信をセキュア接続 (<acronym>HTTPS</acronym>)
                            時に限るかどうか (任意。既定値は <constant>FALSE</constant>)
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
                <listitem>
                    <para>
                    静的メソッド fromString($cookieStr, [$refUri, [$encodeValue]]) をコールし、<acronym>HTTP</acronym> レスポンスヘッダ 'Set-Cookie'
                    あるいは <acronym>HTTP</acronym> リクエストヘッダ 'Cookie' に対応するクッキー文字列を指定します。
                    この場合、クッキーの値は事前にエンコードしておく必要があります。
                    クッキー文字列に 'domain' 部分が含まれない場合は、
                    クッキーのドメインとパスを設定するための参照 <acronym>URI</acronym> を指定する必要があります。
                    </para>
                    <para>
                        <methodname>fromString()</methodname> メソッドでは下記のパラメータを受け付けます。
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                            <varname>$cookieStr</varname>:
                           'Set-Cookie' <acronym>HTTP</acronym> レスポンス・ヘッダや、必須の
                           'Cookie' <acronym>HTTP</acronym> リクエスト・ヘッダで表現されるようなクッキー文字列。
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <varname>$refUri</varname>:
                            クッキーのドメインとパスがセットされる参照 <acronym>URI</acronym>。
                            (任意。既定値では $cookieStr から値をパースします)
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <varname>$encodeValue</varname>:
                            値が urldecode を介して渡されるべきかどうか。
                            クッキー文字列に変換される際に、クッキーのふるまいにも影響します。
                            (任意。既定値は true)
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </itemizedlist>
            <example id="zend.http.cookies.cookie.instantiating.example-1">
               <title>Zend_Http_Cookie のインスタンスの作成</title>
               <programlisting language="php"><![CDATA[
// まずはコンストラクタを使用します。このクッキーの有効期限は二時間です。
$cookie = new Zend_Http_Cookie('foo',
                               'bar',
                               '.example.com',
                               time() + 7200,
                               '/path');

// HTTP レスポンスヘッダ Set-Cookie を設定して使用することもできます。
// このクッキーは先ほどのものとほとんど同じですが、有効期限はありません。
// また、セキュア接続時にのみ送信されます。
$cookie = Zend_Http_Cookie::fromString('foo=bar; domain=.example.com; ' .
                                       'path=/path; secure');

// クッキーのドメインが設定されていない場合は、手動で設定する必要があります。
$cookie = Zend_Http_Cookie::fromString('foo=bar; secure;',
                                       'http://www.example.com/path');
]]></programlisting>
            </example>
            <note>
                <para>
                クッキーオブジェクトを作成するのに <classname>Zend_Http_Cookie</classname>::fromString()
                メソッドを使用した場合は、クッキーの値は <acronym>URL</acronym> エンコードされていなければなりません。
                これはクッキー文字列と同様です。しかし、コンストラクタを使用する場合は、
                エンコードされたものではなく、デコードされた実際の値を使用します。
                </para>
            </note>
        </para>
        <para>
            クッキーオブジェクトを文字列に変換するには、マジックメソッド __toString()
            を使用します。このメソッドは、<acronym>HTTP</acronym> リクエストヘッダ "Cookie" 用の文字列を作成します。
            クッキーの名前と値が表示され、最後はセミコロン (';') となります。
            この値は <acronym>URL</acronym> エンコードされ、そのまま Cookie ヘッダとして使用できるようになります。
            <example id="zend.http.cookies.cookie.instantiating.example-2">
               <title>Zend_Http_Cookie オブジェクトの文字列化</title>
               <programlisting language="php"><![CDATA[
// 新しいクッキーを作成します。
$cookie = new Zend_Http_Cookie('foo',
                               'two words',
                               '.example.com',
                               time() + 7200,
                               '/path');

// これは 'foo=two+words;' を表示します。
echo $cookie->__toString();

// 上と同じことです。
echo (string) $cookie;

// PHP 5.2 以降では、これでもかまいません。
echo $cookie;
]]></programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.http.cookies.cookie.accessors">
        <title>Zend_Http_Cookie のゲッターメソッド</title>
        <para>
            <classname>Zend_Http_Cookie</classname> のインスタンスを作成すると、
            <acronym>HTTP</acronym> クッキーのさまざまなプロパティを取得するためのメソッドが使用できるようになります。
            <itemizedlist>
                <listitem>
                    <para>
                    <methodname>getName()</methodname>: クッキーの名前を取得します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <methodname>getValue()</methodname>: デコードされたクッキーの値を取得します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <methodname>getDomain()</methodname>: クッキーのドメインを取得します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <methodname>getPath()</methodname>: クッキーのパスを取得します。既定値は '/' です。
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <methodname>getExpiryTime()</methodname>: クッキーの有効期限を UNIX タイムスタンプで取得します。
                    設定されていない場合は <constant>NULL</constant> を返します。
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            さらに、チェック用のメソッドも提供されています。
            <itemizedlist>
                <listitem>
                    <para>
                    <methodname>isSecure()</methodname>: クッキーの送信がセキュア接続に限定されているかどうかを調べます。
                    要するに、もし <constant>TRUE</constant> ならそのクッキーは <acronym>HTTPS</acronym> でしか送信されないということです。
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <methodname>isExpired(int $time = null)</methodname>: クッキーが有効期限切れになっているかどうかを調べます。
                    有効期限が設定されていない場合は、常に <constant>TRUE</constant> を返します。$time を指定すると、
                    その時刻の時点で有効期限切れになるのかどうかを調べます。
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <methodname>isSessionCookie()</methodname>: クッキーが "セッションクッキー"、
                    すなわち有効期限を持たないクッキー (セッション終了時に無効になるクッキー)
                    であるかどうかを調べます。
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            <example id="zend.http.cookies.cookie.accessors.example-1">
                <title>Zend_Http_Cookie のゲッターメソッドの使用法</title>
                <programlisting language="php"><![CDATA[
// まずクッキーを作成します
$cookie =
    Zend_Http_Cookie::fromString('foo=two+words; ' +
                                 'domain=.example.com; ' +
                                 'path=/somedir; ' +
                                 'secure; ' +
                                 'expires=Wednesday, 28-Feb-05 20:41:22 UTC');

echo $cookie->getName();   // これは 'foo' を表示します
echo $cookie->getValue();  // これは 'two words' を表示します
echo $cookie->getDomain(); // これは '.example.com' を表示します
echo $cookie->getPath();   // これは '/' を表示します

echo date('Y-m-d', $cookie->getExpiryTime());
// これは '2005-02-28' を表示します

echo ($cookie->isExpired() ? 'Yes' : 'No');
// これは 'Yes' を表示します

echo ($cookie->isExpired(strtotime('2005-01-01') ? 'Yes' : 'No');
// これは 'No' を表示します

echo ($cookie->isSessionCookie() ? 'Yes' : 'No');
// これは 'No' を表示します
]]></programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.http.cookies.cookie.matching">
        <title>Zend_Http_Cookie が条件に一致するものかどうかを調べる</title>
        <para>
            調べるために <classname>Zend_Http_Cookie</classname> に含まれているのは match() メソッドだけです。
            このメソッドを使用して、送ろうとしている <acronym>HTTP</acronym> リクエストに当てはまるクッキーであるかどうかを調べます。
            その結果によって、クッキーをこのリクエストで送信するかどうかが決まります。
            メソッドの構文やパラメータの内容は以下のとおりです。
            <command>Zend_Http_Cookie->match(mixed $uri, [boolean $matchSessionCookies, [int $now]]);</command>
            <itemizedlist>
                <listitem>
                    <para>
                    <varname>$uri</varname>: <classname>Zend_Uri_Http</classname> オブジェクトで、
                    ドメインやパスのチェックに使用します。オプションとして、
                    正しい形式の <acronym>URL</acronym> を文字列で渡すこともできます。
                    指定した <acronym>URL</acronym> のスキーム (<acronym>HTTP</acronym> あるいは <acronym>HTTPS</acronym>)、
                    ドメインおよびパスがすべて一致した場合にのみ、クッキーがマッチします。
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <varname>$matchSessionCookies</varname>:
                    セッションクッキーをマッチの対象にするかどうか。
                    既定値は <constant>TRUE</constant> です。<constant>FALSE</constant> に設定すると、
                    有効期限の設定されていないクッキーはマッチしません。
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <varname>$now</varname>: クッキーの有効期限をチェックする基準となる時刻
                    (UNIX タイムスタンプ形式)。指定しない場合の既定値は、現在時刻です。
                    </para>
                </listitem>
            </itemizedlist>
            <example id="zend.http.cookies.cookie.matching.example-1">
                <title>クッキーがマッチするかどうかの確認</title>
                <programlisting language="php"><![CDATA[
// まずクッキーオブジェクトを作成します。これはセキュアなセッションクッキーです。
$cookie = Zend_Http_Cookie::fromString('foo=two+words; ' +
                                       'domain=.example.com; ' +
                                       'path=/somedir; ' +
                                       'secure;');

$cookie->match('https://www.example.com/somedir/foo.php');
// これは true を返します。

$cookie->match('http://www.example.com/somedir/foo.php');
// これは false を返します。接続がセキュアでないからです。

$cookie->match('https://otherexample.com/somedir/foo.php');
// これは false を返します。ドメインが違っているからです。

$cookie->match('https://example.com/foo.php');
// これは false を返します。パスが違っているからです。

$cookie->match('https://www.example.com/somedir/foo.php', false);
// これは false を返します。セッションクッキーはマッチさせないようにしているからです。

$cookie->match('https://sub.domain.example.com/somedir/otherdir/foo.php');
// これは true を返します。

// 別のクッキーオブジェクトを作成します。今度はセキュアではなく、
// 二時間で有効期限切れとなります。
$cookie = Zend_Http_Cookie::fromString('foo=two+words; ' +
                                       'domain=www.example.com; ' +
                                       'expires='
                                       . date(DATE_COOKIE, time() + 7200));

$cookie->match('http://www.example.com/');
// これは true を返します。

$cookie->match('https://www.example.com/');
// これは true を返します。セキュアでないクッキーは、
// セキュアな通信でも送信されます!

$cookie->match('http://subdomain.example.com/');
// これは false を返します。ドメインが違っているからです。

$cookie->match('http://www.example.com/', true, time() + (3 * 3600));
// これは false を返します。今から三時間後の時刻を指定したからです。
]]></programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.http.cookies.cookiejar">
        <title>Zend_Http_CookieJar のインスタンスの作成</title>
        <para>
            <classname>Zend_Http_CookieJar</classname> のインスタンスを直接作成する必要は、まずありません。
            新しいクッキージャーを <classname>Zend_Http_Client</classname> オブジェクトにアタッチするには、単に
            Zend_Http_Client->setCookieJar() メソッドをコールすればいいのです。これで、
            新しい空のクッキージャーがクライアントに追加されます。このクッキージャーを取得するには
            Zend_Http_Client->getCookieJar() を使用します。
        </para>
        <para>
            それでもやっぱり自分で CookieJar のインスタンスを作成したいというのなら、
            "new Zend_Http_CookieJar()" と直接コールしてください。
            コンストラクタには引数を何も指定しません。インスタンスを作成するもうひとつの方法としては、
            静的メソッド Zend_Http_CookieJar::fromResponse() を使用するものがあります。
            このメソッドは二つのパラメータを受け取ります。まず最初が <classname>Zend_Http_Response</classname>
            オブジェクト、そして二つ目は参照先 <acronym>URI</acronym> で、これは文字列あるいは
            <classname>Zend_Uri_Http</classname> オブジェクトのいずれかです。
            このメソッドは新しい <classname>Zend_Http_CookieJar</classname> オブジェクトを返します。
            このオブジェクトには、指定した <acronym>HTTP</acronym> レスポンスによって設定されたクッキーが既に含まれています。
            クッキーのドメインとパスが Set-Cookie ヘッダで指定されていない場合は、
            参照先 <acronym>URI</acronym> を使用して設定します。
        </para>
    </sect2>

    <sect2 id="zend.http.cookies.cookiejar.adding_cookies">
        <title>Zend_Http_CookieJar オブジェクトへのクッキーの追加</title>
        <para>
            通常は、CookieJar オブジェクトを追加した <classname>Zend_Http_Client</classname> オブジェクトが自動的に処理を行い、
            <acronym>HTTP</acronym> レスポンスで設定されたクッキーをジャーに追加してくれます。
            自分でクッキーをジャーに追加するには、二通りの方法があります。
            <itemizedlist>
                <listitem>
                    <para>
                    <classname>Zend_Http_CookieJar->addCookie($cookie[, $ref_uri])</classname>:
                    単一のクッキーをジャーに追加します。$cookie には <classname>Zend_Http_Cookie</classname>
                    オブジェクトあるいは文字列を指定します。文字列は自動的に
                    Cookie オブジェクトに変換されます。文字列を指定する場合は、同時に
                    $ref_uri も指定しなければなりません。これは参照先 <acronym>URI</acronym> で、文字列あるいは
                    <classname>Zend_Uri_Http</classname> オブジェクトを渡します。これをもとにして、
                    クッキーのデフォルトのドメインとパスを決定します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <classname>Zend_Http_CookieJar->addCookiesFromResponse($response, $ref_uri)</classname>:
                    <acronym>HTTP</acronym> レスポンス内のすべてのクッキーをジャーに追加します。
                    $response は Set-Cookie ヘッダつきの <classname>Zend_Http_Response</classname> オブジェクトです。
                    $ref_uri は参照先 <acronym>URI</acronym> で、文字列あるいは <classname>Zend_Uri_Http</classname> オブジェクトとなります。
                    これをもとにして、クッキーのデフォルトのドメインとパスを決定します。
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>

    <sect2 id="zend.http.cookies.cookiejar.getting_cookies">
        <title>Zend_Http_CookieJar オブジェクトからのクッキーの取得</title>
        <para>
            クッキーを追加する場合と同様、クッキーをジャーから取得する作業についても
            通常は手動で行う必要はありません。<classname>Zend_Http_Client</classname>
            オブジェクトは、その <acronym>HTTP</acronym> リクエストで必要なクッキーを自動的に取得します。
            とは言え、ジャーから手動でクッキーを取得するための方法も提供されています。
            <methodname>getCookie()</methodname>、
            <methodname>getAllCookies()</methodname> および <methodname>getMatchingCookies()</methodname>
            の三通りの方法です。
            さらに、CookieJar を順次処理していくことで、そこからすべての
            <classname>Zend_Http_Cookie</classname> オブジェクトを取得することができます。
        </para>
        <para>
            注意すべき点は、これらのメソッドが特別なパラメータを受け取るようになっているということです。
            このパラメータで、メソッドの返り値の型を指定します。
            指定できる値は次の三種類です。
            <itemizedlist>
                <listitem>
                    <para>
                    <constant>Zend_Http_CookieJar::COOKIE_OBJECT</constant>:
                    <classname>Zend_Http_Cookie</classname> オブジェクトを返します。
                    返されるクッキーが複数の場合は、オブジェクトの配列を返します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <constant>Zend_Http_CookieJar::COOKIE_STRING_ARRAY</constant>:
                    "foo=bar" 形式の文字列を返します。これは、<acronym>HTTP</acronym> リクエストの "Cookie"
                    ヘッダで使用できる形式です。
                    返されるクッキーが複数の場合は、文字列の配列を返します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <constant>Zend_Http_CookieJar::COOKIE_STRING_CONCAT</constant>:
                    COOKIE_STRING_ARRAY と似ていますが、返されるクッキーが複数の場合には
                    それらをひとつの長い文字列に連結して返します。
                    区切り文字はセミコロン (;) となります。
                    これは、マッチするすべてのクッキーを単一の <acronym>HTTP</acronym> リクエストヘッダ
                    "Cookie" で送信したい場合に非常に便利です。
                    </para>
                </listitem>

                <!-- TODO : to be translated -->
                <listitem>
                    <para>
                        <constant>Zend_Http_CookieJar::COOKIE_STRING_CONCAT_STRICT</constant>: Similar to
                        COOKIE_STRING_CONCAT, but follows a strict implementation of RFC6265.  In this mode,
                        a single space character always follows the semicolon separator between cookies, and 
                        the semicolon separator is stripped from the end of the cookie string.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            クッキー取得のためのさまざまなメソッドのについて説明します。
            <itemizedlist>
                <listitem>
                    <para>
                    <classname>Zend_Http_CookieJar->getCookie($uri, $cookie_name[, $ret_as])</classname>:
                    その <acronym>URI</acronym> (ドメインおよびパス) と名前にもとづいて、
                    ジャーから単一のクッキーを取得します。
                    $uri は文字列か <classname>Zend_Uri_Http</classname> オブジェクトで、<acronym>URI</acronym> を表します。
                    $cookie_name はクッキー名を表す文字列です。
                    $ret_as は先ほど説明したように返り値の型を指定します。
                    $ret_type はオプションで、既定値は COOKIE_OBJECT です。
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <classname>Zend_Http_CookieJar->getAllCookies($ret_as)</classname>:
                    ジャーからすべてのクッキーを取得します。
                    $ret_as は先ほど説明したように返り値の型を指定します。
                    指定しなかった場合の $ret_type の既定値は、COOKIE_OBJECT となります。
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <classname>Zend_Http_CookieJar->getMatchingCookies($uri[, $matchSessionCookies[, $ret_as[, $now]]])</classname>:
                    指定した条件を満たす全てのクッキーをジャーから取得します。
                    条件として指定するのは、<acronym>URI</acronym> および有効期限です。
                    <itemizedlist>
                        <listitem>
                            <para>
                            <code>$uri</code> は <classname>Zend_Uri_Http</classname> オブジェクトあるいは文字列です。
                            接続形式 (セキュアかそうでないか)、ドメインおよびパスの条件を指定します。
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$matchSessionCookies</code> は boolean 値で、
                            セッションクッキーを含めるかどうかを指定します。
                            セッションクッキーとは、有効期限が指定されていないクッキーのことです。
                            既定値は <constant>TRUE</constant> です。
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$ret_as</code>
                            は、先ほど説明したように返り値の型を指定します。
                            指定しなかった場合の既定値は COOKIE_OBJECT です。
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$now</code> は整数値で表した UNIX タイムスタンプで、
                            これを "現在時刻" として扱います。
                            有効期限がこの時刻より前に設定されているクッキーはマッチしません。
                            指定しなかった場合の既定値は、現在時刻です。
                            </para>
                        </listitem>
                    </itemizedlist>
                    クッキーのマッチ方法についての詳細は
                    <link linkend="zend.http.cookies.cookie.matching">このセクション</link>
                    を参照してください。
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->