Page Top

NAME

CGI::Session - CGIアプリケーションにおける持続的なデータのセッション

Page Top

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();

Page Top

DESCRIPTION

CGI-SessionはHTTPリクエストを介した簡潔で、信頼性のあるモジュール方式のセッション管理システムを提供するPerl5のライブラリです。 永続性は、ショッピングカートや、ログイン/認証ルーチン、HTTPリクエストを介してデータを持ち運ぶ操作が必要なアプリケーションといったものにとってはキーとなる機能です。 CGI::Sessionではそれを行うと共に、それ以上の多くのことも行います。

Page Top

TO LEARN MORE

現在のマニュアルはクイックリファレンスとして活用されています。 その哲学と、CGI::Sessionのプログラミングスタイルにの両方についてより深く学ぶためには以下を参考にして下さい:

Page Top

METHODS

以下はCGI::Sessionオブジェクト経由で使用可能な全メソッドの概要です。

new()
new( $sid )
new( $query )
new( $dsn, $query||$sid )
new( $dsn, $query||$sid, \%dsn_args )

コンストラクタ。新しいセッションオブジェクト化、失敗時にはundefを返します。エラーメッセージにはerrstr() - クラスメソッドを介してアクセスできます。すでに初期化済のセッションで呼ばれた時には、すでに設定されているオブジェクトに基づいて再度初期化します。これはload()の呼出後に限り有用でしょう。

3つまでの引数、$dsn - データソース名、$query||$sid - クエリオブジェクトまたはセッションIDを示す文字列、そして最後に\%dsn_args、$dsnコンポーネントで使われる引数を受け取ることができます。

引数なしで呼ばれた時は、$dsnはdriver:file;serializer:default;id:md5を、$query||$sidはCGI->new()を、そして\%dsn_argsはundefをデフォルトとします。

引数1つで呼ばれた時には、これはその種類に応じて、$queryまたは$sidのいずれかとして扱われます。引数が文字列であれば、new()はこれをセッションIDとして扱い、データストアからセッションの取得を試みます。これが失敗すると、新しいセッションIDを生成しますが、これにはid()メソッドでアクセスできます。引数がオブジェクトであれば、その中にある$sidを見つけるためと、これをデータストアから取得するために、cookie()とparam()メソッドが呼ばれます。これが失敗すると、新しいセッションIDを生成しますが、これにはid()メソッドでアクセスできます。name()はクエリパラメータおよびクッキー名を定義しますが、このデフォルトはCGISESSIDです。

引数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...

以下のデータソースコンポーネントがサポートされています。

例えば、データの保持にはDB_Fileを使用し、データのシリアライズにはFreezeThawを使うCGI::Sessionを得るには:

    $s = new CGI::Session("driver:DB_File;serializer:FreezeThaw", undef);

引数3つで呼ばれた時には、最初の二つはこれまでの例と同様に扱われ、三番目の引数は\%dsn_argsとして、$dsnコンポーネント（すなわち、ドライバー、シリアライザ、そしてIDジェネレータ）に初期化の目的で渡されます。$dsnコンポーネントは何らかのデフォルト地で初期化される必要があるので、この3番目の引数は大半のドライバを正しく扱う上で、必須ではないはずです。

undefは上述の引数で場所埋めのための妥当な値として使用でき、デフォルトの振る舞いをさせます。

load()
load($query||$sid)
load($dsn, $query||$sid)
load($dsn, $query, \%dsn_args);

コンストラクタ。使い方はnew()と同じで、戻り値もそうです。大きな違いは、new()は期限切れまたは存在しないセッションに対しては新しいセッションを生成しますが、load()はそうしません。

load()は、ライブラリに新しいセッションを生成させることなく、期限切れまたは存在しないセッションを検出するのに役立ちます。つまり、このようなことができます:

    $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;
    }

注意、全ての期限切れのセッションは空ですが、全ての空のセッションが期限切れというわけではありません！

id()

セッションのための有効なIDを返します。 有効なIDと要求されたIDが異なる可能性もあるため、有効なセッションidはこのメソッドを用いることでいつも解決すべきです。

param($name)
param(-name=>$name)

上のどちらの書き方でも、$nameにセットされたセッションパラメータか、存在しなければundefを返します。もしこれが削除されたメソッドparam()で呼び出された時には警告を出しますが、戻り値は定義されていません。

param($name, $value)
param(-name=>$name, -value=>$value)

上のどちらの書き方で使われ、あとで前述したparam()の書き方で取得できるように、$nameパラメータに新しい値をセットします。スカラ、配列リファレンス、ハッシュリファレンスを$valueにできます。

_SESSION_で始まるパラメータ名にセットしようとすると、警告が誘発され、undefが返されます。

param_hashref()

推奨されません。かわりにdataref()を使います。

dataref()

セッションのデータテーブルへのリファレンスを返します:

    $params = $s->dataref();
    $sid = $params->{_SESSION_ID};
    $name= $params->{name};
    # etc...

ハッシュリファレンス内の全てのセッションデータを取得するのには便利ですが、更新するのはリスキーです。

save_param()
save_param($query)
save_param($query, \@list)

クエリパラメータをセッションオブジェクトに保存します。言い替えれば、$query->param()が返す個々のパラメータ全てに対してparam($name, $value)を呼ぶのと同じです。最初の引数は、与えるとすれば、CGIオブジェクトか、又はparam()メソッドを提供することのできるオブジェクトです。もしこれがundefであれば、CGI->newを返すquery()の戻り値をデフォルトにします。もし２つ目の引数が与えられ、それが配列へのリファレンスであるならば、配列中で見つかったクエリパラメータのみがセッション中に格納されます。undefは上述の引数で場所埋めのための妥当な値として使用でき、デフォルトの振る舞いをさせます。

load_param()
load_param($query)
load_param($query, \@list)

セッションパラメータをクエリオブジェクトにロードします。最初の引数は、与えるとすれば、CGIオブジェクトか、又はparam()メソッドを提供することのできるオブジェクトです。もし２つ目の引数が与えられ、それが配列へのリファレンスであるならば、配列中で見つかったパラメータのみがクエリオブジェクトにロードされます。

clear()
clear('field')
clear(\@list)

セッションオブジェクトからパラメータをクリアします。

引数なしの場合、全てのフィールドがクリアされます。一つのパラメータ、または配列リファレンスが渡されれば、その名前のパラメータだけがクリアされます。

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
atime()

読み取り専用メソッド。セッションが最後にアクセスされた時間を新紀元からの秒数の形式で返します。この時間は、自動的に期限切れになるセッション、又はセッションのパラメータ、あるいはその両方で内部的に使用されます。

ctime()

読み取り専用メソッド。セッションが最初に生成された時間を新紀元からの秒数の形式で返します。

expire()
expire($time)
expire($param, $time)

atime()に関連した期限切れまでの間隔をセットします。

引数なしで使用すると、既にセットされていれば期限切れまでの間隔を返します。期限がこれまでに設定されていなければ、undefを返します。後方互換性のために、etime()という名前のメソッドも同じことをします。

2番目の形式は期限切れ時間をセットします。この値は以前に保持されたセッションの取得問い合わせの際にチェックされ、その期限切れ間隔が過ぎていれば、即座にディスクから抹消されます。0を渡すと期限がキャンセルされます。

3番目の書き方で使用すると、~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: 有効期限は全て、セッションの最終アクセス時刻からのもので、作成された時間からではありません。ただちにセッションを期限切れにするにはdelete()を呼び出して下さい。特定のセッションパラメータをすぐに期限切れにするにはそのパラメータに対してclear([$name])を呼び出して下さい。

is_new()

まっさらの新しいセッションの時だけ、trueを返します。

is_expired()

load()で初期化されたセッションが期限切れかどうかをテストします。このメソッドは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;
    }
is_empty()

空のセッションに対してはtrueを返します。これはリクエストされたセッションのロードが成功したか否かのテストとして好まれる方法です:

    $s = CGI::Session->load($sid);
    if ( $s->is_empty ) {
        $s = $s->new();
    }

実際には、上のコードは最悪以外の何者でもありません。同じ効果はこうすれば得られたでしょう:

    $s = CGI::Session->new( $sid );

is_empty()は期限切れのセッションに対するリクエストをキャッチし、それから新しいセッションを生成したいという時にのみ有用です。例として、is_expired()を参照してください。

delete()

完全に、データストアからセッションを削除し、そしてメモリからセッションのデータを空にし、結果として以降の同じオブジェクトへのread/writeリクエストは失敗します。技術的にいえば、これはオブジェクトのステータスをSTATUS_DELETEDにし、flush()を起動して、flush()実際の削除を行います。

find( \&code )
find( $dsn, \&code )
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;
        }
    }

Note: findはセッションが返す修正時刻あるいはアクセス時刻を変更しません。

find()の3つのパラメータの説明:

$dsn

これは以前にどのタイプのセッションを作成しており、コールバックにどの種類のセッションを渡して欲しいとfind()に望むかのコントロールにCGI::Sessionが使うDSN（Data Source Name）です。

デフォルト値は上のnew()メソッドのところで定義されている通り、'driver:file;serializer:default;id:md5'です。

このDSNと、すぐあとの\%dsn_argsの下で出てくる引数のDSNを混同しないで下さい。

\&code

find()メソッドが与えられた$dsnに相当するセッションを見つけるたびに一度、CGI::Sessionが呼び出すコールバックで、あなた（つまりfind()メソッドを呼び出す人）が用意するものです。

このコードリファレンスにはデフォルト値はありません。

実際にあなたのコールバックが呼び出される時の、唯一のパラメータはセッションです。もし既にある追加のパラメータとあわせてサブルーチンを呼びたければ、サブルーチンを希望のパラメータ付きで呼び出す無名サブルーチンを作成することで実現できます。例えば:

    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' ) );
\%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です。

Note: find() is meant to be convenient, not necessarily efficient. It's best suited in cron scripts.

Page Top

MISCELLANEOUS METHODS

remote_addr()

このセッションを最初に作成した時のユーザーのリモートアドレスです。セッションが作成された時の環境変数にREMOTE_ADDRがなければ、undefを返します。

errstr()

クラスメソッドです。最後のこのライブラリからのエラーメッセージを返します。

dump()

セッションオブジェクトのダンプを返します。デバッグの目的に限っては便利でしょう。

header()

CGI.pmのheader()メソッドを置き換えます。このメソッドを使わないのであれば、常にCGI::Cookieオブジェクトを作成し、HTTPヘッダーの一部として送る必要があります。

    $cookie = CGI::Cookie->new(-name=>$session->name, -value=>$session->id);
    print $cgi->header(-cookie=>$cookie);

上を手間を最小限に留めることができます:

    print $session->header();

これは$CGI::Session::NAMEをデフォルト値とするセッションクッキー名を$session-name()>から取得します。セッションクッキーに別の名前を使いたいときは、セッションオブジェクトを作る前に以下のようなことをします:

    CGI::Session->name("MY_SID");
    $session = new CGI::Session(undef, $cgi, \%attrs);

これで、$session->header()は``MY_SID''をこのセッションの名前として使用します。

query()

現在のセッションオブジェクトに関連付けられたクエリオブジェクトを返します。デフォルトのクエリオブジェクトのクラスはCGI.pmです。

DEPRECATED METHODS

これらのメソッドは唯一CGI::Session 3.xとの互換性のためだけに存在します。

close()

セッションを閉じます。代わりにflush()を使うことを、これは現在のclose()の呼び出しがまさしくしていることでもあり、推奨します。

Page Top

DISTRIBUTION

CGI::Sessionはdrivers、serializers、およびid generatorsといったいくつかのコンポーネントから成ります。このセクションでは利用できるもののリストを挙げます。

DRIVERS

以下のドライバは標準配布物に含まれています:

SERIALIZERS

ID GENERATORS

以下のIDジェネレータを使用できます:

Page Top

CREDITS

CGI::Sessionは、かの開発者の助けを得て現在の形に発展しました。このリストは厳密な順序に従ったものではありませんが、ある程度時系列のものです。詳細は、Changesファイルにあります。

Andy Lester
Brian King <mrbbking@mac.com>
Olivier Dragon <dragon@shadnet.shad.ca>
Adam Jacob <adam@sysadminsith.org>
Igor Plisco <igor@plisco.ru>
Mark Stosberg <markstos@cpan.org>
Matt LeBlanc <mleblanc@cpan.org>
Shawn Sorichetti

Page Top

COPYRIGHT

Copyright (C) 2001-2005 Sherzod Ruzmetov <sherzodr@cpan.org>. All rights reserved. This library is free software. You can modify and or distribute it under the same terms as Perl itself.

Page Top

PUBLIC CODE REPOSITORY

あなたは、最後のリリース以後に開発者が行ったことを、コードリポジトリからチェックアウトすることで見ることができます。 ここからSubversionリポジトリをブラウズできます:

 http://svn.cromedome.net/

あるいは、ここからsvnで直接チェックしてください:

 svn://svn.cromedome.net/CGI-Session

Page Top

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 で受け取ります。

Page Top

AUTHOR

Sherzod Ruzmetov <sherzodr@cpan.org>, http://author.handalak.com/

Mark Stosbergは4.0の開発においては副メンテナになりました。 markstos@cpan.org.

Page Top

SEE ALSO

Page Top

DOCUMENT TRANSLATION

Makio Tsukamoto, tsukamoto@gmail.com

和訳にあたっては、三浦真磁氏によるCGI::Session 3.11版の和訳を参考にさせていただきました。 これは、perldoc.jpでアクセスすることができます。

Page Top

This document is hosted by