NAME

CGI::Application::Plugin::Session - CGI::ApplicationにCGI::Sessionのサポートを追加

SYNOPSIS

 use CGI::Application::Plugin::Session;

 my $language = $self->session->param('language');

Page Top

DESCRIPTION

CGI::Application::Plugin::Sessionはアプリケーションのどこからでもアクセス可能なCGI::Applicationモジュールのシームレスなセッションサポートを提供します。

このリクエストがセッションを必要としないときに、高価なファイルシステムまたはデータベースへのコールが行われないよう、遅延ローディングが使用されます。言い換えれば、Sessionオブジェクトはそれが実際に必要になるまで生成されません。また、リクエストの持続時間中は常に同じSessionオブジェクトを返すことで、Sessionオブジェクトはシングルトンとして振舞います。

このもジュールはできるだけ押し付けがましいところがなく、シンプルであることを目指しています。あなたのモジュールの継承ツリーには変更がまったく不要で、既存のアプリケーションへの追加が簡単になっています。モジュールをロードすることで、CGI::Applicationの名前空間に直接、2、3の新しいメソッドを追加するプラグインモジュールであると考えてください。

Page Top

METHODS

session

このメソッドは現在のCGI::Sessionオブジェクトを返します。最初のこのメソッドの呼び出しではCGI::Sessionオブジェクトが生成され、移行の呼び出しでは同じオブジェクトが返されます。事実上、これはリクエストの持続時間を通じてシングルトンのセッションオブジェクトの生成です。 CGI::SessionはセッションIDを含むCookieまたはパラメータを探し、見つからなければ新しいセッションを生成します。 sessionの最初の呼び出しの前にsession_configが呼ばれていなければ、おかしくなさそうな値をセッションオブジェクトを生成するためのデフォルト値として使用します。

  # セッションオブジェクトの取得
  my $session = $self->session;

  - or -

  # 直接セッションオブジェクトを使用
  my $language = $self->session->param('language');

session_config

このメソッドでCGI::Application::Plugin::Sessionモジュールの機能をカスタマイズすることができます。このメソッドの呼び出しが即セッションオブジェクトの生成を意味するわけではありません。セッションオブジェクトは最初の$self->sessionの呼び出しまで生成されません。この'遅延ローディング'は、このリクエストの処理中にセッションが必要とされないなら、高価なファイルシステムやデータベースへのコールを防ぐことができます。

session_configは、CGI::Applicationのcgiapp_init段階に配置することをお勧めします。このメソッドが既にセッションオブジェクトにアクセスがあったあとで呼ばれると、これはエラーメッセージを出してdieします。

このメソッドが全く呼ばれないと、妥当なデフォルト値のセットが使用されます（正確なデフォルト値は以下で定義されます）。

以下のパラメタを受け取ります:

CGI_SESSION_OPTIONS: CGI::Sessionオブジェクトの生成方法をカスタマイズすることができます。パラメータの正しい書き方は、CGI::Sessionのドキュメンテーションを見てください。
DEFAULT_EXPIRY: CGI::Sessionでは、セッションの有効期限を設定することができます。 DEFAULT_EXPIRYオプションを設定することで、新しく生成されたセッション全てにデフォルトの有効期限を設定することができます。これはCGI::Sessionの$session->expiryメソッドと同じ形式をとります。これは新規のセッションに対してのみの設定で、保持されているセッションがリロードされた時は含まないことに注意してください。
COOKIE_PARAMS: これでセッションクッキーを作成するとき使用されるオプションをカスタマイズすることができます。例えば、-expiry => '+24h'を渡すことで、Cookieの有効期限を与えることができます。このクッキーの-nameおよび-valueパラメータは、明示的に-nameおよび-valueパラメータを上書きしなければ、自動的に追加されます。パラメータの正しい書き方は、CGI::Sessionのドキュメンテーションを見てください。; 注意：-nameパラメタを渡してクッキーの名前を変更した時は、CGI::Session->name('new_cookie_name')を呼んでCGI::Sessionに通知するのを忘れないようにしてください。
SEND_COOKIE: trueの値が設定されると、新しいセッションが生成された時は、ヘッダー出力に自動的にクッキーヘッダーが追加されます。（このセッションモジュールは遅延ロードされるので、これはどこかで$self->sessionを呼び出してセッションオブジェクトを生成した時にだけ起こります）。このオプションのデフォルトはtrueです。これをfalseに設定すると、セッションクッキーは送られませんので、URLベースのセッションが良いと思うときは便利でしょう（この場合、セッションIDを渡すのはあなたの仕事になります）。

以下の例は、どんなオプションがデフォルトで設定されるか（つまり、あなたがsession_configを呼ばなかった場合に何が得られるか）を示します。

 $self->session_config(
          CGI_SESSION_OPTIONS => [ "driver:File", $self->query, {Directory=>'/tmp'} ],
          COOKIE_PARAMS       => {
                                   -path  => '/',
                                 },
          SEND_COOKIE         => 1,
 );

以下は、PostgreSQLドライバーを使用して、クッキーに有効期限とドメインを設定するカスタマイズ例です。

 $self->session_config(
          CGI_SESSION_OPTIONS => [ "driver:PostgreSQL;serializer:Storable", $self->query, {Handle=>$dbh} ],
          COOKIE_PARAMS       => {
                                   -domain  => 'mydomain.com',
                                   -expires => '+24h',
                                   -path    => '/',
                                   -secure  => 1,
                                 },
 );

session_cookie

このメソッドは、出力されるヘッダにCGI::SessionモジュールがアサインしたセッションIDを含むクッキーを追加します。

このメソッドはSEND_COOKIEがtrue（デフォルト）であれば最初に$self->sessionがアクセスされた時に自動的に呼び出されますので、ほとんどの場合これを手動で呼び出す必要はないでしょう。

これを手動で呼び出すことを選ぶと、セッションオブジェクトがまだ存在しなければ自動的に生成されることに注意してください。これはセッションが必要になったときにだけ生成/ロードされるという遅延ロードの効果を打ち消してしまいます。

このリクエストでセッションが使われなかったとしても強制的にクッキーヘッダーが送られるようにしたい時や、SEND_COOKIEをfalseに変更して自分でヘッダーを管理したいというときには便利かもしれません。

  # いくつかの独自のクッキーパラメータを含むクッキーヘッダーを
  # 強制的に使用。
  $self->session_cookie(-secure => 1, -expires => '+1w');

session_delete

このメソッドは、CGI::Sessionのdelete()メソッドを呼び、さらにクッキーを使用していれば、クライアントからもクッキーを削除して、より包括的にセッションのクリーンアップを行います。

  sub logout {
    my $self = shift;
    $self->session_delete;
    # 次に何を？ホームページに戻るようにユーザーをリダイレクト？
  }

Page Top

EXAMPLE

CGI::Applicationモジュールで:

  # init段階の中で一度だけセッションを設定
  sub cgiapp_init {
    my $self = shift;

    # セッションの設定
    $self->session_config(
       CGI_SESSION_OPTIONS => [ "driver:PostgreSQL;serializer:Storable", $self->query, {Handle=>$self->dbh} ],
       DEFAULT_EXPIRY      => '+1w',
       COOKIE_PARAMS       => {
                                -expires => '+24h',
                                -path    => '/',
                              },
       SEND_COOKIE         => 1,
    );

  sub cgiapp_prerun {
    my $self = shift;

    # 必要であれば、ログインへリダイレクト
    unless ( $self->session->param('~logged-in') ) {
      $self->prerun_mode('login');
    }
      }

  sub my_runmode {
    my $self = shift;

    # テンプレートをロード
    my $template = $self->load_tmpl('my_runmode.tmpl');

    # セッションのパラメータを全てテンプレートに追加
    $template->param($self->session->param_hashref());

    # テンプレートのoutputを返す
    return $template->output;
      }

Page Top

TODO

要望があれば、将来、Apache::Sessionや他の可能なセッションモジュールのサポートを追加するつもりです。
クッキーが確かにクライアントに受け入れられることを確認するテストを追加するかもしれません。
セッションが作成された直後に実行されるコールバックを受け入れます。

Page Top

AUTHOR

Cees Hek <ceeshek@gmail.com>

Page Top

LICENSE

This library is free software. You can modify and or distribute it under the same terms as Perl itself.

Page Top

DOCUMENT TRANSLATION

Makio Tsukamoto, tsukamoto@gmail.com

Page Top