=encoding utf8

=head1 NAME

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

=head1 SYNOPSIS

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

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

=head1 DESCRIPTION

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

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

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

=head1 METHODS

=head2 session

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

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

  - or -

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

=head2 session_config

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

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

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

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

=over 4

=item CGI_SESSION_OPTIONS

L<CGI::Session>コンストラクタに渡されるオプションのリストを与えることで、L<CGI::Session>オブジェクトの生成方法をカスタマイズすることができます。
パラメータの正しい書き方は、L<CGI::Session>のドキュメンテーションを見てください。

=item DEFAULT_EXPIRY

L<CGI::Session>では、セッションの有効期限を設定することができます。
DEFAULT_EXPIRYオプションを設定することで、新しく生成されたセッション全てにデフォルトの有効期限を設定することができます。
これはL<CGI::Session>の$session->expiryメソッドと同じ形式をとります。
これは新規のセッションに対してのみの設定で、保持されているセッションがリロードされた時は含まないことに注意してください。

=item COOKIE_PARAMS

これでセッションクッキーを作成するとき使用されるオプションをカスタマイズすることができます。
例えば、-expiry => '+24h'を渡すことで、Cookieの有効期限を与えることができます。
このクッキーの-nameおよび-valueパラメータは、明示的に-nameおよび-valueパラメータを上書きしなければ、自動的に追加されます。
パラメータの正しい書き方は、L<CGI::Session>のドキュメンテーションを見てください。

注意：-nameパラメタを渡してクッキーの名前を変更した時は、CGI::Session->name('new_cookie_name')を呼んでCGI::Sessionに通知するのを忘れないようにしてください。

=item SEND_COOKIE

trueの値が設定されると、新しいセッションが生成された時は、ヘッダー出力に自動的にクッキーヘッダーが追加されます。（このセッションモジュールは遅延ロードされるので、これはどこかで$self->sessionを呼び出してセッションオブジェクトを生成した時にだけ起こります）。
このオプションのデフォルトはtrueです。
これをfalseに設定すると、セッションクッキーは送られませんので、URLベースのセッションが良いと思うときは便利でしょう（この場合、セッションIDを渡すのはあなたの仕事になります）。

=back

以下の例は、どんなオプションがデフォルトで設定されるか（つまり、あなたが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,
                                 },
 );


=head2 session_cookie

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

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

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

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

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


=head2 session_delete

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

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


=head1 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;
  }


=head1 TODO

=over 4

=item *

要望があれば、将来、L<Apache::Session>や他の可能なセッションモジュールのサポートを追加するつもりです。

=item *

クッキーが確かにクライアントに受け入れられることを確認するテストを追加するかもしれません。

=item *

セッションが作成された直後に実行されるコールバックを受け入れます。

=back


=head1 SEE ALSO

L<CGI::Application>, L<CGI::Session>, perl(1)

=head1 AUTHOR

Cees Hek <ceeshek@gmail.com>

=head1 LICENSE

Copyright (C) 2004, 2005 Cees Hek <ceeshek@gmail.com>

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

=head1 DOCUMENT TRANSLATION

Makio Tsukamoto, tsukamoto@gmail.com

=cut