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.