名前¶
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は、Webサーバに、接続についての永続的な情報をブラウザ側に 格納させることを可能にする新機能である、Netscape(HTTP/1.1)クッキーへの インターフェースです。CGI::CookieはCGI.pmと一緒に使うよう意図されています (そして事実、内部的にはそれによって使われています)が、このモジュールだけを 独立で使うことも出来ます。
クッキーについての完全な情報はこちらをご覧下さい
http://www.ics.uci.edu/pub/ietf/http/rfc2109.txt
CGI::Cookieの使い方¶
CGI::Cookieはオブジェクト指向です。各クッキーオブジェクトは名前と値を 持ちます。名前にはスカラー値が指定できます。値はスカラー、配列の値が 指定できます(連想配列も許されます)。クッキーは以下のものを含めて、 多くの属性も持っています:
- 1. 有効期限(expiration date)
-
有効期限はブラウザにいつまでクッキーを保持するかを伝えます。 もしクッキーが将来の日付を指定すれば、ブラウザはクッキーの情報を ディスク・ファイルに格納し、(有効期限になるまで)ユーザが再接続 するたびにサーバーに、それを返します。もしクッキーが過去の日付を 指定していたら、ブラウザはディスク・ファイルからクッキーを削除します。 もし有効期限が指定されなければ、クッキーはユーザがブラウザを終わら せるまで有効です。
- 2. ドメイン(domain)
-
これはクッキーが有効であるドメイン名の全体あるいは一部になります。 ブラウザはドメイン名の一部がマッチする、全てのホストにクッキーを 返します。例えばドメイン名に".capricorn.com"を指定すれば、 ブラウザは"www.capricorn.com", "www2.capricorn.com", "feckless.capricorn.com"などのマシンで実行されている全ての Webサーバにクッキーを返します。".edu"のように最上位のドメインに マッチさせようとすることを防ぐため、ドメイン名は少なくとも2つの ピリオドが入っていなければなりません。もしドメインが指定されなければ、 ブラウザはクッキーが作成されたホストのサーバにだけクッキーを返します。
- 3. パス(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スクリプトが、そのクッキーを受信します。
- 4. 安全フラグ(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オブジェクト・シライアライゼーション・プロトコルの1つをサポートするでしょう)
-expiresはCGI.pmで理解されるフォーマットの相対あるいは絶対日付を 受取ります。例えば"+3M"は3ヶ月先です。詳細はCGI.pmのドキュメントを ごらんください。
-domainはドメイン名または完全に修飾されたホスト名を示します。 もし指定されなければ、クッキーはそれが作成されたWebサーバーにしか 返されません。
-pathは現在のサーバーでのURLの一部を返します。クッキーは指定された パスで始まるすべてのURLへ返されます。指定されなければ、デフォルトは"/"になります。 これはあなたのサイトのすべてのページにクッキーを返します。
-securetrue値に設定すると暗号プロトコルが使われているときにだけ クッキーを返すようブラウザに指示します。
ブラウザにクッキーを送信¶
CGIスクリプトではHTTPヘッダで1つまたは複数の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()
-
クッキーの有効期限を取得または設定します。
作者情報(AUTHOR INFORMATION)¶
Copyright 1997-1998, Lincoln D. Stein. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
バグレポートとコメントはこちらへ: lstein@cshl.org
バグ¶
このセクションは最初はブランクのままです。
(訳者注:どうもデフォルトのままのようです)
参考資料¶
翻訳者¶
川合孝典(GCD00051@nifty.ne.jp)