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 CWsession() method.

If you're using Mason, you should probably take a look at CWMasonX::Request::WithApacheSession first, which integrates this module directly into Mason.

This class provides the following public methods:

* new

This method creates a new CWApache::Session::Wrapper object. If the parameters you provide are not correct (wrong type, missing parameters, etc.), this method throws an CWApache::Session::Wrapper::Exception::Params exception. You can treat this as a string if you want.

* session

This method returns a hash tied to the CWApache::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.

This module accepts quite a number of parameters, most of which are simply passed through to CWApache::Session. For this reason, you are advised to familiarize yourself with the CWApache::Session documentation before attempting to configure this module.

* class => class name

The name of the CWApache::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 CWApache::Session writes the session. If it is false, the default CWApache::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 CWApache::Session::Wrapper::Exception::NonExistentSessionID exception will be thrown instead. This defaults to true.

* use_cookie => boolean

If true, then this module will use CWApache::Cookie or CWCGI::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 CWcookie_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 CWApache::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: CWerr_header_out(), CWerr_headers_out(), CWheader_out(), or CWheaders_out(). The pluralized versions are needed to support mod_perl 2. Under mod_perl, this will default to the object returned by CWApache->request. This may not work under mod_perl 2.

* 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 CW$m->session->{_session_id}.

* param_object => object

This should be an object that provides a CWparam() method. This object will be checked to see if it contains the parameter named in params_name. This object will probably be a CWCGI.pm or CWApache::Request object, but it doesn't have to be.

These parameters are simply passed through to CWApache::Session.

* data_source => DSN

Corresponds to the CWDataSource parameter passed to the DBI-related session modules.

* user_name => user name

Corresponds to the CWUserName parameter passed to the DBI-related session modules.

* password => password

Corresponds to the CWPassword parameter passed to the DBI-related session modules. Defaults to undef.

* handle => DBI handle

Corresponds to the CWHandle 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 CWTableName paramaeter passed to DBI-related modules.

* lock_data_source => DSN

Corresponds to the CWLockDataSource parameter passed to CWApache::Session::MySQL.

* lock_user_name => user name

Corresponds to the CWLockUserName parameter passed to CWApache::Session::MySQL.

* lock_password => password

Corresponds to the CWLockPassword parameter passed to CWApache::Session::MySQL. Defaults to undef.

* lock_handle => DBI handle

Corresponds to the CWLockHandle parameter passed to the DBI-related session modules. As with the CWhandle parameter, this cannot be set via the httpd.conf file.

* commit => boolean

Corresponds to the CWCommit parameter passed to the DBI-related session modules.

* transaction => boolean

Corresponds to the CWTransaction parameter.

* directory => directory

Corresponds to the CWDirectory parameter passed to CWApache::Session::File.

* lock_directory => directory

Corresponds to the CWLockDirectory parameter passed to CWApache::Session::File.

* file_name => file name

Corresponds to the CWFileName parameter passed to CWApache::Session::DB_File.

* store => class

Corresponds to the CWStore parameter passed to CWApache::Session::Flex.

* lock => class

Corresponds to the CWLock parameter passed to CWApache::Session::Flex.

* generate => class

Corresponds to the CWGenerate parameter passed to CWApache::Session::Flex.

* serialize => class

Corresponds to the CWSerialize parameter passed to CWApache::Session::Flex.

* textsize => size

Corresponds to the CWtextsize parameter passed to CWApache::Session::Sybase.

* long_read_len => size

Corresponds to the CWLongReadLen parameter passed to CWApache::Session::MySQL.

* n_sems => number

Corresponds to the CWNSems parameter passed to CWApache::Session::Lock::Semaphore.

* semaphore_key => key

Corresponds to the CWSemaphoreKey parameter passed to CWApache::Session::Lock::Semaphore.

* mod_usertrack_cookie_name => name

Corresponds to the CWModUsertrackCookieName parameter passed to CWApache::Session::Generate::ModUsertrack.

* save_path => path

Corresponds to the CWSavePath parameter passed to CWApache::Session::PHP.

When run under mod_perl, this module attempts to first use CWApache::Cookie for cookie-handling. Otherwise it uses CWCGI::Cookie as a fallback.

If it ends up using CWCGI::Cookie then must provide a header_object parameter. The module calls CWerr_header_out() or CWheader_out() on the provided object, using the former if it's available.

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 CW_get_session_id(). In this class, that method is a no-op, but you can override this in a subclass.

This class is a CWClass::Container subclass, so if you accept additional constructor parameters, you should declare them via the CWvalid_params() method.

As can be seen by the number of parameters above, CWApache::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>