=encoding utf8 =pod =head1 NAME CGI::Session - CGIアプリケーションにおける持続的なデータのセッション =head1 SYNOPSIS # オブジェクトの初期化: use CGI::Session; $session = new CGI::Session(); $CGISESSID = $session->id(); # クッキーを含む適切なHTTPヘッダーの送出: print $session->header(); # セッションにデータを格納 $session->param('f_name', 'Sherzod'); # or $session->param(-name=>'l_name', -value=>'Ruzmetov'); # データの回収 my $f_name = $session->param('f_name'); # または my $l_name = $session->param(-name=>'l_name'); # 特定セッションパラメータのクリア $session->clear(["l_name", "f_name"]); # '_is_logged_in'フラグは10分間アイドルした後期限切れになります $session->expire('is_logged_in', '+10m') # '_IS_LOGGED_IN'フラグは10分間アイドルした後期限切れになります $session->expire(_IS_LOGGED_IN => '+10m'); # セッションそのものが1時間アイドルした後期限切れになります $session->expire('+1h'); # セッションを削除したほうが良いでしょう $session->delete(); =head1 DESCRIPTION CGI-SessionはHTTPリクエストを介した簡潔で、信頼性のあるモジュール方式のセッション管理システムを提供するPerl5のライブラリです。 永続性は、ショッピングカートや、ログイン/認証ルーチン、HTTPリクエストを介してデータを持ち運ぶ操作が必要なアプリケーションといったものにとってはキーとなる機能です。 CGI::Sessionではそれを行うと共に、それ以上の多くのことも行います。 =head1 TO LEARN MORE 現在のマニュアルはクイックリファレンスとして活用されています。 その哲学と、CGI::Sessionのプログラミングスタイルにの両方についてより深く学ぶためには以下を参考にして下さい: =over 4 =item * L - CGI::Sessionに関して広範囲に記述されたマニュアルです。 ライブラリの構成やドライバの特性についての説明を含んでいます。 =item * 我々はCGI::Session usersのためのメーリングリストも提供しています。 メーリングリストを購読する、あるいはアーカイブを閲覧するためには https://lists.sourceforge.net/lists/listinfo/cgi-session-user を訪れて下さい。 =item * B - "HTTP State Management Mechanism"は ftp://ftp.isi.edu/in-notes/rfc2965.txt で見付かります。 =item * L - 標準CGIライブラリ =item * L - CGI::Sessionに対するもう一つの素晴らしい選択肢。 =back =head1 METHODS 以下はCGI::Sessionオブジェクト経由で使用可能な全メソッドの概要です。 =over 4 =item new() =item new( $sid ) =item new( $query ) =item new( $dsn, $query||$sid ) =item new( $dsn, $query||$sid, \%dsn_args ) コンストラクタ。新しいセッションオブジェクト化、失敗時にはundefを返します。エラーメッセージにはLを介してアクセスできます。すでに初期化済のセッションで呼ばれた時には、すでに設定されているオブジェクトに基づいて再度初期化します。これはLの呼出後に限り有用でしょう。 3つまでの引数、$dsn - データソース名、$query||$sid - クエリオブジェクトまたはセッションIDを示す文字列、そして最後に\%dsn_args、$dsnコンポーネントで使われる引数を受け取ることができます。 引数なしで呼ばれた時は、$dsnはIを、$query||$sidはC<< CGI->new() >>を、そしてC<\%dsn_args>はIをデフォルトとします。 引数1つで呼ばれた時には、これはその種類に応じて、C<$query>またはC<$sid>のいずれかとして扱われます。引数が文字列であれば、CはこれをセッションIDとして扱い、データストアからセッションの取得を試みます。これが失敗すると、新しいセッションIDを生成しますが、これにはLでアクセスできます。引数がオブジェクトであれば、その中にあるC<$sid>を見つけるためと、これをデータストアから取得するために、LとLメソッドが呼ばれます。これが失敗すると、新しいセッションIDを生成しますが、これにはLでアクセスできます。Cはクエリパラメータおよびクッキー名を定義しますが、このデフォルトはIです。 引数2つで呼ばれた時には、最初のものは$dsn、2番目はその種類に応じて、$queryまたは$sidまたはundefとして扱われます。この記法のサンプルです: $s = CGI::Session->new("driver:mysql", undef); $s = CGI::Session->new("driver:sqlite", $sid); $s = CGI::Session->new("driver:db_file", $query); $s = CGI::Session->new("serializer:storable;id:incr", $sid); # etc... 以下のデータソースコンポーネントがサポートされています。 =over 4 =item * B - CGI::Session のドライバです。使用可能なドライバはL、L、L、及びLです。 サードパーティのドライバを歓迎します。ドライバの仕様についてはLを検討してください。 =item * B - シリアライザはデータをディスクに保存する前に、データ構造をエンコードするために用いられます。 使用可能なシリアライザはL、LおよびLです。 defaultシリアライザはLを用います。 =item * B - 新しいセッションが作成される際に用いられるIDジェネレータです。 使用可能なIDジェネレータはLです。 =back 例えば、データの保持にはDB_Fileを使用し、データのシリアライズにはFreezeThawを使うCGI::Sessionを得るには: $s = new CGI::Session("driver:DB_File;serializer:FreezeThaw", undef); 引数3つで呼ばれた時には、最初の二つはこれまでの例と同様に扱われ、三番目の引数はC<\%dsn_args>として、C<$dsn>コンポーネント（すなわち、ドライバー、シリアライザ、そしてIDジェネレータ）に初期化の目的で渡されます。$dsnコンポーネントは何らかのデフォルト地で初期化される必要があるので、この3番目の引数は大半のドライバを正しく扱う上で、必須ではないはずです。 undefは上述の引数で場所埋めのための妥当な値として使用でき、デフォルトの振る舞いをさせます。 =item load() =item load($query||$sid) =item load($dsn, $query||$sid) =item load($dsn, $query, \%dsn_args); コンストラクタ。使い方はLと同じで、戻り値もそうです。大きな違いは、Lは期限切れまたは存在しないセッションに対しては新しいセッションを生成しますが、Cはそうしません。 Cは、ライブラリに新しいセッションを生成させることなく、期限切れまたは存在しないセッションを検出するのに役立ちます。つまり、このようなことができます: $s = CGI::Session->load() or die CGI::Session->errstr(); if ( $s->is_expired ) { print $s->header(), $cgi->start_html(), $cgi->p("セッションがタイムアウトしました！スクリーンをリフレッシュして新しいセッションを始めてください！") $cgi->end_html(); exit(0); } if ( $s->is_empty ) { $s = $s->new() or die $s->errstr; } 注意、全てのI<期限切れ>のセッションは空ですが、全てのI<空>のセッションが期限切れというわけではありません！ =cut =pod =item id() セッションのための有効なIDを返します。 有効なIDと要求されたIDが異なる可能性もあるため、有効なセッションidはこのメソッドを用いることでいつも解決すべきです。 =item param($name) =item param(-name=E$name) 上のどちらの書き方でも、$nameにセットされたセッションパラメータか、存在しなければundefを返します。もしこれが削除されたメソッドparam()で呼び出された時には警告を出しますが、戻り値は定義されていません。 =item param($name, $value) =item param(-name=E$name, -value=E$value) 上のどちらの書き方で使われ、あとで前述したparam()の書き方で取得できるように、$nameパラメータに新しい値をセットします。スカラ、配列リファレンス、ハッシュリファレンスをC<$value>にできます。 I<_SESSION_>で始まるパラメータ名にセットしようとすると、警告が誘発され、undefが返されます。 =item param_hashref() B<推奨されません>。かわりにLを使います。 =item dataref() セッションのデータテーブルへのリファレンスを返します: $params = $s->dataref(); $sid = $params->{_SESSION_ID}; $name= $params->{name}; # etc... ハッシュリファレンス内の全てのセッションデータを取得するのには便利ですが、更新するのはリスキーです。 =item save_param() =item save_param($query) =item save_param($query, \@list) クエリパラメータをセッションオブジェクトに保存します。言い替えれば、C<< $query->param() >>が返す個々のパラメータ全てに対してLを呼ぶのと同じです。最初の引数は、与えるとすれば、CGIオブジェクトか、又はparam()メソッドを提供することのできるオブジェクトです。もしこれがundefであれば、C<< CGI->new >>を返すLの戻り値をデフォルトにします。もし２つ目の引数が与えられ、それが配列へのリファレンスであるならば、配列中で見つかったクエリパラメータのみがセッション中に格納されます。undefは上述の引数で場所埋めのための妥当な値として使用でき、デフォルトの振る舞いをさせます。 =item load_param() =item load_param($query) =item load_param($query, \@list) セッションパラメータをクエリオブジェクトにロードします。最初の引数は、与えるとすれば、CGIオブジェクトか、又はparam()メソッドを提供することのできるオブジェクトです。もし２つ目の引数が与えられ、それが配列へのリファレンスであるならば、配列中で見つかったパラメータのみがクエリオブジェクトにロードされます。 =item clear() =item clear('field') =item clear(\@list) セッションオブジェクトからパラメータをクリアします。 引数なしの場合、全てのフィールドがクリアされます。一つのパラメータ、または配列リファレンスが渡されれば、その名前のパラメータだけがクリアされます。 =item flush() メモリ上のデータを、ドライバによってシリアライズされたコピーと同期させます。現在のセッションオブジェクトの外部からアクセスする必要がある場合にflush()を呼びます。少なくとも、プログラムを終了する前にflash()を呼ぶ必要があります。 最終的には、CGI::Sessionはプログラムが終了されるか、セッションオブジェクトがスコープの外に行こうとする直前に、自動的にflushを呼びます。この自動的な振る舞いは、4.xシリーズより前までは推奨動作でした。自動でのflushが信頼できないことが判明したため、いくつかのケース3.xでは自動的に動作していた場所でもいくつかの場合にはこれが必要とされます。詳細は以下を参照: http://rt.cpan.org/Ticket/Display.html?id=17541 http://rt.cpan.org/Ticket/Display.html?id=17299 =item atime() 読み取り専用メソッド。セッションが最後にアクセスされた時間を新紀元からの秒数の形式で返します。この時間は、自動的に期限切れになるセッション、又はセッションのパラメータ、あるいはその両方で内部的に使用されます。 =item ctime() 読み取り専用メソッド。セッションが最初に生成された時間を新紀元からの秒数の形式で返します。 =item expire() =item expire($time) =item expire($param, $time) Lに関連した期限切れまでの間隔をセットします。 引数なしで使用すると、既にセットされていれば期限切れまでの間隔を返します。期限がこれまでに設定されていなければ、undefを返します。後方互換性のために、Cという名前のメソッドも同じことをします。 2番目の形式は期限切れ時間をセットします。この値は以前に保持されたセッションの取得問い合わせの際にチェックされ、その期限切れ間隔が過ぎていれば、即座にディスクから抹消されます。0を渡すと期限がキャンセルされます。 3番目の書き方で使用すると、I<~logged-in>などといった、適切なセッションパラメータの期限をセットすることができます。こうすると、ライブラリは時間切れになった時に、このパラメータに対してclear()を呼びます。0を渡すと期限がキャンセルされます。 どの時間の値も、秒数の形式で与えることができます。利便性のため、以下のキーワードもサポートされています: +===========+===============+ |エイリアス | 意味 | +===========+===============+ | s | 秒 | | m | 分 | | h | 時 | | d | 日 | | w | 週 | | M | 月 | | y | 年 | +-----------+---------------+ 例: $session->expire("2h"); # 2時間が有効期限 $session->expire(0); # 有効期限をキャンセル $session->expire("~logged-in", "10m"); # '~logged-in'パラメータは10分のインターバル後に期限切れ Note: 有効期限は全て、セッションの最終アクセス時刻からのもので、作成された時間からではありません。ただちにセッションを期限切れにするにはLを呼び出して下さい。特定のセッションパラメータをすぐに期限切れにするにはそのパラメータに対してLを呼び出して下さい。 =cut =pod =item is_new() まっさらの新しいセッションの時だけ、trueを返します。 =item is_expired() Lで初期化されたセッションが期限切れかどうかをテストします。このメソッドはload()で初期化されたセッションでのみ動作します: $s = CGI::Session->load() or die CGI::Session->errstr; if ( $s->is_expired ) { die "Your session expired. Please refresh"; } if ( $s->is_empty ) { $s = $s->new() or die $s->errstr; } =item is_empty() 空のセッションに対してはtrueを返します。これはリクエストされたセッションのロードが成功したか否かのテストとして好まれる方法です: $s = CGI::Session->load($sid); if ( $s->is_empty ) { $s = $s->new(); } 実際には、上のコードは最悪以外の何者でもありません。同じ効果はこうすれば得られたでしょう: $s = CGI::Session->new( $sid ); Lは期限切れのセッションに対するリクエストをキャッチし、それから新しいセッションを生成したいという時にのみ有用です。例として、Lを参照してください。 =item delete() 完全に、データストアからセッションを削除し、そしてメモリからセッションのデータを空にし、結果として以降の同じオブジェクトへのread/writeリクエストは失敗します。技術的にいえば、これはオブジェクトのステータスをIにし、Lを起動して、flush()実際の削除を行います。 =item find( \&code ) =item find( $dsn, \&code ) =item find( $dsn, \&code, \%dsn_args ) 実験的な機能です。初期化されたCGI::Sessionオブジェクトを\&codeに対する最初の引数として、ディスクに保持されている全てのセッションオブジェクトに対して\&codeを実行します。整理整頓の実現、例えば期限切れセッションの削除などに有用です。以下の行は、実際に、既に期限切れしているものの、まだディスク上にあるセッションを削除します: CGI::Session->find( sub {} ); 注意、上の\&codeは何もすることがありません。というのは、find()内でセッションの初期化のために呼び出されるload()は、自動的に期限切れのセッションを削除するからです。以下の例は10日以上経過しているオブジェクトを全て削除します。 CGI::Session->find( \&purge ); sub purge { my ($session) = @_; next if $session->empty; # <-- 既に期限切れ？ if ( ($session->ctime + 3600*240) <= time() ) { $session->delete() or warn "couldn't remove " . $session->id . ": " . $session->errstr; } } B: findはセッションが返す修正時刻あるいはアクセス時刻を変更しません。 Cの3つのパラメータの説明: =over 4 =item $dsn これは以前にどのタイプのセッションを作成しており、コールバックにどの種類のセッションを渡して欲しいとCに望むかのコントロールにCGI::Sessionが使うDSN（Data Source Name）です。 デフォルト値は上のCメソッドのところで定義されている通り、'driver:file;serializer:default;id:md5'です。 このDSNと、すぐあとの\%dsn_argsの下で出てくる引数のDSNを混同しないで下さい。 =item \&code Cメソッドが与えられた$dsnに相当するセッションを見つけるたびに一度、CGI::Sessionが呼び出すコールバックで、あなた（つまりCメソッドを呼び出す人）が用意するものです。 このコードリファレンスにはデフォルト値はありません。 実際にあなたのコールバックが呼び出される時の、唯一のパラメータはセッションです。もし既にある追加のパラメータとあわせてサブルーチンを呼びたければ、サブルーチンを希望のパラメータ付きで呼び出す無名サブルーチンを作成することで実現できます。例えば: CGI::Session->find($dsn, sub { my_subroutine( @_, 'param 1', 'param 2' ) } ); CGI::Session->find($dsn, sub { $coderef->( @_, $extra_arg ) } ); あるいは、お望みであれば、このようなサブジェネレータを定義することもできます: sub coderef_with_args { my ( $coderef, @params ) = @_; return sub { $coderef->( @_, @params ) }; } CGI::Session->find($dsn, coderef_with_args( $coderef, 'param 1', 'param 2' ) ); =item \%dsn_args $dsnがファイルベースのストレージであれば、このハッシュリファレンスは次のようなキーを持つかもしれません: { Directory => Value 1, NoFlock => Value 2, UMask => Value 3 } $dsnがDBベースのストレージであれば、このハッシュリファレンスはこのような3つ（まで）のキーを持つかもしれません: { DataSource => Value 1, User => Value 2, Password => Value 3 } このDSN、ユーザー名、パスワードの3つという形態はDBIがデータベースサーバへのアクセスをコントロールするもので、したがってDBベースのせっしょを使うときだけに関連するものです。 このハッシュリファレンスのデフォルト値はundefです。 =back B find() is meant to be convenient, not necessarily efficient. It's best suited in cron scripts. =head1 MISCELLANEOUS METHODS =over 4 =item remote_addr() このセッションを最初に作成した時のユーザーのリモートアドレスです。セッションが作成された時の環境変数にREMOTE_ADDRがなければ、undefを返します。 =cut =pod =item errstr() クラスメソッドです。最後のこのライブラリからのエラーメッセージを返します。 =item dump() セッションオブジェクトのダンプを返します。デバッグの目的に限っては便利でしょう。 =item header() Lのheader()メソッドを置き換えます。このメソッドを使わないのであれば、常にCGI::Cookieオブジェクトを作成し、HTTPヘッダーの一部として送る必要があります。 $cookie = CGI::Cookie->new(-name=>$session->name, -value=>$session->id); print $cgi->header(-cookie=>$cookie); 上を手間を最小限に留めることができます: print $session->header(); これはC<$CGI::Session::NAME>をデフォルト値とするセッションクッキー名をC<$session->name()>から取得します。セッションクッキーに別の名前を使いたいときは、セッションオブジェクトを作る前に以下のようなことをします: CGI::Session->name("MY_SID"); $session = new CGI::Session(undef, $cgi, \%attrs); これで、$session->header()は"MY_SID"をこのセッションの名前として使用します。 =item query() 現在のセッションオブジェクトに関連付けられたクエリオブジェクトを返します。デフォルトのクエリオブジェクトのクラスはLです。 =back =head2 DEPRECATED METHODS これらのメソッドは唯一CGI::Session 3.xとの互換性のためだけに存在します。 =over 4 =item close() セッションを閉じます。代わりにflush()を使うことを、これは現在のclose()の呼び出しがまさしくしていることでもあり、推奨します。 =back =head1 DISTRIBUTION CGI::SessionはL、L、およびLといったいくつかのコンポーネントから成ります。このセクションでは利用できるもののリストを挙げます。 =head2 DRIVERS 以下のドライバは標準配布物に含まれています: =over 4 =item * L - セッションデータをプレーンファイルに保存するデフォルトのドライバです。フルネーム: B =item * L - セッションデータをBerkelyDBに保存するためのものです。要求事項: L。フルネーム: B =item * L - セッションデータをMySQLのテーブルに保存するためのものです。LとLが必要です。フルネーム: B =item * L - セッションデータをSQLiteに保存するためのものです。LとLが必要です。フルネーム: B =back =head2 SERIALIZERS =over 4 =item * L - デフォルトのデータシリアライザです。標準のLを使います。フルネーム: B =item * L - Lを使うデータシリアライザです。Lが必要です。フルネーム: B =item * L - Lを使う出たシリアライザです。Lが必要です。フルネーム: B =item * L - YAMLを使ってデータをシリアライズします。LかLが必要です。フルネーム: B =item * L - JSONを使ってデータをシリアライズします。Lが必要です。フルネーム: B =back =head2 ID GENERATORS 以下のIDジェネレータを使用できます: =over 4 =item * L - 32文字の長い16進数文字列を生成します。Lが必要です。フルネーム: B =item * L - 1ずつ増えていく（インクリメンタル）IDを生成します。 =item * L - 静的なセッションIDを生成します。B =back =head1 CREDITS CGI::Sessionは、かの開発者の助けを得て現在の形に発展しました。このリストは厳密な順序に従ったものではありませんが、ある程度時系列のものです。詳細は、Fファイルにあります。 =over 4 =item Andy Lester =item Brian King Emrbbking@mac.comE =item Olivier Dragon Edragon@shadnet.shad.caE =item Adam Jacob Eadam@sysadminsith.orgE =item Igor Plisco Eigor@plisco.ruE =item Mark Stosberg Emarkstos@cpan.orgE =item Matt LeBlanc Emleblanc@cpan.orgE =item Shawn Sorichetti =back =head1 COPYRIGHT Copyright (C) 2001-2005 Sherzod Ruzmetov Esherzodr@cpan.orgE. All rights reserved. This library is free software. You can modify and or distribute it under the same terms as Perl itself. =head1 PUBLIC CODE REPOSITORY あなたは、最後のリリース以後に開発者が行ったことを、コードリポジトリからチェックアウトすることで見ることができます。 ここからSubversionリポジトリをブラウズできます: http://svn.cromedome.net/ あるいは、ここからCで直接チェックしてください: svn://svn.cromedome.net/CGI-Session =head1 SUPPORT CGI::Sessionを使うにあたってヘルプが必要であれば、メーリング・リストを検討してください。 cgi-session-user@lists.sourceforge.net に質問を送ることで、（メーリング）リストに問い合わせることができます。 メーリング･リストへの参加は https://lists.sourceforge.net/lists/listinfo/cgi-session-user からできます。 バグレポートは http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Session で受け取ります。 =head1 AUTHOR Sherzod Ruzmetov Esherzodr@cpan.orgE, http://author.handalak.com/ Mark Stosbergは4.0の開発においては副メンテナになりました。 C. =head1 SEE ALSO =over 4 =item * L - より長いCGI::Sessionマニュアル =item * B - "HTTP State Management Mechanism"、所在は ftp://ftp.isi.edu/in-notes/rfc2965.txt =item * L - standard CGI library =item * L - CGI::Sessionの良い代替 =back =head1 DOCUMENT TRANSLATION Makio Tsukamoto, tsukamoto@gmail.com 和訳にあたっては、三浦真磁氏によるCGI::Session 3.11版の和訳を参考にさせていただきました。 これは、perldoc.jpでアクセスすることができます。 =cut