{
    "mode": "perldoc",
    "parameter": "CGI::Session::Driver",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/CGI%3A%3ASession%3A%3ADriver/json",
    "generated": "2026-06-08T12:40:51Z",
    "synopsis": "require CGI::Session::Driver;\n@ISA = qw( CGI::Session::Driver );",
    "sections": {
        "NAME": {
            "content": "CGI::Session::Driver - CGI::Session driver specifications\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "require CGI::Session::Driver;\n@ISA = qw( CGI::Session::Driver );\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "CGI::Session::Driver is a base class for all CGI::Session's native drivers. It also documents\ndriver specifications for those willing to write drivers for different databases not currently\nsupported by CGI::Session.\n",
            "subsections": []
        },
        "WHAT IS A DRIVER": {
            "content": "Driver is a piece of code that helps CGI::Session library to talk to specific database engines,\nor storage mechanisms. To be more precise, driver is a .pm file that inherits from\nCGI::Session::Driver and defines retrieve(), store() and remove() methods.\n\nBLUEPRINT\nThe best way of learning the specs is to look at a blueprint of a driver:\n\npackage CGI::Session::Driver::yourdrivername;\nuse strict;\nuse base qw( CGI::Session::Driver CGI::Session::ErrorHandler );\n\nsub init {\nmy ($self) = @;\n# optional\n}\n\nsub DESTROY {\nmy ($self) = @;\n# optional\n}\n\nsub store {\nmy ($self, $sid, $datastr) = @;\n# Store $datastr, which is an already serialized string of data.\n}\n\nsub retrieve {\nmy ($self, $sid) = @;\n# Return $datastr, which was previously stored using above store() method.\n# Return $datastr if $sid was found. Return 0 or \"\" if $sid doesn't exist\n}\n\nsub remove {\nmy ($self, $sid) = @;\n# Remove storage associated with $sid. Return any true value indicating success,\n# or undef on failure.\n}\n\nsub traverse {\nmy ($self, $coderef) = @;\n# execute $coderef for each session id passing session id as the first and the only\n# argument\n}\n\n1;\n\nAll the attributes passed as the second argument to CGI::Session's new() or load() methods will\nautomatically be made driver's object attributes. For example, if session object was initialized\nas following:\n\n$s = CGI::Session->new(\"driver:yourdrivername\", undef, {Directory=>'/tmp/sessions'});\n\nYou can access value of 'Directory' from within your driver like so:\n\nsub store {\nmy ($self, $sid, $datastr) = @;\nmy $dir = $self->{Directory};   # <-- in this example will be '/tmp/sessions'\n}\n\nOptionally, you can define \"init()\" method within your driver to do driver specific global\ninitialization. \"init()\" method will be invoked only once during the lifecycle of your driver,\nwhich is the same as the lifecycle of a session object.\n\nFor examples of \"init()\" look into the source code of native CGI::Session drivers.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "This section lists and describes all driver methods. All the driver methods will receive driver\nobject ($self) as the first argument. Methods that pertain to an individual session (such as\n\"retrieve()\", \"store()\" and \"remove()\") will also receive session id ($sid) as the second\nargument.\n\nFollowing list describes every driver method, including its argument list and what step of\nsession's life they will be invoked. Understanding this may help driver authors.\n",
            "subsections": [
                {
                    "name": "retrieve",
                    "content": "Called whenever a specific session is requested either via \"CGI::Session->new()\" or\n\"CGI::Session->load()\" syntax. Method should try to retrieve data associated with $sid and\nreturn it. In case no data could be retrieved for $sid 0 (zero) or \"\" should be returned.\nundef must be returned only to signal error. Error message should be set via seterror(),\nwhich can be inherited from CGI::Session::ErrorHandler.\n\nTip: seterror() always returns undef. Use it for your advantage.\n"
                },
                {
                    "name": "store",
                    "content": "Called whenever modified session data is to be stored back to disk. This happens whenever\nCGI::Session->flush() is called on modified session. Since CGI::Session->DESTROY() calls\nflush(), store() gets requested each time session object is to be terminated.\n\n\" store() \" is called both to store new sessions and to update already stored sessions. It's\ndriver author's job to figure out which operation needs to be performed.\n\n$datastr, which is passed as the third argument to represents already serialized session\ndata that needs to be saved.\n\nstore() can return any true value indicating success or undef on failure. Error message\nshould be passed to seterror()\n"
                },
                {
                    "name": "remove",
                    "content": "Called whenever session data is to be deleted, which is when CGI::Session->delete() is\ncalled. Should return any true value indicating success, undef on failure. Error message\nshould be logged in seterror().\n"
                },
                {
                    "name": "traverse",
                    "content": "Called only from within CGI::Session->find(). Job of traverse() is to call \\&coderef for\nevery single session stored in disk passing session's id as the first and only argument:\n\"$coderef->( $sid )\"\n"
                },
                {
                    "name": "init",
                    "content": "Optional. Called whenever driver object is to be initialized, which happens only once during\nthe lifecycle of CGI::Session object. Here you can do driver-wide initialization, such as to\nopen connection to a database server.\n\nDESTROY($self)\nOptional. Perl automatically calls this method on objects just before they are to be\nterminated. This gives your driver chance to close any database connections or close any\nopen file handles.\n\nNOTES\n*   All driver .pm files must be lowercase!\n\n*   DBI-related drivers are better off using CGI::Session::Driver::DBI as base, but don't have\nto.\n"
                }
            ]
        },
        "BACKWARDS COMPATIBILITY": {
            "content": "Version 4.0 of CGI::Session's driver specification is NOT backward compatible with the previous\nspecification. If you already have a driver developed to work with the previous version you're\nhighly encouraged to upgrade your driver code to make it compatible with the current version.\nFortunately, current driver specs are a lot easier to adapt to.\n\nFor support information see CGI::Session\n",
            "subsections": []
        },
        "LICENSING": {
            "content": "For support and licensing see CGI::Session.\n",
            "subsections": []
        }
    },
    "summary": "CGI::Session::Driver - CGI::Session driver specifications",
    "flags": [],
    "examples": [],
    "see_also": []
}