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
