1Apache::Session::WrappeUrs(e3r)Contributed Perl DocumentAaptaicohne::Session::Wrapper(3)
2
3
4
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
15 # 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
23 It can uses cookies to store the session id, or it can look in a
24 provided object for a specific parameter. Alternately, you can simply
25 provide the session id yourself in the call to the "session()" method.
26
27 If you're using Mason, you should probably take a look at
28 "MasonX::Request::WithApacheSession" first, which integrates this
29 module directly into Mason.
30
32 This class provides the following public methods:
33
34 · new
35
36 This method creates a new "Apache::Session::Wrapper" object.
37
38 If the parameters you provide are not correct (wrong type, missing
39 parameters, etc.), this method throws an
40 "Apache::Session::Wrapper::Exception::Params" exception. You can
41 treat this exception as a string if you want.
42
43 · session
44
45 This method returns a hash tied to the "Apache::Session" class.
46
47 This method accepts an optional "session_id" parameter.
48
49 · delete_session
50
51 This method deletes the existing session from persistent storage.
52 If you are using the built-in cookie handling, it also deletes the
53 cookie in the browser.
54
56 This module accepts quite a number of parameters, most of which are
57 simply passed through to "Apache::Session". For this reason, you are
58 advised to familiarize yourself with the "Apache::Session"
59 documentation before attempting to configure this module.
60
61 You can also register "Apache::Session" classes, or the classes used
62 for doing the work in "Apache::Session::Flex". See REGISTERING CLASSES
63 for details.
64
65 Supported Classes
66 The following classes are already supported and do not require
67 registration:
68
69 · Apache::Session::MySQL
70
71 · Apache::Session::Postgres
72
73 · Apache::Session::Oracle
74
75 · Apache::Session::Informix
76
77 · Apache::Session::Sybase
78
79 · Apache::Session::File
80
81 · Apache::Session::DB_File
82
83 · Apache::Session::PHP
84
85 · Apache::Session::Flex
86
87 The following classes can be used with "Apache::Session::Flex":
88
89 · Apache::Session::Store::MySQL
90
91 · Apache::Session::Store::Postgres
92
93 · Apache::Session::Store::Informix
94
95 · Apache::Session::Store::Oracle
96
97 · Apache::Session::Store::Sybase
98
99 · Apache::Session::Store::File
100
101 · Apache::Session::Store::DB_File
102
103 · Apache::Session::Store::PHP
104
105 · Apache::Session::Lock::MySQL
106
107 · Apache::Session::Lock::File
108
109 · Apache::Session::Lock::Null
110
111 · Apache::Session::Lock::Semaphore
112
113 · Apache::Session::Generate::MD5
114
115 · Apache::Session::Generate::ModUsertrack
116
117 · Apache::Session::Serialize::Storable
118
119 · Apache::Session::Serialize::Base64
120
121 · Apache::Session::Serialize::Sybase
122
123 · Apache::Session::Serialize::UUEncode
124
125 · Apache::Session::Serialize::PHP
126
127 Generic Parameters
128 · class => class name
129
130 The name of the "Apache::Session" subclass you would like to use.
131
132 This module will load this class for you if necessary.
133
134 This parameter is required.
135
136 · always_write => boolean
137
138 If this is true, then this module will ensure that
139 "Apache::Session" writes the session. If it is false, the default
140 "Apache::Session" behavior is used instead.
141
142 This defaults to true.
143
144 · allow_invalid_id => boolean
145
146 If this is true, an attempt to create a session with a session id
147 that does not exist in the session storage will be ignored, and a
148 new session will be created instead. If it is false, a
149 "Apache::Session::Wrapper::Exception::NonExistentSessionID"
150 exception will be thrown instead.
151
152 This defaults to true.
153
154 · session_id => string
155
156 Try this session id first and use it if it exist. If the session
157 does not exist, it will ignore this parameter and make a new
158 session.
159
160 Cookie-Related Parameters
161 · use_cookie => boolean
162
163 If true, then this module will use one of "Apache::Cookie",
164 "Apache2::Cookie" or "CGI::Cookie" (as appropriate) to set and read
165 cookies that contain the session id.
166
167 · cookie_name => name
168
169 This is the name of the cookie that this module will set. This
170 defaults to "Apache-Session-Wrapper-cookie". Corresponds to the
171 "Apache::Cookie" "-name" constructor parameter.
172
173 · cookie_expires => expiration
174
175 How long before the cookie expires. This defaults to 1 day, "+1d".
176 Corresponds to the "-expires" parameter.
177
178 As a special case, you can set this value to "session" to have the
179 "-expires" parameter set to undef, which gives you a cookie that
180 expires at the end of the session.
181
182 · cookie_domain => domain
183
184 This corresponds to the "-domain" parameter. If not given this
185 will not be set as part of the cookie.
186
187 If it is undefined, then no "-domain" parameter will be given.
188
189 · cookie_path => path
190
191 Corresponds to the "-path" parameter. It defaults to "/".
192
193 · cookie_secure => boolean
194
195 Corresponds to the "-secure" parameter. It defaults to false.
196
197 · cookie_resend => boolean
198
199 By default, this parameter is true, and the cookie will be sent for
200 every request. If it is false, then the cookie will only be sent
201 when the session is created. This is important as resending the
202 cookie has the effect of updating the expiration time.
203
204 · header_object => object
205
206 When running outside of mod_perl, you must provide an object to
207 which the cookie header can be added. This object must provide an
208 "err_headers_out()" or "headers_out()" method.
209
210 Under mod_perl 1, this will default to the object returned by
211 "Apache->request()". Under mod_perl 2 we call
212 "Apache2::RequestUtil->request()"
213
214 Query/POST-Related Parameters
215 · param_name => name
216
217 If set, then this module will first look for the session id in the
218 object specified via "param_object". This parameter determines the
219 name of the parameter that is checked.
220
221 If you are also using cookies, then the module checks the param
222 object first, and then it checks for a cookie.
223
224 · param_object => object
225
226 This should be an object that provides a "param()" method. This
227 object will be checked to see if it contains the parameter named in
228 "params_name". This object will probably be a "CGI.pm" or
229 "Apache::Request" object, but it doesn't have to be.
230
231 Apache::Session-related Parameters
232 These parameters are simply passed through to "Apache::Session".
233
234 · data_source => DSN
235
236 Corresponds to the "DataSource" parameter passed to the DBI-related
237 session modules.
238
239 · user_name => user name
240
241 Corresponds to the "UserName" parameter passed to the DBI-related
242 session modules.
243
244 · password => password
245
246 Corresponds to the "Password" parameter passed to the DBI-related
247 session modules. Defaults to undef.
248
249 · handle => DBI handle
250
251 Corresponds to the "Handle" parameter passed to the DBI-related
252 session modules. This cannot be set via the httpd.conf file,
253 because it needs to be an actual Perl variable, not the name of
254 that variable.
255
256 · table_name => table name
257
258 Corresponds to the "TableName" paramaeter passed to DBI-related
259 modules.
260
261 · lock_data_source => DSN
262
263 Corresponds to the "LockDataSource" parameter passed to
264 "Apache::Session::MySQL".
265
266 · lock_user_name => user name
267
268 Corresponds to the "LockUserName" parameter passed to
269 "Apache::Session::MySQL".
270
271 · lock_password => password
272
273 Corresponds to the "LockPassword" parameter passed to
274 "Apache::Session::MySQL". Defaults to undef.
275
276 · lock_handle => DBI handle
277
278 Corresponds to the "LockHandle" parameter passed to the DBI-related
279 session modules. As with the "handle" parameter, this cannot be
280 set via the httpd.conf file.
281
282 · commit => boolean
283
284 Corresponds to the "Commit" parameter passed to the DBI-related
285 session modules.
286
287 · transaction => boolean
288
289 Corresponds to the "Transaction" parameter.
290
291 · directory => directory
292
293 Corresponds to the "Directory" parameter passed to
294 "Apache::Session::File".
295
296 · lock_directory => directory
297
298 Corresponds to the "LockDirectory" parameter passed to
299 "Apache::Session::File".
300
301 · file_name => file name
302
303 Corresponds to the "FileName" parameter passed to
304 "Apache::Session::DB_File".
305
306 · store => class
307
308 Corresponds to the "Store" parameter passed to
309 "Apache::Session::Flex".
310
311 · lock => class
312
313 Corresponds to the "Lock" parameter passed to
314 "Apache::Session::Flex".
315
316 · generate => class
317
318 Corresponds to the "Generate" parameter passed to
319 "Apache::Session::Flex".
320
321 · serialize => class
322
323 Corresponds to the "Serialize" parameter passed to
324 "Apache::Session::Flex".
325
326 · textsize => size
327
328 Corresponds to the "textsize" parameter passed to
329 "Apache::Session::Sybase".
330
331 · long_read_len => size
332
333 Corresponds to the "LongReadLen" parameter passed to
334 "Apache::Session::MySQL".
335
336 · n_sems => number
337
338 Corresponds to the "NSems" parameter passed to
339 "Apache::Session::Lock::Semaphore".
340
341 · semaphore_key => key
342
343 Corresponds to the "SemaphoreKey" parameter passed to
344 "Apache::Session::Lock::Semaphore".
345
346 · mod_usertrack_cookie_name => name
347
348 Corresponds to the "ModUsertrackCookieName" parameter passed to
349 "Apache::Session::Generate::ModUsertrack".
350
351 · save_path => path
352
353 Corresponds to the "SavePath" parameter passed to
354 "Apache::Session::PHP".
355
357 When run under mod_perl, this module attempts to first use
358 "Apache::Cookie" for cookie-handling. Otherwise it uses "CGI::Cookie"
359 as a fallback.
360
361 If it ends up using "CGI::Cookie" then you must provide a
362 "header_object" parameter. This object must have an "err_headers_out()"
363 or "headers_out()" method. It looks for these methods in that order.
364 The method is expected to return an object with an API like
365 "Apache::Table". It calls "add()" on the returned method to add a "Set-
366 Cookie" header.
367
369 In order to support any "Apache::Session" subclasses, this module
370 provides a simple registration mechanism.
371
372 You can register an "Apache::Session" subclass, or a class intended to
373 provide a class that implements something required by
374 "Apache::Session::Flex".
375
376 Registering a Complete Subclass
377 This is done by calling "Apache::Session::Wrapper->RegisterClass()":
378
379 Apache::Session::Wrapper->RegisterClass
380 ( name => 'MyClass',
381 required => [ [ qw( param1 param2 ) ],
382 [ qw( param3 param4 ) ] ],
383 optional => [ 'optional_p' ],
384 );
385
386 Apache::Session::Wrapper->RegisterClass
387 ( name => 'Apache::Session::MyFile',
388 required => 'File',
389 optional => 'File',
390 );
391
392 The "RegisterClass()" method takes the following options:
393
394 · name
395
396 This should be the name of the class you are registering. The
397 actual class must start with "Apache::Session::", but this part
398 does not need to be included when registering the class (it's
399 optional).
400
401 · required
402
403 These are the required parameters for this class.
404
405 The value of this parameter can either be a string or a reference
406 to an array of array references.
407
408 If it is a string, then it identifies an existing "Apache::Session"
409 subclass which is already registered or built-in, like "File" or
410 "Postgres".
411
412 If it an array reference, then that reference should in turn
413 contain one or more array references. Each of those contained
414 references represents one set of required parameters. When an
415 "Apache::Session::Wrapper" object is constructed, only one of these
416 sets must be passed in. For example:
417
418 required => [ [ qw( p1 p2 ) ],
419 [ qw( p2 p3 p4 ) ] ]
420
421 This says that either "p1" and "p2" must be provided, or "p2",
422 "p3", and "p4".
423
424 If there are no required parameters for this class, then the
425 "required" parameter can be omitted.
426
427 · optional
428
429 This specifies optional parameters, and should just be a simple
430 array reference.
431
432 Registering a Subclass for Flex
433 Registering a subclass that can be used with "Apache::Session::Flex" is
434 very similar to registering a complete class:
435
436 Apache::Session::Wrapper->RegisterFlexClass
437 ( name => 'MyClass',
438 type => 'Store',
439 required => [ [ qw( param1 param2 ) ],
440 [ qw( param3 param4 ) ] ],
441 optional => [ 'optional_p' ],
442 );
443
444 Apache::Session::Wrapper->RegisterFlexClass
445 ( name => 'Apache::Session::Store::MyFile',
446 type => 'store',
447 required => 'File',
448 optional => 'File',
449 );
450
451 The "RegisterFlexClass()" method has the same parameters as
452 "RegisterClass()", but it also requires a "type" parameter. This must
453 be one of "store", "lock", "generate", or "serialize".
454
456 This class provides a simple hook for subclasses. Before trying to get
457 a session id from the URL or cookie, it calls a method named
458 "_get_session_id()". In this class, that method is a no-op, but you
459 can override this in a subclass.
460
461 This class is a "Class::Container" subclass, so if you accept
462 additional constructor parameters, you should declare them via the
463 "valid_params()" method.
464
466 As can be seen by the number of parameters above, "Apache::Session" has
467 way too many possibilities for me to test all of them. This means
468 there are almost certainly bugs.
469
470 Please submit bugs to the CPAN RT system at
471 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Apache%3A%3ASession%3A%3AWrapper
472 or via email at bug-apache-session-wrapper@rt.cpan.org.
473
474 Support questions can be sent to me at my email address, shown below.
475
477 Dave Rolsky, <autarch@urth.org>
478
480 Copyright (c) 2003-2006 David Rolsky. All rights reserved. This
481 program is free software; you can redistribute it and/or modify it
482 under the same terms as Perl itself.
483
484 The full text of the license can be found in the LICENSE file included
485 with this module.
486
487
488
489perl v5.30.0 2019-07-26 Apache::Session::Wrapper(3)