Apache::Session::Wrapper - A simple wrapper around Apache::Session
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;
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.
session()
If you're using Mason, you should probably take a look at MasonX::Request::WithApacheSession first, which integrates this module directly into Mason.
MasonX::Request::WithApacheSession
This class provides the following public methods:
new
This method creates a new Apache::Session::Wrapper object.
Apache::Session::Wrapper
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.
Apache::Session::Wrapper::Exception::Params
session
This method returns a hash tied to the Apache::Session class.
Apache::Session
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.
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.
Apache::Session::Flex
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
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
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.
Apache::Session::Wrapper::Exception::NonExistentSessionID
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.
Apache::Cookie
Apache2::Cookie
CGI::Cookie
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.
err_headers_out()
headers_out()
Under mod_perl 1, this will default to the object returned by Apache->request(). Under mod_perl 2 we call Apache2::RequestUtil->request()
Apache->request()
Apache2::RequestUtil->request()
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.
param()
CGI.pm
Apache::Request
These parameters are simply passed through to Apache::Session.
data_source => DSN
Corresponds to the DataSource parameter passed to the DBI-related session modules.
DataSource
user_name => user name
Corresponds to the UserName parameter passed to the DBI-related session modules.
UserName
password => password
Corresponds to the Password parameter passed to the DBI-related session modules. Defaults to undef.
Password
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.
Handle
table_name => table name
Corresponds to the TableName paramaeter passed to DBI-related modules.
TableName
lock_data_source => DSN
Corresponds to the LockDataSource parameter passed to Apache::Session::MySQL.
LockDataSource
lock_user_name => user name
Corresponds to the LockUserName parameter passed to Apache::Session::MySQL.
LockUserName
lock_password => password
Corresponds to the LockPassword parameter passed to Apache::Session::MySQL. Defaults to undef.
LockPassword
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.
LockHandle
handle
commit => boolean
Corresponds to the Commit parameter passed to the DBI-related session modules.
Commit
transaction => boolean
Corresponds to the Transaction parameter.
Transaction
directory => directory
Corresponds to the Directory parameter passed to Apache::Session::File.
Directory
lock_directory => directory
Corresponds to the LockDirectory parameter passed to Apache::Session::File.
LockDirectory
file_name => file name
Corresponds to the FileName parameter passed to Apache::Session::DB_File.
FileName
store => class
Corresponds to the Store parameter passed to Apache::Session::Flex.
Store
lock => class
Corresponds to the Lock parameter passed to Apache::Session::Flex.
Lock
generate => class
Corresponds to the Generate parameter passed to Apache::Session::Flex.
Generate
serialize => class
Corresponds to the Serialize parameter passed to Apache::Session::Flex.
Serialize
textsize => size
Corresponds to the textsize parameter passed to Apache::Session::Sybase.
textsize
long_read_len => size
Corresponds to the LongReadLen parameter passed to Apache::Session::MySQL.
LongReadLen
n_sems => number
Corresponds to the NSems parameter passed to Apache::Session::Lock::Semaphore.
NSems
semaphore_key => key
Corresponds to the SemaphoreKey parameter passed to Apache::Session::Lock::Semaphore.
SemaphoreKey
mod_usertrack_cookie_name => name
Corresponds to the ModUsertrackCookieName parameter passed to Apache::Session::Generate::ModUsertrack.
ModUsertrackCookieName
save_path => path
Corresponds to the SavePath parameter passed to Apache::Session::PHP.
SavePath
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.
Apache::Table
add()
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.
This is done by calling Apache::Session::Wrapper->RegisterClass():
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:
RegisterClass()
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 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".
RegisterFlexClass()
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.
_get_session_id()
This class is a Class::Container subclass, so if you accept additional constructor parameters, you should declare them via the valid_params() method.
Class::Container
valid_params()
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.
Dave Rolsky, <autarch@urth.org>
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.
To install Apache::Session::Wrapper, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache::Session::Wrapper
CPAN shell
perl -MCPAN -e shell install Apache::Session::Wrapper
For more information on module installation, please visit the detailed CPAN module installation guide.