NAME
MasonX::Request::WithApache2Session - Add a session to the Mason Request object
SYNOPSIS
In your httpd.conf file:
PerlSetVar MasonRequestClass MasonX::Request::WithApache2Session
PerlSetVar MasonSessionCookieDomain .example.com
PerlSetVar MasonSessionClass Apache::Session::MySQL
PerlSetVar MasonSessionDataSource dbi:mysql:somedb
Or when creating an Apache2Handler object:
my $ah =
MasonX::Apache2Handler->new
( request_class => 'MasonX::Request::WithApache2Session',
session_cookie_domain => '.example.com',
session_class => 'Apache::2Session::MySQL',
session_data_source => 'dbi:mysql:somedb',
);
In a component:
$m->session->{foo} = 1;
if ( $m->session->{bar}{baz} > 1 ) { ... }
DESCRIPTION
MasonX::Request::WithApache2Session is experimental ( beta ) and should only be used in a test environment.
MasonX::Request::WithApache2Session is a clone of MasonX::Request::WithApacheSession changed to work under a pure mod_perl2 environment. The external interface is unchanged, see MasonX::Request::WithApacheSession.
The actual changes I made can be found in the distribution in diff/WithApacheSession.diff ( made with 'diff -Naru' ... ).
A HOWTO for MasonX::Apache2Handler and friends may be found at Mason-with-mod_perl2.
The following documentation is from MasonX::Request::WithApacheSession,
This module integrates Apache::Session
into Mason by adding methods to the Mason Request object available in all Mason components.
Any subrequests created by a request share the same session.
USAGE
To use this module you need to tell Mason to use this class for requests. This can be done in one of two ways. If you are configuring Mason via your httpd.conf file, simply add this:
PerlSetVar MasonRequestClass MasonX::Request::WithApache2Session
If you are using a handler.pl file, simply add this parameter to the parameters given to the ApacheHandler constructor:
request_class => 'MasonX::Request::WithApache2Session'
METHODS
This class adds two methods to the Request 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 mechanism, 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
session_class / MasonSessionClass => 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.
session_always_write / MasonSessionAlwaysWrite => boolean
If this is true, then this module will ensure that
Apache::Session
writes the session. If it is false, the defaultApache::Session
behavior is used instead.This defaults to true.
session_allow_invalid_id / MasonSessionAllowInvalidId => 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
session_use_cookie / MasonSessionUseCookie => 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
session_cookie_resend
parameter is false.session_cookie_name / MasonSessionCookieName => name
This is the name of the cookie that this module will set. This defaults to "MasonX-Request-WithApacheSession-cookie". Corresponds to the
Apache::Cookie
"-name" constructor parameter.session_cookie_expires / MasonSessionCookieExpires => expiration
How long before the cookie expires. This defaults to 1 day, "+1d". Corresponds to the "-expires" parameter.
session_cookie_domain / MasonSessionCookieDomain => 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.
session_cookie_path / MasonSessionCookiePath => path
Corresponds to the "-path" parameter. It defaults to "/".
session_cookie_secure / MasonSessionCookieSecure => boolean
Corresponds to the "-secure" parameter. It defaults to false.
session_cookie_resend / MasonSessionCookieResend => 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.
URL-Related Parameters
session_args_param / MasonSessionArgsParam => name
If set, then this module will first look for the session id in the query string or POST parameter with the specified name.
If you are also using cookies, then the module checks in the request arguments first, and then it checks for a cookie.
The session id is available from
$m->session->{_session_id}
.
Apache::Session-related Parameters
These parameters are simply passed through to Apache::Session
.
session_data_source / MasonSessionDataSource => DSN
Corresponds to the
DataSource
parameter given to the DBI-related session modules.session_user_name / MasonSessionUserName => user name
Corresponds to the
UserName
parameter given to the DBI-related session modules.session_password / MasonSessionPassword => password
Corresponds to the
Password
parameter given to the DBI-related session modules.session_handle => DBI handle
Corresponds to the
Handle
parameter given 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.session_lock_data_source / MasonSessionLockDataSource => DSN
Corresponds to the
LockDataSource
parameter given toApache::Session::MySQL
.session_lock_user_name / MasonSessionLockUserName => user name
Corresponds to the
LockUserName
parameter given toApache::Session::MySQL
.session_lock_password / MasonSessionLockPassword => password
Corresponds to the
LockPassword
parameter given toApache::Session::MySQL
.session_lock_handle => DBI handle
Corresponds to the
LockHandle
parameter given to the DBI-related session modules. As with thesession_handle
parameter, this cannot be set via the httpd.conf file.session_commit / MasonSessionCommit => boolean
Corresponds to the
Commit
parameter given to the DBI-related session modules.session_transaction / MasonSessionTransaction => boolean
Corresponds to the
Transaction
parameter.session_directory / MasonSessionDirectory => directory
Corresponds to the
Directory
parameter given toApache::Session::File
.session_lock_directory / MasonSessionLockDirectory => directory
Corresponds to the
LockDirectory
parameter given toApache::Session::File
.session_file_name / MasonSessionFileName => file name
Corresponds to the
FileName
parameter given toApache::Session::DB_File
.session_store / MasonSessionStore => class
Corresponds to the
Store
parameter given toApache::Session::Flex
.session_lock / MasonSessionLock => class
Corresponds to the
Lock
parameter given toApache::Session::Flex
.session_generate / MasonSessionGenerate => class
Corresponds to the
Generate
parameter given toApache::Session::Flex
.session_serialize / MasonSessionSerialize => class
Corresponds to the
Serialize
parameter given toApache::Session::Flex
.session_textsize / MasonSessionTextsize => size
Corresponds to the
textsize
parameter given toApache::Session::Sybase
.session_long_read_len / MasonSessionLongReadLen => size
Corresponds to the
LongReadLen
parameter given toApache::Session::MySQL
.session_n_sems / MasonSessionNSems => number
Corresponds to the
NSems
parameter given toApache::Session::Lock::Semaphore
.session_semaphore_key / MasonSessionSemaphoreKey => key
Corresponds to the
SemaphoreKey
parameter given toApache::Session::Lock::Semaphore
.session_mod_usertrack_cookie_name / MasonSessionModUsertrackCookieName => name
Corresponds to the
ModUsertrackCookieName
parameter given toApache::Session::Generate::ModUsertrack
.session_save_path / MasonSessionSavePath => path
Corresponds to the
SavePath
parameter given toApache::Session::PHP
.
HOW COOKIES ARE HANDLED
When run under the ApacheHandler module, 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 it can only set cookies if it is running under either the ApacheHandler or the CGIHandler module. Otherwise, the MasonX::Request::WithApacheSession
request object has no way to get to an object which can take the headers. In other words, if there's no $r
, there's nothing with which to set headers.
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.
Bug reports and requests for help should be sent to the mason-users list. See http://www.masonhq.com/resources/mailing_lists.html for more details.
AUTHOR
Beau E. Cox <mason@beaucox.com> http://beaucox.com.
The real authors (I just made mod_perl2 changes) is Dave Rolsky, <autarch@urth.org>
Version 0.01 as of January, 2004.
SEE ALSO
My documents, including: HOWTO Run Mason with mod_perl2, MasonX::Apache2Handler, MasonX::Request::WithMulti2Session,
Original Mason documents, including: HTML::Mason::ApacheHandler, MasonX::Request::WithApacheSession, MasonX::Request::WithMultiSession.
Also see the Mason documentation at http://masonhq.com/docs/manual/.