NAME
    CGI::Application::Plugin::Session - Plugin that adds session support to
    CGI::Application

VERSION
    version 1.05

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.

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

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: You can do the following to get both the cookie name and the
        internal name of the CGI::Session object to be changed:

          $self->session_config(
            CGI_SESSION_OPTIONS => [
              $driver,
              $self->query,
              \%driver_options,
              { name => 'new_cookie_name' } # change cookie and session name
            ]
          );

        Also, if '-name' parameter and 'name' of session don't match a
        warning will be emitted.

    SEND_COOKIE
        If set to a true value, the module will automatically add a cookie
        header to the outgoing headers if a new session is created (Since
        the session module is lazy loaded, this will only happen if you make
        a call to $self->session at some point to create the session
        object). 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');

  session_loaded
    This method will let you know if the session object has been loaded yet.
    In other words, it lets you know if $self->session has been called.

      sub cgiapp_postrun {
        my $self = shift;
        $self->session->flush if $self->session_loaded;;
      }

  session_recreate
    This method will delete the existing session, and create a brand new one
    for you with a new session ID. It copies over all existing parameters
    into the new session.

    This can be useful to protect against some login attacks when storing
    authentication tokens in the session. Very briefly, an attacker loads a
    page on your site and creates a session, then tries to trick a victim
    into loading this page with the same session ID (possibly by embedding
    it in a URL). Then if the victim follows the link and subsequently logs
    into their account, the attacker will have a valid session ID where the
    session is now logged in, and hence the attacker has access to the
    victims account.

      sub mylogin {
        my $self = shift;
        if ($newly_authenticated) {
            $self->session_recreate;
        }
      }

  session_delete
    This method will perform a more comprehensive clean-up of the session,
    calling both the CGI::Session delete() method, but also deleting the
    cookie from the client, if you are using cookies.

      sub logout {
        my $self = shift;
        $self->session_delete;
        # what now?  redirect user back to the homepage?
      }

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 <ceeshek@gmail.com>

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.

AUTHOR
    Cees Hek <ceeshek@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by Cees Hek.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

