NAME
   CGI::Application::Plugin::Session - Add CGI::Session support to
   CGI::Application

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

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

DESCRIPTION
   CGI::Application::Plugin::Session seamlessly adds session support to
   your CGI::Application modules by providing a CGI::Session object that is
   accessible from anywhere in the application.

   Lazy loading is used to prevent expensive file system or database calls
   from being made if the session is not needed during this request. In
   other words, the Session object is not created until it is actually
   needed. Also, the Session object will act as a singleton by always
   returning the same Session object for the duration of the request.

   This module aims to be as simple and non obtrusive as possible. By not
   requiring any changes to the inheritance tree of your modules, it can be
   easily added to existing applications. Think of it as a plugin module
   that adds a couple of new methods directly into the CGI::Application
   namespace simply by loading the module.

METHODS
 session
   This method will return the current CGI::Session object. The
   CGI::Session object is created on the first call to this method, and any
   subsequent calls will return the same object. This effectively creates a
   singleton session object for the duration of the request. CGI::Session
   will look for a cookie or param containing the session ID, and create a
   new session if none is found. If "session_config" has not been called
   before the first call to "session", then it will choose some sane
   defaults to create the session object.

     # retrieve the session object
     my $session = $self->session;

     - or -

     # use the session object directly
     my $language = $self->session->param('language');

 session_config
   This method can be used to customize the functionality of the
   CGI::Application::Plugin::Session module. Calling this method does not
   mean that a new session object will be immediately created. The session
   object will not be created until the first call to $self->session. This
   'lazy loading' can prevent expensive file system or database calls from
   being made if the session is not needed during this request.

   The recommended place to call "session_config" is in the "cgiapp_init"
   stage of CGI::Application. If this method is called after the session
   object has already been accessed, then it will die with an error
   message.

   If this method is not called at all then a reasonable set of defaults
   will be used (the exact default values are defined below).

   The following parameters are accepted:

   CGI_SESSION_OPTIONS
       This allows you to customize how the CGI::Session object is created
       by providing a list of options that will be passed to the
       CGI::Session constructor. Please see the documentation for
       CGI::Session for the exact syntax of the parameters.

   DEFAULT_EXPIRY
       CGI::Session Allows you to set an expiry time for the session. You
       can set the DEFAULT_EXPIRY option to have a default expiry time set
       for all newly created sessions. It takes the same format as the
       $session->expiry method of CGI::Session takes. Note that it is only
       set for new session, not when a session is reloaded from the store.

   COOKIE_PARAMS
       This allows you to customize the options that are used when creating
       the session cookie. For example you could provide an expiry time for
       the cookie by passing -expiry => '+24h'. The -name and -value
       parameters for the cookie will be added automatically unless you
       specifically override them by providing -name and/or -value
       parameters. See the CGI::Cookie docs for the exact syntax of the
       parameters.

       NOTE: If you change the name of the cookie by passing a -name
       parameter, remember to notify CGI::Session of the change by calling
       CGI::Session->name('new_cookie_name').

   SEND_COOKIE
       If set to a true value, the module will automatically add a cookie
       header to the outgoing headers. This option defaults to true. If it
       is set to false, then no session cookies will be sent, which may be
       useful if you prefer URL based sessions (it is up to you to pass the
       session ID in this case).

   The following example shows what options are set by default (ie this is
   what you would get if you do not call session_config).

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

   Here is a more customized example that uses the PostgreSQL driver and
   sets an expiry and domain on the cookie.

    $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
   This method will add a cookie to the outgoing headers containing the
   session ID that was assigned by the CGI::Session module.

   This method is called automatically the first time $self->session is
   accessed if SEND_COOKIE was set true, which is the default, so it will
   most likely never need to be called manually.

   NOTE that if you do choose to call it manually that a session object
   will automatically be created if it doesn't already exist. This removes
   the lazy loading benefits of the plugin where a session is only
   created/loaded when it is required.

   It could be useful if you want to force the cookie header to be sent out
   even if the session is not used on this request, or if you want to
   manage the headers yourself by turning SEND_COOKIE to false.

     # Force the cookie header to be sent including some
     # custom cookie parameters
     $self->session_cookie(-secure => 1, -expires => '+1w');

EXAMPLE
   In a CGI::Application module:

     # configure the session once during the init stage
     sub cgiapp_init {
       my $self = shift;

       # Configure the session
       $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;

       # Redirect to login, if necessary
       unless ( $self->session->param('~logged-in') ) {
         $self->prerun_mode('login');
       }
     }

     sub my_runmode {
       my $self = shift;

       # Load the template
       my $template = $self->load_tmpl('my_runmode.tmpl');

       # Add all the session parameters to the template
       $template->param($self->session->param_hashref());

       # return the template output
       return $template->output;
     }

TODO
   *   I am considering adding support for other session modules in the
       future, like Apache::Session and possibly others if there is a
       demand.

   *   Possibly add some tests to make sure cookies are accepted by the
       client.

   *   Allow a callback to be executed right after a session has been
       created

SEE ALSO
   CGI::Application, CGI::Session, perl(1)

AUTHOR
   Cees Hek <[email protected]>

LICENSE
   Copyright (C) 2004, 2005 Cees Hek <[email protected]>

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.