/ 
CGI-Lazy-1.08
River stage zero No dependents
/ CGI::Lazy::Session

LEGAL

#===========================================================================

Copyright (C) 2008 by Nik Ogura. All rights reserved.

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

Bug reports and comments to nik.ogura@gmail.com.

#===========================================================================

NAME

CGI::Lazy::Session

SYNOPSIS

use CGI::Lazy;

our $q = CGI::Lazy->new({

				tmplDir 	=> "/templates",

				jsDir		=>  "/js",

				plugins 	=> {

					mod_perl => {

						PerlHandler 	=> "ModPerl::Registry",

						saveOnCleanup	=> 1,

					},

					ajax	=>  1,

					dbh 	=> {

						dbDatasource 	=> "dbi:mysql:somedatabase:localhost",

						dbUser 		=> "dbuser",

						dbPasswd 	=> "letmein",

						dbArgs 		=> {"RaiseError" => 1},

					},

					session	=> {

						sessionTable	=> 'SessionData',

						sessionCookie	=> 'frobnostication',

						saveOnDestroy	=> 1,

						expires		=> '+15m',

					},

				},

			});

DESCRIPTION

CGI::Lazy::Session is for maintaining state between requests. It's enabled in the config file or config hash. Once it's enabled, any calls to $q->header will automatically include a cookie that will be used to retrieve session data.

To function, the session needs the following arguments:

sessionTable	=> name of table to store data in

sessionCookie	=> name of the cookie

expires		=> how long a session can sit idle before expiring

By default, sessions are automatically saved when the Lazy object is destroyed, or in the cleanup stage of the request cycle for mod_perl apps. Both mechanisms are enabled by default. (call me paranoid) Should you wish to disable the save on destroy: saveOnDestroy => 0

If the key is missing from the config, it's as if it was set to 1. You will have to set it to 0 to disable this functionality. Same goes for the mod_perl save. See CGI::Lazy::ModPerl for details

Session data is stored in the db as JSON formatted text at present. Fancier storage (for binary data and such) will have to wait for subsequent releases.

The session table must have the following fields at a bare minimum:

sessionID	not null, primary key, varchar(25)

data		text (mysql) large storage (clob in oracle)

METHODS

cookiemonster

returns reference to CGI::Lazy::CookieMonster object

config

returns reference to the config object

data ()

returns reference to the CGI::Lazy::Session::Data object

db ()

returns reference to CGI::Lazy::DB object

expired ()

returns 1 if session has been expired, either explicitly or by timeout

expires ()

Returns time in epoch when session expires.

getData ()

Called internally on CGI::Lazy::Session::Data creation. Queries db for session data

id ()

returns session id

new ( sessionID )

Constructor. Creates new session.

sessionID

valid session ID string

open ( q sessionID )

Opens a previous session, or creates a new one. If it's opening an existing session, it will check to see that the session given has not expired. If it has, it will create a new one.

q

CGI::Lazy object

sessionID

valid session ID

parseExpiry ( time)

Parses expiration string from session plugin and returns time in epoch when session should expire.

Currently only can parse seconds, minutes, hours and days. Is more really necessary?

time

Epoch returned from time() function

q ()

Returns reference to CGI::Lazy object

sessionCookie ()

Returns name of session cookie specified by session plugin

sessionID ()

Returns session id

sessionTable ()

Returns session table name specified by session plugin

save ()

Saves session variable to database

terminate ()

Terminates the session. Session data object will have the 'terminated' flag set.