1CGI::Session::Driver(3)User Contributed Perl DocumentatioCnGI::Session::Driver(3)
2
3
4

NAME

6       CGI::Session::Driver - CGI::Session driver specifications
7

SYNOPSIS

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

DESCRIPTION

13       CGI::Session::Driver is a base class for all CGI::Session's native
14       drivers. It also documents driver specifications for those willing to
15       write drivers for different databases not currently supported by
16       CGI::Session.
17

WHAT IS A DRIVER

19       Driver is a piece of code that helps CGI::Session library to talk to
20       specific database engines, or storage mechanisms. To be more precise,
21       driver is a .pm file that inherits from CGI::Session::Driver and
22       defines retrieve(), store() and remove() methods.
23
24   BLUEPRINT
25       The best way of learning the specs is to look at a blueprint of a
26       driver:
27
28           package CGI::Session::Driver::your_driver_name;
29           use strict;
30           use base qw( CGI::Session::Driver CGI::Session::ErrorHandler );
31
32           sub init {
33               my ($self) = @_;
34               # optional
35           }
36
37           sub DESTROY {
38               my ($self) = @_;
39               # optional
40           }
41
42           sub store {
43               my ($self, $sid, $datastr) = @_;
44               # Store $datastr, which is an already serialized string of data.
45           }
46
47           sub retrieve {
48               my ($self, $sid) = @_;
49               # Return $datastr, which was previously stored using above store() method.
50               # Return $datastr if $sid was found. Return 0 or "" if $sid doesn't exist
51               }
52
53           sub remove {
54               my ($self, $sid) = @_;
55               # Remove storage associated with $sid. Return any true value indicating success,
56               # or undef on failure.
57           }
58
59           sub traverse {
60               my ($self, $coderef) = @_;
61               # execute $coderef for each session id passing session id as the first and the only
62               # argument
63           }
64
65           1;
66
67       All the attributes passed as the second argument to CGI::Session's
68       new() or load() methods will automatically be made driver's object
69       attributes. For example, if session object was initialized as
70       following:
71
72           $s = CGI::Session->new("driver:your_driver_name", undef, {Directory=>'/tmp/sessions'});
73
74       You can access value of 'Directory' from within your driver like so:
75
76           sub store {
77               my ($self, $sid, $datastr) = @_;
78               my $dir = $self->{Directory};   # <-- in this example will be '/tmp/sessions'
79           }
80
81       Optionally, you can define "init()" method within your driver to do
82       driver specific global initialization. "init()" method will be invoked
83       only once during the lifecycle of your driver, which is the same as the
84       lifecycle of a session object.
85
86       For examples of "init()" look into the source code of native
87       CGI::Session drivers.
88

METHODS

90       This section lists and describes all driver methods. All the driver
91       methods will receive driver object ($self) as the first argument.
92       Methods that pertain to an individual session (such as "retrieve()",
93       "store()" and "remove()") will also receive session id ($sid) as the
94       second argument.
95
96       Following list describes every driver method, including its argument
97       list and what step of session's life they will be invoked.
98       Understanding this may help driver authors.
99
100       retrieve($self, $sid)
101           Called whenever a specific session is requested either via
102           "CGI::Session->new()" or "CGI::Session->load()" syntax. Method
103           should try to retrieve data associated with  $sid  and return it.
104           In case no data could be retrieved for  $sid  0 (zero) or "" should
105           be returned. undef must be returned only to signal error. Error
106           message should be set via set_error(), which can be inherited from
107           CGI::Session::ErrorHandler.
108
109           Tip: set_error() always returns undef. Use it for your advantage.
110
111       store($self, $sid, $datastr)
112           Called whenever modified session data is to be stored back to disk.
113           This happens whenever CGI::Session->flush() is called on modified
114           session. Since CGI::Session->DESTROY() calls flush(), store() gets
115           requested each time session object is to be terminated.
116
117           " store() " is called both to store new sessions and to update
118           already stored sessions. It's driver author's job to figure out
119           which operation needs to be performed.
120
121           $datastr, which is passed as the third argument to represents
122           already serialized session data that needs to be saved.
123
124           store() can return any true value indicating success or undef on
125           failure. Error message should be passed to set_error()
126
127       remove($self, $sid)
128           Called whenever session data is to be deleted, which is when
129           CGI::Session->delete() is called. Should return any true value
130           indicating success, undef on failure. Error message should be
131           logged in set_error().
132
133       traverse($self, \&coderef)
134           Called only from within CGI::Session->find(). Job of traverse() is
135           to call \&coderef for every single session stored in disk passing
136           session's id as the first and only argument: "$coderef->( $sid )"
137
138       init($self)
139           Optional. Called whenever driver object is to be initialized, which
140           happens only once during the lifecycle of CGI::Session object. Here
141           you can do driver-wide initialization, such as to open connection
142           to a database server.
143
144       DESTROY($self)
145           Optional. Perl automatically calls this method on objects just
146           before they are to be terminated. This gives your driver chance to
147           close any database connections or close any open file handles.
148
149   NOTES
150       ·   All driver .pm files must be lowercase!
151
152       ·   DBI-related drivers are better off using CGI::Session::Driver::DBI
153           as base, but don't have to.
154

BACKWARDS COMPATIBILITY

156       Version 4.0 of CGI::Session's driver specification is NOT backward
157       compatible with the previous specification. If you already have a
158       driver developed to work with the previous version you're highly
159       encouraged to upgrade your driver code to make it compatible with the
160       current version. Fortunately, current driver specs are a lot easier to
161       adapt to.
162
163       For support information see CGI::Session
164

LICENSING

166       For support and licensing see CGI::Session.
167
168
169
170perl v5.30.0                      2019-07-26           CGI::Session::Driver(3)
Impressum