# perldoc > CGI::Session::Driver

---
type: CommandReference
command: CGI::Session::Driver
mode: perldoc
section: 
source: perldoc
---

## Quick Reference

- `use base qw( CGI::Session::Driver );` — inherit from base class
- `sub retrieve { my ($self, $sid) = @_; ... }` — fetch session data for `$sid`; return `0` or `""` if not found, `undef` on error
- `sub store { my ($self, $sid, $datastr) = @_; ... }` — save serialized data for `$sid`; return true on success, `undef` on failure
- `sub remove { my ($self, $sid) = @_; ... }` — delete session data; return true on success, `undef` on failure
- `sub traverse { my ($self, $coderef) = @_; ... }` — call `$coderef->($sid)` for every stored session
- `sub init { my ($self) = @_; }` — optional global initialization (called once per session object)
- `sub DESTROY { my ($self) = @_; }` — optional cleanup (close connections, etc.)

## Name

[CGI::Session::Driver](http://localhost/phpMan.php/perldoc/CGI%3A%3ASession%3A%3ADriver/markdown) — base class and specification for [CGI::Session](http://localhost/phpMan.php/perldoc/CGI%3A%3ASession/markdown) drivers.

## Synopsis

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

sub init { ... }      # optional
sub DESTROY { ... }   # optional
sub store { ... }
sub retrieve { ... }
sub remove { ... }
sub traverse { ... }
1;
## Methods

All methods receive the driver object (`$self`) as first argument. Session methods also receive `$sid` second.

- `retrieve($self, $sid)` — Fetch data for `$sid`. Return serialized string on success, `0` or `""` if not found, `undef` on error (use `set_error()` to signal).
- `store($self, $sid, $datastr)` — Save `$datastr` (already serialized) for `$sid`. Called for new and updated sessions. Return true on success, `undef` on failure.
- `remove($self, $sid)` — Delete session data. Return true on success, `undef` on failure.
- `traverse($self, $coderef)` — Call `$coderef->($sid)` for every stored session. Used by `CGI::Session->find()`.
- `init($self)` — Optional. Called once per session object lifecycle. Use for driver-wide initialization (e.g., open database connection).
- `DESTROY($self)` — Optional. Called automatically when driver object is destroyed. Use for cleanup (close connections, file handles).

## Examples

Blueprint for a custom driver:

perl
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 only argument
}

1;
Driver attributes passed to `CGI::Session->new()` or `->load()` become object attributes automatically:

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

- [CGI::Session](http://localhost/phpMan.php/perldoc/CGI%3A%3ASession/markdown) — session management
- [CGI::Session::ErrorHandler](http://localhost/phpMan.php/perldoc/CGI%3A%3ASession%3A%3AErrorHandler/markdown) — error handling base
- [CGI::Session::Driver::DBI](http://localhost/phpMan.php/perldoc/CGI%3A%3ASession%3A%3ADriver%3A%3ADBI/markdown) — DBI-specific base for database drivers

## Notes

- Driver `.pm` files must be lowercase.
- DBI-related drivers are better off using `CGI::Session::Driver::DBI` as base.
- Version 4.0 driver specification is NOT backward compatible with previous versions.