1CGI::Session::Driver(3)User Contributed Perl DocumentatioCnGI::Session::Driver(3)
2
6 CGI::Session::Driver - CGI::Session driver specifications
7
9 require CGI::Session::Driver;
10 @ISA = qw( CGI::Session::Driver );
11
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
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 BLUEPRINT
25 The best way of learning the specs is to look at a blueprint of a
26 driver:
27 package CGI::Session::Driver::your_driver_name;
29 use strict;
30 use base qw( CGI::Session::Driver CGI::Session::ErrorHandler );
31 sub init {
33 my ($self) = @_;
34 # optional
35 }
36 sub DESTROY {
38 my ($self) = @_;
39 # optional
40 }
41 sub store {
43 my ($self, $sid, $datastr) = @_;
44 # Store $datastr, which is an already serialized string of data.
45 }
46 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 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 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 1;
66 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 $s = CGI::Session->new("driver:your_driver_name", undef, {Directory=>'/tmp/sessions'});
73 You can access value of 'Directory' from within your driver like so:
75 sub store {
77 my ($self, $sid, $datastr) = @_;
78 my $dir = $self->{Directory}; # <-- in this example will be '/tmp/sessions'
79 }
80 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 For examples of init() look into the source code of native CGI::Session
87 drivers.
88
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 second
94 argument.
95 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 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 Tip: set_error() always returns undef. Use it for your advantage.
110 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 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 $datastr, which is passed as the third argument to represents
122 already serialized session data that needs to be saved.
123 store() can return any true value indicating success or undef on
125 failure. Error message should be passed to set_error()
126 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 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 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 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 NOTES
150 • All driver .pm files must be lowercase!
151 • DBI-related drivers are better off using CGI::Session::Driver::DBI
153 as base, but don't have to.
154
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 For support information see CGI::Session
164
166 For support and licensing see CGI::Session.
167perl v5.36.0 2023-01-20 CGI::Session::Driver(3)