NAME

CGI::Session::Driver - CGI::Session driver specifications

WARNING

Version 2.01 of CGI::Session's driver specification is NOT backward compatible with previous specification. If you already have a driver developed to work with the previous version you're highly encouraged to upgrade your driver code to make it compatible with the current version. Fortunately, current driver specs are a lot easier to adapt to.

If you need any help converting your driver to meet current specs, send me an e-mail. For support information see CGI::Session

SYNOPSIS

require CGI::Session::Driver;
@ISA = qw( CGI::Session::Driver );

DESCRIPTION

CGI::Session::Driver is a base class for all CGI::Session's native drivers. It also documents driver specifications for those willing to write drivers for different databases not currently supported by CGI::Session.

WHAT IS A DRIVER

Driver is a piece of code that helps CGI::Session library to talk to specific database engines, or storage mechanisms. To be more precise, driver is a .pm file that inherits from CGI::Session::Driver and defines retrieve(), store() and remove() methods.

BLUEPRINT

The best way of learning the specs is to look at a blueprint of a driver:

package CGI::Session::Driver::your_driver_name;
use strict;
use base qw( CGI::Session::Driver CGI::Session::ErrorHandler );

sub init {
    my ($self) = @_;
    # optional
}

sub DESTROY {
    my ($self) = @_;
    # optional
}

sub store {
    my ($self, $sid, $datastr) = @_;
    # Store $datastr, which is an already serialized string of data.
    # Return any true value on success, undef failure.
    # Set error message using $self->set_error()
}

sub retrieve {
    my ($self, $sid) = @_;
    # Return $datastr, which was previously stored using above store() method.
    # Return $datastr if $sid was found. Return 0 or "" if $sid doesn't exist
    # in the datastore. Return undef to indicate failure. Set error message
    # using $self->set_error()
}

sub remove {
    my ($self, $sid) = @_;
    # Remove storage associated for $sid. Return any true value indicating success,
    # or undef on failure. Set error message using $self->set_error()
}

All the attributes passed as the second argument to CGI::Session's new() or load() methods will automatically be made driver's object attributes. For example, if session object was initialized as following:

$s = CGI::Session->new("driver:your_driver_name", undef, {Directory=>'/tmp/sessions'});

You can access value of 'Directory' from within your driver like so:

sub store {
    my ($self, $sid, $datastr) = @_;
    my $dir = $self->{Directory};   # <-- in this example will be '/tmp/sessions'
}

Optionally, you can define init() method within your driver to do driver specific global initialization. init() method will be envoked only once during the lifecycle of your driver, which is the same as the lifecycle of a session object.

For examples of init() look into the source code of native CGI::Session drivers.

NOTES

• All driver .pm files must be lowercase!

• DBI-related drivers are better off using CGI::Session::Driver::DBI as base, but don't have to.

LICENSING

For support and licensing see CGI::Session.