--- name: "CGI::Session::Driver" section: "3pm" platform: "linux" package: "perl-cgi-session" version: "4.49-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/CGI::Session::Driver" --- # CGI::Session::Driver(3pm) CGI::Session driver specifications ## NAME CGI::Session::Driver - CGI::Session driver specifications ## 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. } 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; ``` 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 invoked 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. ## METHODS This section lists and describes all driver methods. All the driver methods will receive driver object ($self) as the first argument. Methods that pertain to an individual session (such as `retrieve()`, `store()` and `remove()`) will also receive session id ($sid) as the second argument. 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. ### 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. ## BACKWARDS COMPATIBILITY Version 4.0 of CGI::Session's driver specification is **NOT** backward compatible with the 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. For support information see CGI::Session ## LICENSING For support and licensing see CGI::Session.