NAME

CAM::Session - DBI and cookie CGI session state maintenance

LICENSE

Copyright 2005 Clotho Advanced Media, Inc., <cpan@clotho.com>

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

COMPARISON

CGI::Session is a better module than this one, but this one is a little easier to use. If you are starting from scratch, use CGI::Session. If you are using CAM::App, then we recommend this module for session management since CAM::App takes care of all of the details for you.

See README for more detail.

SYNOPSIS

  use CAM::Session;
  use DBI;
  my $dbh = DBI->connect(...);
  CAM::Session->setDBH($dbh);
  
  my $session = new CAM::Session();
  $session->printCookie();
  
  $session->set("username", $username);
  ...
  $session->get("username", $username);
  $session->delete("username");

To periodically clean up the session table, run a script like the following as a daily scheduled task:

  use CAM::Session;
  use DBI;
  my $dbh = DBI->connect(...) || die "no dbh";
  CAM::Session->setDBH($dbh);
  CAM::Session->setExpiration(24*60*60); # older than one day
  CAM::Session->clean();

DESCRIPTION

CAM::Session interacts with the CGI program, the database and the visitor's cookie to create a storage space for persistent data.

FUNCTIONS

new

new DBIHANDLE

Create a new session object, retrieving the session ID from the cookie, if any. If the database handle is not set here, it must have been set previously via the setDBH() class method.

DESTROY

Saves the session data on object destruction, if needed.

getID

getCookie

Return a cookie that indicates this session. Any arguments are passed to CGI::Cookie::new(). Use this, for example, with

    print CGI->header(-cookie => $session->getCookie);

printCookie

Outputs a cookie that indicates this session. Use this just before "print CGI->header()", for example.

getAll

Retrieve a hash of all of the session data.

get FIELDNAME

Retrieve a field from the session storage.

set FIELDNAME, VALUE, FIELDNAME, VALUE, ...

Record a field in the session storage. If autoSave is on (it is by default) this value is immediately recorded in the database.

delete FIELDNAME, FIELDNAME, ...

Remove one or more fields from the session storage. If autoSave is on (it is by default) this change is immediately recorded in the database.

clear

Calls delete() on every field in the session storage.

loadSessionData

Retrieve the session data from storage. This function is called by new() so it is only needed if you need to reload the data for some reason.

Returns a boolean indicating the success or failure of the load operation.

saveSessionData

Write the session data to permanent storage. This function is called by the set() method. so it is only needed if you have turned off the autoSave feature.

Returns a boolean indicating the success or failure of the save operation.

isNewSession

Returns true if this session was newly created (as opposed to a repeat visitor)

setDBH DBI_HANDLE

Set the global database handle for this package. Use like this:

  CAM::Session->setDBH($dbh);

setExpiration SECONDS

Set the duration for the session content. If the session is older than the specified time, a new session will be created. The default expiration is unlimited (set solely by the visitor's cookie expiration). This is a class method

Use like this:

  CAM::Session->setExpiration($seconds);

setTableName NAME

Set the name of the database table that is used for the session storage. This is a class method.

Use like this:

  CAM::Session->setTableName($name);

setCookieName NAME

Set the name of the cookie that is used for the recording the session. This is a class method.

Use like this:

  CAM::Session->setCookieName($name);

setup

setup DBIHANDLE, TABLENAME

Create a database table for storing sessions. This is not intended to be called often, if ever. This is a class method.

clean

clean DBIHANDLE, TABLENAME, SECONDS

Cleans out all records older than the specified number of seconds. This is a class method.

AUTHOR

Clotho Advanced Media Inc., cpan@clotho.com

Primary developer: Chris Dolan

SEE ALSO

CGI::Session, CAM::App