NAME

PAB3::Session - PAB3 session handler

SYNOPSIS

with PAB3::CGI module

  use PAB3::CGI;
  use PAB3::Session;
  
  &PAB3::CGI::init();
  &PAB3::Session::start();

without PAB3::CGI module

  use PAB3::Session;
  
  &PAB3::Session::start(
      'id' => 'mysessionid'
  );

DESCRIPTION

PAB3::Session provides an interace to Session Handling Functions in PAB3.

EXAMPLE

  use PAB3::CGI;
  use PAB3::Session;
  use PAB3::Utils;
  
  &PAB3::CGI::init();
  &PAB3::Session::start();
  
  if( ! $_SESSION{'time_start'} ) {
      $_SESSION{'hits'} = 1;
      $_SESSION{'time_start'} = time;
      print "you are first time here.";
  }
  else {
      $_SESSION{'hits'} ++;
      print
          "you are here since ",
          &PAB3::Utils::strftime(
              '%h hours, %m min, %s sec',
              time - $_SESSION{'time_start'}
          )
      ;
  }

METHODS

start ( [%ARG] )

start() creates a session or resumes the current one based on the current session id that's being passed via a request, such as GET, POST, or a cookie.

Available arguments are:

  save_path       => path to save the session files
                     default is '/tmp'
  name            => name of the session id in %_REQUEST or %_COOKIE
                     default is PABSESSID
  id              => id of session; needs to be defined if PAB3::CGI is not used
  use_cookies     => store session id in a cookie, default is TRUE
  use_only_cookie => use cookies only, default is FALSE
  cookie_path     => path on the server in which the cookie will be
                     available on, default is ''
  cookie_domain   => defines the domain that the cookie is available
                     default is ''
  cookie_lifetime => defines the time the cookie expires,
                     default is 0
  cookie_secure   => indicates that the cookie should only be
                     transmitted over a secure HTTPS connection,
                     default is FALSE
  gc_max_lifetime => specifies the number of seconds after which data
                     will be seen as 'garbage' and cleaned up
                     default 1440 (24 min)
  gc_probality    => gc_probability in conjunction with gc_divisor
                     is used to manage probability that the gc
                     (garbage collection) routine is started.
                     default is 1.
  gc_divisor      => gc_divisor coupled with gc_probability defines
                     the probability that the gc (garbage collection)
                     process is started on every session initialization.
                     The probability is calculated by using
                     gc_probability/gc_divisor, e.g. 1/100 means there
                     is a 1% chance that the GC process starts on each
                     request. gc_divisor defaults to 100.

Example:

  &PAB3::Session::start(
      'save_path'    => '/path/to/save/sessions/',
  );

write ()

Store session data.

write() is called internally at the END block or inside ModPerl as cleanup callback at the end of each request. If you use PAB3::CGI, it will be registered as callback by PAB3::CGI::cleanup_register. In other environments, like PerlEx or FastCGI, that do not support cleanup mechanism you need to call it by yourself.

destroy ()

Destroys all data registered to a session.

gc ()

Runs the session garbage collector.

VARIABLES

$SID

Contains the session id

%_SESSION

Store your session data in the %_SESSION hash.

EXPORTS

By default the variables $SID and %_SESSION are exported. To export function also use the export tag ':default'. Exported functions get the prefix "session_".

AUTHORS

Christian Mueller <christian_at_hbr1.com>

COPYRIGHT

The PAB3::Session module is free software. You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.