NAME

SYNOPSIS

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

DESCRIPTION

WHAT IS 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.
    }

    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
        }

    sub remove {
        my ($self, $sid) = @_;
        # Remove storage associated with $sid. Return any true value indicating success,
        # or undef on failure.
    }

    sub traverse {
        my ($self, $coderef) = @_;
        # execute $coderef for each session id passing session id as the first and the only
        # argument
    }

    1;

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

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

METHODS

Following list describes every driver method, including its argument list and what step of session's life they will be invoked. Understanding this may help driver authors.

retrieve($self, $sid)

Called whenever a specific session is requested either via "CGI::Session->new()" or "CGI::Session->load()" syntax. Method should try to retrieve data associated with $sid and return it. In case no data could be retrieved for $sid 0 (zero) or "" should be returned. undef must be returned only to signal error. Error message should be set via set_error(), which can be inherited from CGI::Session::ErrorHandler.

Tip: set_error() always returns undef. Use it for your advantage.

store($self, $sid, $datastr)

Called whenever modified session data is to be stored back to disk. This happens whenever CGI::Session->flush() is called on modified session. Since CGI::Session->DESTROY() calls flush(), store() gets requested each time session object is to be terminated.

" store() " is called both to store new sessions and to update already stored sessions. It's driver author's job to figure out which operation needs to be performed.

$datastr, which is passed as the third argument to represents already serialized session data that needs to be saved.

store() can return any true value indicating success or undef on failure. Error message should be passed to set_error()

remove($self, $sid)

Called whenever session data is to be deleted, which is when CGI::Session->delete() is called. Should return any true value indicating success, undef on failure. Error message should be logged in set_error().

traverse($self, \&coderef)

Called only from within CGI::Session->find(). Job of traverse() is to call \&coderef for every single session stored in disk passing session's id as the first and only argument: "$coderef->( $sid )"

init($self)

Optional. Called whenever driver object is to be initialized, which happens only once during the lifecycle of CGI::Session object. Here you can do driver-wide initialization, such as to open connection to a database server.

DESTROY($self)

Optional. Perl automatically calls this method on objects just before they are to be terminated. This gives your driver chance to close any database connections or close any open file handles.

BACKWARDS COMPATIBILITY

For support information see CGI::Session

LICENSING