CGI::Cookieモジュール

by Hippo2000(2000/8/9,2001/5/14,2002/7/14)

CGI::Cookieモジュールなのです。

原本の著作権はLincoln D. Stein.氏がお持ちです。詳しくは著作権情報をご覧ください。

内容等が間違っていたら修正します。ご連絡ください。

(2002/7/14)　みのむしさんからの指摘を受けて2ヶ所、誤字を訂正しました。

(2001/5/14) ゴン太さんからの指摘を受けて1ヶ所、誤字を訂正しました。

名前

CGI::Cookie - Netscape クッキーへのインターフェース

概要

    use CGI qw/:standard/;
    use CGI::Cookie;

    # 新しいクッキーを作成し、それを送信します
    $cookie1 = new CGI::Cookie(-name=>'ID',-value=>123456);
    $cookie2 = new CGI::Cookie(-name=>'preferences',
                               -value=>{ font => Helvetica,
                                         size => 12 } 
                               );
    print header(-cookie=>[$cookie1,$cookie2]);

    # 既にあるクッキーを取り出します
    %cookies = fetch CGI::Cookie;
    $id = $cookies{'ID'}->value;

    # 外部ソースから返されたクッキーを作成します
    %cookies = parse CGI::Cookie($ENV{COOKIE});

説明

CGI::CookieはNetscape(HTTP/1.1)クッキーへのインターフェースで、Webｓ－バに接続のブラウザ側で永続する情報を格納させることを可能にする新機能です。CGI::CookieはCGI.pmと一緒に使うように意図しています（そして内部的には事実それによって使われています）が、このモジュールを独立だけで使うことも出来ます。

クッキーについての完全な情報はここをご覧下さい：

        http://www.ics.uci.edu/pub/ietf/http/rfc2109.txt

CGI::Cookieの使い方

CGI::Cookieはオブジェクト指向です。各クッキーオブジェクトは名前と値を持ちます。名前にはすべてのスカラ値が指定できます。値はスカラ、配列の値であればなんでも指定できます（連想配列も許されます）。クッキーは以下のものを含めて、多くの属性も持っています：

有効期限(expiration time)
これはクッキーの有効期限をしめす時刻／日付の文字列（特別なGMTフォーマットによる）です。ユーザがブラウザを終了させ、再起動したならば、この有効期限が来るまで、クッキーは保存され、スクリプトに返されます。有効期限が指定されなければ、クッキーはユーザがブラウザを終わらせるまで有効です。
ドメイン（domain)
これはクッキーが有効であるドメイン名の全体あるいは一部です。ブラウザはドメイン名の一部がマッチする、すべてのホストにクッキーを返します。例えば、ドメイン名に".capricorn.com"を指定すれば、ブラウザは"www.capricorn.com", "www2.capricorn.com", "feckless.capricorn.com"などのマシンのすべて実行されているWebサーバにクッキーを返します。".edu"のように最上位のドメインにマッチしようとすることを防ぐよう、ドメイン名は少なくとも２つのピリオドが入っていなければなりません、もしドメインが指定されなければ、ブラウザはクッキーが作成されたホストのサーバにだけクッキーを返します。
パス(path)
クッキーpath属性を与えるとブラウザは、クッキーを返す前にスクリプトのURLをチェックします。例えば、パスを"/cgi-bin"と指定すれば、"/cgi-bin/tally.pl", "/cgi-bin/order.pl", そして"/cgi-bin/customer_service/complain.pl"のそれぞれのスクリプトには返されますが、"/cgi-private/site_admin.pl'"には返されません。デフォルトではパスは"/"で、これはクッキーはあなたのサイトのすべてのCGIスクリプトに送信されます。
"安全"フラグ("secure" flag)
もし"secure"属性が設定されれば、クッキーは、CGIリクエストがSSLのようなセキュアなチャンネルで発生された場合にのみ送信されます。

新しいクッキーの作成

        $c = new CGI::Cookie(-name    =>  'foo',
                             -value   =>  'bar',
                             -expires =>  '+3M',
                             -domain  =>  '.capricorn.com',
                             -path    =>  '/cgi-bin/database'
                             -secure  =>  1
                            );

newメソッドで始めからクッキーを作成してください。 -name と -value パラメータは必須です。名前(name)はスカラ値でなけばなりません。値(value)はスカラ、配列リファレンス、またはハッシュ・リファレンスにすることができます。（将来のどこかの時点で、クッキーは完全に一般的なPerlオブジェクト・シライアライゼーション・プロトコルの１つをサポートするでしょう）

-expires はCGI.pmで理解されるフォーマットの相対あるいは絶対日付すべてを受取ります。例えば"+3M"は３ヶ月先です。詳細はCGI.pmのドキュメントをごらんください。

-domain はドメイン名または完全に修飾されたホスト名を示します。もし指定されなければ、クッキーはそれが作成されたWebサーバーにしか返されません。

-path は現在のサーバーでのURLの一部を返します。クッキーは指定されたパスで始まるすべてのURLへ返されます。指定されなければ、デフォルトで"/"になります、これはあなたのサイトのすべてのページにクッキーを返します。

-secure true値に設定すると暗号プロトコルが使われているときにだけクッキーを返すようにブラウザに命令します。

ブラウザにクッキーを送信

CGIスクリプトではHTTPヘッダで１つまたは複数のSet-Cookie:フィールドを作ることによってブラウザにクッキーを送信することが出来ます。以下に典型的なシーケンスを示します：

  my $c = new CGI::Cookie(-name    =>  'foo',
                          -value   =>  ['bar','baz'],
                          -expires =>  '+3M');

  print "Set-Cookie: $c\n";
  print "Content-Type: text/html\n\n";

複数のクッキーを送信するためには、たくさんのSet-Cookie:を作ってください。そうでなければクッキーを";"でつなげて、それを1つのフィールドで送ることが出来ます。

CGI.pmを使っているならば、header()メソッドに-cookie引数を与えることによりクッキーを送信します：

  print header(-cookie=>$c);

Mod_perl のユーザはrequestオブジェクトのheader_out()メソッドを使って設定できます：

  $r->header_out('Set-Cookie',$c);

内部的には、CookieはHTTPヘッダに入れられると、そのas_string()を呼びたすための""オペレータをオーバーロードします。as_string()はクッキーの内部表現をRFC互換のテキスト表現に変換します。もし好きであれば、as_stringを呼ぶことも出来ます：

  print "Set-Cookie: ",$c->as_string,"\n";

以前のクッキーの回復

        %cookies = fetch CGI::Cookie;

fetch はブラウザから返されたすべてのクッキーが入った連想配列を返します。その配列のキーはクッキーの名前です。クッキー全体を以下のようにして繰り返すことが出来ます：

        %cookies = fetch CGI::Cookie;
        foreach (keys %cookies) {
           do_something($cookies{$_});
        }

スカラコンテキストでは、fetch()はハッシュ・リファンレンスを返します。それは複数のクッキーを扱っているならより効率的かもしれません。

CGI.pmは、そのクッキーでの予約文字を保存し、元に戻すためにURLエスケープするメソッドを使います。よそのサーバにより設定されたクッキーを取り出そうとしているのであれば、このエスケープするメソッドはあなたをつまづかせるかもしれません。代りにraw_fetch()を使ってください。それはfetch()と同じ意味ですが、アンエスケープはしません。

parse()クラスメソッドでいくつかの外部形式に格納されたクッキーも取り出すことができます：

       $COOKIES = `cat /usr/tmp/Cookie_stash`;
       %cookies = parse CGI::Cookie($COOKIES);

クッキーの取り扱い

Cookieオブジェクトはクッキー属性を取得し設定する一連のアクセサ・メソッドを持っています。各アクセサは同じ書式です。引数なしに呼ばれると、アクセサはその属性の現在の値を返します。引数付きで呼ばれると、アクセサはその属性を変更し、その新しい値を返します。

name()

クッキーの名前を取得または設定します。例：

        $name = $c->name;
        $new_name = $c->name('fred');

value()

クッキーの値を取得または設定します。例：

        $value = $c->value;
        @new_value = $c->value(['a','b','c','d']);

value() はコンテキストに敏感です。配列コンテキストでは、配列でクッキーの値を返します。スカラ・コンテキストでは複数の値を持つクッキーの最初の値を返します。

domain()

クッキーのドメインを取得または設定します。

path()

クッキーのパスを取得または設定します。

expires()

クッキーの有効期限を取得または設定します。

作者情報

（原文のまま）

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

バグレポートとコメントはlstein@cshl.org に送ってください。

バグ

このセクションは最初はブランクのままです。

（訳者注：どうもデフォルトのままのようです）

参考資料

CGI::Carp, CGI

ホーム　Perlの小技

ご意見、ご質問はこちらの掲示板で受け付けています。
またメールは河馬屋(Nifty)にお願いします。

CGI::Cookieモジュール

目次