1Apache::Session::WrappeUrs(e3r)Contributed Perl DocumentAaptaicohne::Session::Wrapper(3)
2
3
4

NAME

6       Apache::Session::Wrapper - A simple wrapper around Apache::Session
7

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

CONFIGURATION

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

HOW COOKIES ARE HANDLED

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

REGISTERING CLASSES

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

SUBCLASSING

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

SUPPORT

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

AUTHOR

477       Dave Rolsky, <autarch@urth.org>
478

COPYRIGHT

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.36.0                      2022-07-22       Apache::Session::Wrapper(3)