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 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.

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.

Cookie-Related Parameters

• use_cookie => boolean

  If true, then this module will use Apache::Cookie or CGI::Cookie (as appropriate) 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.

  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 one of the following methods: err_header_out(), err_headers_out(), header_out(), or headers_out(). The pluralized versions are needed to support mod_perl 2.

  Under mod_perl, this will default to the object returned by Apache->request. This may not work under mod_perl 2.

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. 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 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%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>

cpanm Apache::Session::Wrapper

perl -MCPAN -e shell
install Apache::Session::Wrapper