1Apache::Session::WrappeUrs(e3r)Contributed Perl DocumentAaptaicohne::Session::Wrapper(3)
2
6 Apache::Session::Wrapper - A simple wrapper around Apache::Session
7
9 my $wrapper =
10 Apache::Session::Wrapper->new( class => 'MySQL',
11 handle => $dbh,
12 cookie_name => 'example-dot-com-cookie',
13 );
14 # will get an existing session from a cookie, or create a new session
16 # and cookie if needed
17 $wrapper->session->{foo} = 1;
18
20 This module is a simple wrapper around Apache::Session which provides
21 some methods to simplify getting and setting the session id.
22 It can uses cookies to store the session id, or it can look in a pro‐
24 vided object for a specific parameter. Alternately, you can simply
25 provide the session id yourself in the call to the "session()" method.
26 If you're using Mason, you should probably take a look at
28 "MasonX::Request::WithApacheSession" first, which integrates this mod‐
29 ule directly into Mason.
30
32 This class provides the following public methods:
33 * new
35 This method creates a new "Apache::Session::Wrapper" object.
36 If the parameters you provide are not correct (wrong type, missing
38 parameters, etc.), this method throws an "Apache::Session::Wrap‐
39 per::Exception::Params" exception. You can treat this exception as
40 a string if you want.
41 * session
43 This method returns a hash tied to the "Apache::Session" class.
44 This method accepts an optional "session_id" parameter.
46 * delete_session
48 This method deletes the existing session from persistent storage.
49 If you are using the built-in cookie handling, it also deletes the
50 cookie in the browser.
51
53 This module accepts quite a number of parameters, most of which are
54 simply passed through to "Apache::Session". For this reason, you are
55 advised to familiarize yourself with the "Apache::Session" documenta‐
56 tion before attempting to configure this module.
57 You can also register "Apache::Session" classes, or the classes used
59 for doing the work in "Apache::Session::Flex". See "REGISTERING
60 CLASSES" for details.
61 Supported Classes
63 The following classes are already supported and do not require regis‐
65 tration:
66 * Apache::Session::MySQL
68 * Apache::Session::Postgres
69 * Apache::Session::Oracle
70 * Apache::Session::Informix
71 * Apache::Session::Sybase
72 * Apache::Session::File
73 * Apache::Session::DB_File
74 * Apache::Session::PHP
75 * Apache::Session::Flex
76 The following classes can be used with "Apache::Session::Flex":
78 * Apache::Session::Store::MySQL
80 * Apache::Session::Store::Postgres
81 * Apache::Session::Store::Informix
82 * Apache::Session::Store::Oracle
83 * Apache::Session::Store::Sybase
84 * Apache::Session::Store::File
85 * Apache::Session::Store::DB_File
86 * Apache::Session::Store::PHP
87 * Apache::Session::Lock::MySQL
88 * Apache::Session::Lock::File
89 * Apache::Session::Lock::Null
90 * Apache::Session::Lock::Semaphore
91 * Apache::Session::Generate::MD5
92 * Apache::Session::Generate::ModUsertrack
93 * Apache::Session::Serialize::Storable
94 * Apache::Session::Serialize::Base64
95 * Apache::Session::Serialize::Sybase
96 * Apache::Session::Serialize::UUEncode
97 * Apache::Session::Serialize::PHP
98 Generic Parameters
100 * class => class name
102 The name of the "Apache::Session" subclass you would like to use.
103 This module will load this class for you if necessary.
105 This parameter is required.
107 * always_write => boolean
109 If this is true, then this module will ensure that "Apache::Ses‐
110 sion" writes the session. If it is false, the default
111 "Apache::Session" behavior is used instead.
112 This defaults to true.
114 * allow_invalid_id => boolean
116 If this is true, an attempt to create a session with a session id
117 that does not exist in the session storage will be ignored, and a
118 new session will be created instead. If it is false, a
119 "Apache::Session::Wrapper::Exception::NonExistentSessionID" excep‐
120 tion will be thrown instead.
121 This defaults to true.
123 * session_id => string
125 Try this session id first and use it if it exist. If the session
126 does not exist, it will ignore this parameter and make a new ses‐
127 sion.
128 Cookie-Related Parameters
130 * use_cookie => boolean
132 If true, then this module will use one of "Apache::Cookie",
133 "Apache2::Cookie" or "CGI::Cookie" (as appropriate) to set and read
134 cookies that contain the session id.
135 * cookie_name => name
137 This is the name of the cookie that this module will set. This
138 defaults to "Apache-Session-Wrapper-cookie". Corresponds to the
139 "Apache::Cookie" "-name" constructor parameter.
140 * cookie_expires => expiration
142 How long before the cookie expires. This defaults to 1 day, "+1d".
143 Corresponds to the "-expires" parameter.
144 As a special case, you can set this value to "session" to have the
146 "-expires" parameter set to undef, which gives you a cookie that
147 expires at the end of the session.
148 * cookie_domain => domain
150 This corresponds to the "-domain" parameter. If not given this
151 will not be set as part of the cookie.
152 If it is undefined, then no "-domain" parameter will be given.
154 * cookie_path => path
156 Corresponds to the "-path" parameter. It defaults to "/".
157 * cookie_secure => boolean
159 Corresponds to the "-secure" parameter. It defaults to false.
160 * cookie_resend => boolean
162 By default, this parameter is true, and the cookie will be sent for
163 every request. If it is false, then the cookie will only be sent
164 when the session is created. This is important as resending the
165 cookie has the effect of updating the expiration time.
166 * header_object => object
168 When running outside of mod_perl, you must provide an object to
169 which the cookie header can be added. This object must provide an
170 "err_headers_out()" or "headers_out()" method.
171 Under mod_perl 1, this will default to the object returned by
173 "Apache->request()". Under mod_perl 2 we call "Apache2::RequestU‐
174 til->request()"
175 Query/POST-Related Parameters
177 * param_name => name
179 If set, then this module will first look for the session id in the
180 object specified via "param_object". This parameter determines the
181 name of the parameter that is checked.
182 If you are also using cookies, then the module checks the param
184 object first, and then it checks for a cookie.
185 * param_object => object
187 This should be an object that provides a "param()" method. This
188 object will be checked to see if it contains the parameter named in
189 "params_name". This object will probably be a "CGI.pm" or
190 "Apache::Request" object, but it doesn't have to be.
191 Apache::Session-related Parameters
193 These parameters are simply passed through to "Apache::Session".
195 * data_source => DSN
197 Corresponds to the "DataSource" parameter passed to the DBI-related
198 session modules.
199 * user_name => user name
201 Corresponds to the "UserName" parameter passed to the DBI-related
202 session modules.
203 * password => password
205 Corresponds to the "Password" parameter passed to the DBI-related
206 session modules. Defaults to undef.
207 * handle => DBI handle
209 Corresponds to the "Handle" parameter passed to the DBI-related
210 session modules. This cannot be set via the httpd.conf file,
211 because it needs to be an actual Perl variable, not the name of
212 that variable.
213 * table_name => table name
215 Corresponds to the "TableName" paramaeter passed to DBI-related
216 modules.
217 * lock_data_source => DSN
219 Corresponds to the "LockDataSource" parameter passed to
220 "Apache::Session::MySQL".
221 * lock_user_name => user name
223 Corresponds to the "LockUserName" parameter passed to "Apache::Ses‐
224 sion::MySQL".
225 * lock_password => password
227 Corresponds to the "LockPassword" parameter passed to "Apache::Ses‐
228 sion::MySQL". Defaults to undef.
229 * lock_handle => DBI handle
231 Corresponds to the "LockHandle" parameter passed to the DBI-related
232 session modules. As with the "handle" parameter, this cannot be
233 set via the httpd.conf file.
234 * commit => boolean
236 Corresponds to the "Commit" parameter passed to the DBI-related
237 session modules.
238 * transaction => boolean
240 Corresponds to the "Transaction" parameter.
241 * directory => directory
243 Corresponds to the "Directory" parameter passed to "Apache::Ses‐
244 sion::File".
245 * lock_directory => directory
247 Corresponds to the "LockDirectory" parameter passed to
248 "Apache::Session::File".
249 * file_name => file name
251 Corresponds to the "FileName" parameter passed to "Apache::Ses‐
252 sion::DB_File".
253 * store => class
255 Corresponds to the "Store" parameter passed to "Apache::Ses‐
256 sion::Flex".
257 * lock => class
259 Corresponds to the "Lock" parameter passed to "Apache::Ses‐
260 sion::Flex".
261 * generate => class
263 Corresponds to the "Generate" parameter passed to "Apache::Ses‐
264 sion::Flex".
265 * serialize => class
267 Corresponds to the "Serialize" parameter passed to "Apache::Ses‐
268 sion::Flex".
269 * textsize => size
271 Corresponds to the "textsize" parameter passed to "Apache::Ses‐
272 sion::Sybase".
273 * long_read_len => size
275 Corresponds to the "LongReadLen" parameter passed to "Apache::Ses‐
276 sion::MySQL".
277 * n_sems => number
279 Corresponds to the "NSems" parameter passed to "Apache::Ses‐
280 sion::Lock::Semaphore".
281 * semaphore_key => key
283 Corresponds to the "SemaphoreKey" parameter passed to "Apache::Ses‐
284 sion::Lock::Semaphore".
285 * mod_usertrack_cookie_name => name
287 Corresponds to the "ModUsertrackCookieName" parameter passed to
288 "Apache::Session::Generate::ModUsertrack".
289 * save_path => path
291 Corresponds to the "SavePath" parameter passed to "Apache::Ses‐
292 sion::PHP".
293
295 When run under mod_perl, this module attempts to first use
296 "Apache::Cookie" for cookie-handling. Otherwise it uses "CGI::Cookie"
297 as a fallback.
298 If it ends up using "CGI::Cookie" then you must provide a
300 "header_object" parameter. This object must have an "err_headers_out()"
301 or "headers_out()" method. It looks for these methods in that order.
302 The method is expected to return an object with an API like
303 "Apache::Table". It calls "add()" on the returned method to add a
304 "Set-Cookie" header.
305
307 In order to support any "Apache::Session" subclasses, this module pro‐
308 vides a simple registration mechanism.
309 You can register an "Apache::Session" subclass, or a class intended to
311 provide a class that implements something required by "Apache::Ses‐
312 sion::Flex".
313 Registering a Complete Subclass
315 This is done by calling "Apache::Session::Wrapper->RegisterClass()":
317 Apache::Session::Wrapper->RegisterClass
319 ( name => 'MyClass',
320 required => [ [ qw( param1 param2 ) ],
321 [ qw( param3 param4 ) ] ],
322 optional => [ 'optional_p' ],
323 );
324 Apache::Session::Wrapper->RegisterClass
326 ( name => 'Apache::Session::MyFile',
327 required => 'File',
328 optional => 'File',
329 );
330 The "RegisterClass()" method takes the following options:
332 * name
334 This should be the name of the class you are registering. The
335 actual class must start with "Apache::Session::", but this part
336 does not need to be included when registering the class (it's
337 optional).
338 * required
340 These are the required parameters for this class.
341 The value of this parameter can either be a string or a reference
343 to an array of array references.
344 If it is a string, then it identifies an existing "Apache::Session"
346 subclass which is already registered or built-in, like "File" or
347 "Postgres".
348 If it an array reference, then that reference should in turn con‐
350 tain one or more array references. Each of those contained refer‐
351 ences represents one set of required parameters. When an
352 "Apache::Session::Wrapper" object is constructed, only one of these
353 sets must be passed in. For example:
354 required => [ [ qw( p1 p2 ) ],
356 [ qw( p2 p3 p4 ) ] ]
357 This says that either "p1" and "p2" must be provided, or "p2",
359 "p3", and "p4".
360 If there are no required parameters for this class, then the
362 "required" parameter can be omitted.
363 * optional
365 This specifies optional parameters, and should just be a simple
366 array reference.
367 Registering a Subclass for Flex
369 Registering a subclass that can be used with "Apache::Session::Flex" is
371 very similar to registering a complete class:
372 Apache::Session::Wrapper->RegisterFlexClass
374 ( name => 'MyClass',
375 type => 'Store',
376 required => [ [ qw( param1 param2 ) ],
377 [ qw( param3 param4 ) ] ],
378 optional => [ 'optional_p' ],
379 );
380 Apache::Session::Wrapper->RegisterFlexClass
382 ( name => 'Apache::Session::Store::MyFile',
383 type => 'store',
384 required => 'File',
385 optional => 'File',
386 );
387 The "RegisterFlexClass()" method has the same parameters as "Register‐
389 Class()", but it also requires a "type" parameter. This must be one of
390 "store", "lock", "generate", or "serialize".
391
393 This class provides a simple hook for subclasses. Before trying to get
394 a session id from the URL or cookie, it calls a method named "_get_ses‐
395 sion_id()". In this class, that method is a no-op, but you can over‐
396 ride this in a subclass.
397 This class is a "Class::Container" subclass, so if you accept addi‐
399 tional constructor parameters, you should declare them via the
400 "valid_params()" method.
401
403 As can be seen by the number of parameters above, "Apache::Session" has
404 way too many possibilities for me to test all of them. This means
405 there are almost certainly bugs.
406 Please submit bugs to the CPAN RT system at
408 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Apache%3A%3ASes‐
409 sion%3A%3AWrapper or via email at bug-apache-session-wrap‐
410 per@rt.cpan.org.
411 Support questions can be sent to me at my email address, shown below.
413
415 Dave Rolsky, <autarch@urth.org>
416
418 Copyright (c) 2003-2006 David Rolsky. All rights reserved. This pro‐
419 gram is free software; you can redistribute it and/or modify it under
420 the same terms as Perl itself.
421 The full text of the license can be found in the LICENSE file included
423 with this module.
424perl v5.8.8 2007-01-17 Apache::Session::Wrapper(3)