CGI::Se...:Driver(3)

💾 CGI::Session::Driver(3) — the driver specs page, bestie edition

okay so real talk: you're reading the CGI::Session::Driver page from the User Contributed Perl Documentation, and it's literally the blueprint for how every CGI::Session driver is supposed to behave. it's giving "spec sheet but make it cute". let's get into it 💅

---

✨ NAME ✨

CGI::Session::Driver — the driver specifications for CGI::Session, no cap 🎀

🌸 SYNOPSIS 🌸

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

that's it. that's the whole synopsis. short and iconic 💖

🦋 DESCRIPTION 🦋

CGI::Session::Driver is the base class for all of CGI::Session's native drivers. full stop, main character energy 👑

but it's also doing double duty: it documents the driver specs for anyone who wants to write drivers for different databases that CGI::Session doesn't currently support. so if you're out here wanting your fave storage engine to be part of the family, this page is for you 🫶

🔥 WHAT IS A DRIVER 🔥

a driver is a piece of code that helps the CGI::Session library talk to specific database engines, or storage mechanisms. to be more precise (and we love precision), a driver is a .pm file that inherits from CGI::Session::Driver and defines the retrieve(), store() and remove() methods. that's the whole vibe check 🧚

🎀 BLUEPRINT 🎀

honestly the best way of learning the specs is to just look at a blueprint of a driver. here it is in all its glory:

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;

so cute, so structured, we stan 💜

here's the tea though: all the attributes passed as the second argument to CGI::Session's new() or load() methods will automatically be made driver's object attributes. automatic. effortless. slay ✨

for example, if the session object was initialized as following:

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

you can access the 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'
}

see how easy that was? obsessed 😭

optionally, you can define an init() method within your driver to do driver specific global initialization. init() will be invoked only once during the lifecycle of your driver — which is the same as the lifecycle of a session object. one and done, periodt 💅

for examples of init() look into the source code of native CGI::Session drivers. go read the source, bestie, it's good for you 📚

---

👑 METHODS 👑

this section lists and describes all driver methods. heads up: all the driver methods will receive the driver object ($self) as the first argument. methods that pertain to an individual session (such as retrieve(), store() and remove()) will also receive the session id ($sid) as the second argument. so you always know who's talking and who they're talking about 🫶

the following list describes every driver method, including its argument list and what step of the session's life they will be invoked at. understanding this may help driver authors. iykyk 🌈

• retrieve($self, $sid) — called whenever a specific session is requested, either via "CGI::Session->new()" or "CGI::Session->load()" syntax. the 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. the 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. that's the hack, bestie 🧠✨

• 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 a modified session. and since CGI::Session->DESTROY() calls flush(), store() gets requested each time the session object is to be terminated. every single time. no escape 😭

store() is called both to store new sessions and to update already stored sessions. it's the driver author's job to figure out which operation needs to be performed. detective work, honestly 🔍

$datastr, which is passed as the third argument, represents already serialized session data that needs to be saved. don't serialize it again, it's already done 💖

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(). bye bye session, you had a good run 👋💀
• traverse($self, \&coderef) — called only from within CGI::Session->find(). the job of traverse() is to call \&coderef for every single session stored in disk, passing the session's id as the first and only argument: $coderef->( $sid ). one argument. that's it. don't overthink it 🦋
• init($self) — optional. called whenever the driver object is to be initialized, which happens only once during the lifecycle of the CGI::Session object. here you can do driver-wide initialization, such as to open a connection to a database server. big "setting up the group chat" energy 💬
• DESTROY($self) — optional. Perl automatically calls this method on objects just before they are to be terminated. this gives your driver a chance to close any database connections or close any open file handles. cleanup era 🧹✨

⭐ NOTES ⭐

• all driver .pm files must be lowercase! lowercase. lowercase. LOWERCASE. i'm not kidding 🚨
• DBI-related drivers are better off using CGI::Session::Driver::DBI as base, but don't have to. it's a suggestion, not a rule, live your truth 💅

---

🌈 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 (and this is the good news), current driver specs are a lot easier to adapt to. glow-up complete 🦋

for support information see CGI::Session.

💜 LICENSING 💜

for support and licensing see CGI::Session.

---

okay that's the whole page, you're officially a driver spec expert 🎓✨ this was CGI::Session::Driver(3) from the User Contributed Perl Documentation, perl v5.42.2, dated 2026-07-28 — go forth and write iconic drivers, bestie 🫶🎀💖