NAME¶
Apache::Session::Wrapper - A simple wrapper around Apache::Session
SYNOPSIS¶
my $wrapper =
Apache::Session::Wrapper->new( class => 'MySQL',
handle => $dbh,
cookie_name => 'example-dot-com-cookie',
);
# will get an existing session from a cookie, or create a new session
# and cookie if needed
$wrapper->session->{foo} = 1;
DESCRIPTION¶
This module is a simple wrapper around Apache::Session which provides some
methods to simplify getting and setting the session id.
It can uses cookies to store the session id, or it can look in a provided object
for a specific parameter. Alternately, you can simply provide the session id
yourself in the call to the "session()" method.
If you're using Mason, you should probably take a look at
"MasonX::Request::WithApacheSession" first, which integrates this
module directly into Mason.
METHODS¶
This class provides the following public methods:
- •
- new
This method creates a new "Apache::Session::Wrapper" object.
If the parameters you provide are not correct (wrong type, missing
parameters, etc.), this method throws an
"Apache::Session::Wrapper::Exception::Params" exception. You can
treat this exception as a string if you want.
- •
- session
This method returns a hash tied to the "Apache::Session" class.
This method accepts an optional "session_id" parameter.
- •
- delete_session
This method deletes the existing session from persistent storage. If you are
using the built-in cookie handling, it also deletes the cookie in the
browser.
CONFIGURATION¶
This module accepts quite a number of parameters, most of which are simply
passed through to "Apache::Session". For this reason, you are
advised to familiarize yourself with the "Apache::Session"
documentation before attempting to configure this module.
You can also register "Apache::Session" classes, or the classes used
for doing the work in "Apache::Session::Flex". See REGISTERING
CLASSES for details.
Supported Classes¶
The following classes are already supported and do not require registration:
- •
- Apache::Session::MySQL
- •
- Apache::Session::Postgres
- •
- Apache::Session::Oracle
- •
- Apache::Session::Informix
- •
- Apache::Session::Sybase
- •
- Apache::Session::File
- •
- Apache::Session::DB_File
- •
- Apache::Session::PHP
- •
- Apache::Session::Flex
The following classes can be used with "Apache::Session::Flex":
- •
- Apache::Session::Store::MySQL
- •
- Apache::Session::Store::Postgres
- •
- Apache::Session::Store::Informix
- •
- Apache::Session::Store::Oracle
- •
- Apache::Session::Store::Sybase
- •
- Apache::Session::Store::File
- •
- Apache::Session::Store::DB_File
- •
- Apache::Session::Store::PHP
- •
- Apache::Session::Lock::MySQL
- •
- Apache::Session::Lock::File
- •
- Apache::Session::Lock::Null
- •
- Apache::Session::Lock::Semaphore
- •
- Apache::Session::Generate::MD5
- •
- Apache::Session::Generate::ModUsertrack
- •
- Apache::Session::Serialize::Storable
- •
- Apache::Session::Serialize::Base64
- •
- Apache::Session::Serialize::Sybase
- •
- Apache::Session::Serialize::UUEncode
- •
- Apache::Session::Serialize::PHP
Generic Parameters¶
- •
- class => class name
The name of the "Apache::Session" subclass you would like to use.
This module will load this class for you if necessary.
This parameter is required.
- •
- always_write => boolean
If this is true, then this module will ensure that
"Apache::Session" writes the session. If it is false, the
default "Apache::Session" behavior is used instead.
This defaults to true.
- •
- allow_invalid_id => boolean
If this is true, an attempt to create a session with a session id that does
not exist in the session storage will be ignored, and a new session will
be created instead. If it is false, a
"Apache::Session::Wrapper::Exception::NonExistentSessionID"
exception will be thrown instead.
This defaults to true.
- •
- session_id => string
Try this session id first and use it if it exist. If the session does not
exist, it will ignore this parameter and make a new session.
- •
- use_cookie => boolean
If true, then this module will use one of "Apache::Cookie",
"Apache2::Cookie" or "CGI::Cookie" (as appropriate) to
set and read cookies that contain the session id.
- •
- cookie_name => name
This is the name of the cookie that this module will set. This defaults to
"Apache-Session-Wrapper-cookie". Corresponds to the
"Apache::Cookie" "-name" constructor parameter.
- •
- cookie_expires => expiration
How long before the cookie expires. This defaults to 1 day, "+1d".
Corresponds to the "-expires" parameter.
As a special case, you can set this value to "session" to have the
"-expires" parameter set to undef, which gives you a cookie that
expires at the end of the session.
- •
- cookie_domain => domain
This corresponds to the "-domain" parameter. If not given this
will not be set as part of the cookie.
If it is undefined, then no "-domain" parameter will be
given.
- •
- cookie_path => path
Corresponds to the "-path" parameter. It defaults to
"/".
- •
- cookie_secure => boolean
Corresponds to the "-secure" parameter. It defaults to false.
- •
- cookie_resend => boolean
By default, this parameter is true, and the cookie will be sent for every
request. If it is false, then the cookie will only be sent when the
session is created. This is important as resending the cookie has
the effect of updating the expiration time.
- •
- header_object => object
When running outside of mod_perl, you must provide an object to which the
cookie header can be added. This object must provide an
"err_headers_out()" or "headers_out()" method.
Under mod_perl 1, this will default to the object returned by
"Apache->request()". Under mod_perl 2 we call
"Apache2::RequestUtil->request()"
Query/POST-Related Parameters¶
- •
- param_name => name
If set, then this module will first look for the session id in the object
specified via "param_object". This parameter determines the name
of the parameter that is checked.
If you are also using cookies, then the module checks the param object
first, and then it checks for a cookie.
- •
- param_object => object
This should be an object that provides a "param()" method. This
object will be checked to see if it contains the parameter named in
"params_name". This object will probably be a "CGI.pm"
or "Apache::Request" object, but it doesn't have to be.
These parameters are simply passed through to "Apache::Session".
- •
- data_source => DSN
Corresponds to the "DataSource" parameter passed to the
DBI-related session modules.
- •
- user_name => user name
Corresponds to the "UserName" parameter passed to the DBI-related
session modules.
- •
- password => password
Corresponds to the "Password" parameter passed to the DBI-related
session modules. Defaults to undef.
- •
- handle => DBI handle
Corresponds to the "Handle" parameter passed to the DBI-related
session modules. This cannot be set via the httpd.conf file,
because it needs to be an actual Perl variable, not the name
of that variable.
- •
- table_name => table name
Corresponds to the "TableName" paramaeter passed to DBI-related
modules.
- •
- lock_data_source => DSN
Corresponds to the "LockDataSource" parameter passed to
"Apache::Session::MySQL".
- •
- lock_user_name => user name
Corresponds to the "LockUserName" parameter passed to
"Apache::Session::MySQL".
- •
- lock_password => password
Corresponds to the "LockPassword" parameter passed to
"Apache::Session::MySQL". Defaults to undef.
- •
- lock_handle => DBI handle
Corresponds to the "LockHandle" parameter passed to the
DBI-related session modules. As with the "handle" parameter,
this cannot be set via the httpd.conf file.
- •
- commit => boolean
Corresponds to the "Commit" parameter passed to the DBI-related
session modules.
- •
- transaction => boolean
Corresponds to the "Transaction" parameter.
- •
- directory => directory
Corresponds to the "Directory" parameter passed to
"Apache::Session::File".
- •
- lock_directory => directory
Corresponds to the "LockDirectory" parameter passed to
"Apache::Session::File".
- •
- file_name => file name
Corresponds to the "FileName" parameter passed to
"Apache::Session::DB_File".
- •
- store => class
Corresponds to the "Store" parameter passed to
"Apache::Session::Flex".
- •
- lock => class
Corresponds to the "Lock" parameter passed to
"Apache::Session::Flex".
- •
- generate => class
Corresponds to the "Generate" parameter passed to
"Apache::Session::Flex".
- •
- serialize => class
Corresponds to the "Serialize" parameter passed to
"Apache::Session::Flex".
- •
- textsize => size
Corresponds to the "textsize" parameter passed to
"Apache::Session::Sybase".
- •
- long_read_len => size
Corresponds to the "LongReadLen" parameter passed to
"Apache::Session::MySQL".
- •
- n_sems => number
Corresponds to the "NSems" parameter passed to
"Apache::Session::Lock::Semaphore".
- •
- semaphore_key => key
Corresponds to the "SemaphoreKey" parameter passed to
"Apache::Session::Lock::Semaphore".
- •
- mod_usertrack_cookie_name => name
Corresponds to the "ModUsertrackCookieName" parameter passed to
"Apache::Session::Generate::ModUsertrack".
- •
- save_path => path
Corresponds to the "SavePath" parameter passed to
"Apache::Session::PHP".
HOW COOKIES ARE HANDLED¶
When run under mod_perl, this module attempts to first use
"Apache::Cookie" for cookie-handling. Otherwise it uses
"CGI::Cookie" as a fallback.
If it ends up using "CGI::Cookie" then you must provide a
"header_object" parameter. This object must have an
"err_headers_out()" or "headers_out()" method. It looks
for these methods in that order. The method is expected to return an object
with an API like "Apache::Table". It calls "add()" on the
returned method to add a "Set-Cookie" header.
REGISTERING CLASSES¶
In order to support any "Apache::Session" subclasses, this module
provides a simple registration mechanism.
You can register an "Apache::Session" subclass, or a class intended to
provide a class that implements something required by
"Apache::Session::Flex".
Registering a Complete Subclass¶
This is done by calling
"Apache::Session::Wrapper->RegisterClass()":
Apache::Session::Wrapper->RegisterClass
( name => 'MyClass',
required => [ [ qw( param1 param2 ) ],
[ qw( param3 param4 ) ] ],
optional => [ 'optional_p' ],
);
Apache::Session::Wrapper->RegisterClass
( name => 'Apache::Session::MyFile',
required => 'File',
optional => 'File',
);
The "RegisterClass()" method takes the following options:
- •
- name
This should be the name of the class you are registering. The actual class
must start with "Apache::Session::", but this part does not need
to be included when registering the class (it's optional).
- •
- required
These are the required parameters for this class.
The value of this parameter can either be a string or a reference to an
array of array references.
If it is a string, then it identifies an existing
"Apache::Session" subclass which is already registered or
built-in, like "File" or "Postgres".
If it an array reference, then that reference should in turn contain
one or more array references. Each of those contained references
represents one set of required parameters. When an
"Apache::Session::Wrapper" object is constructed, only one of
these sets must be passed in. For example:
required => [ [ qw( p1 p2 ) ],
[ qw( p2 p3 p4 ) ] ]
This says that either "p1" and "p2" must be provided,
or "p2", "p3", and "p4".
If there are no required parameters for this class, then the
"required" parameter can be omitted.
- •
- optional
This specifies optional parameters, and should just be a simple array
reference.
Registering a Subclass for Flex¶
Registering a subclass that can be used with "Apache::Session::Flex"
is very similar to registering a complete class:
Apache::Session::Wrapper->RegisterFlexClass
( name => 'MyClass',
type => 'Store',
required => [ [ qw( param1 param2 ) ],
[ qw( param3 param4 ) ] ],
optional => [ 'optional_p' ],
);
Apache::Session::Wrapper->RegisterFlexClass
( name => 'Apache::Session::Store::MyFile',
type => 'store',
required => 'File',
optional => 'File',
);
The "RegisterFlexClass()" method has the same parameters as
"RegisterClass()", but it also requires a "type"
parameter. This must be one of "store", "lock",
"generate", or "serialize".
SUBCLASSING¶
This class provides a simple hook for subclasses. Before trying to get a session
id from the URL or cookie, it calls a method named
"_get_session_id()". In this class, that method is a no-op, but you
can override this in a subclass.
This class is a "Class::Container" subclass, so if you accept
additional constructor parameters, you should declare them via the
"valid_params()" method.
SUPPORT¶
As can be seen by the number of parameters above, "Apache::Session"
has
way too many possibilities for me to test all of them. This means
there are almost certainly bugs.
Please submit bugs to the CPAN RT system at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Apache%3A%3ASession%3A%3AWrapper
or via email at bug-apache-session-wrapper@rt.cpan.org.
Support questions can be sent to me at my email address, shown below.
AUTHOR¶
Dave Rolsky, <autarch@urth.org>
COPYRIGHT¶
Copyright (c) 2003-2006 David Rolsky. All rights reserved. This program is free
software; you can redistribute it and/or modify it under the same terms as
Perl itself.
The full text of the license can be found in the LICENSE file included with this
module.