So here's the second release of the module that was discussed on this list
earlier. It provides a simple wrapper around Apache::Session that handles
getting a session id from a cookie or URL parameter.
It also has a generic hook for subclassing, where it will simply call
"_get_session_id" before trying to get an id from a cookie or URL.
Unfortunately, I just realized that I forgot to document this (oops).
Ignore version 0.1, which is missing a bit of docs, and has the wrong
default cookie name.
Docs after my sig for this first release.
-dave
/*=======================
House Absolute Consulting
www.houseabsolute.com
=======================*/
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.
* session
This method returns a hash tied to the "Apache::Session" class.
* 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.
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
"HTML::Mason::Exception::NonExistentSessionID" exception will be
thrown instead.
This defaults to true.
Cookie-Related Parameters
* use_cookie => boolean
If true, then this module will use "Apache::Cookie" to set and read
cookies that contain the session id.
The cookie will be set again every time the client accesses a Mason
component unless the "cookie_resend" parameter is false.
* 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.
* 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
either an "err_header_out()" or "header_out()" method.
Under mod_perl, this will default to the object returned by
"Apache->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.
The session id is available from "$m->session->{_session_id}".
* 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.
Apache::Session-related Parameters
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.
* 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".
* 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 must provide a "header_object"
parameter. The module calls "err_header_out()" or "header_out()" on the
provided object, using the former if it's available.
SUBCLASSING
This class provides a simply 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%3A
Wrapper or via email at [EMAIL PROTECTED]
Support questions can be sent to me at my email address, listed below.
AUTHOR
Dave Rolsky, <[EMAIL PROTECTED]>
--
Report problems: http://perl.apache.org/bugs/
Mail list info: http://perl.apache.org/maillist/modperl.html
List etiquette: http://perl.apache.org/maillist/email-etiquette.html
