view release on metacpan or  search on metacpan

README  view on Meta::CPAN

 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.