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->request". 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. * 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". * 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%3A Wrapper or via email at [EMAIL PROTECTED] Support questions can be sent to me at my email address, listed below. AUTHOR Dave Rolsky, <[EMAIL PROTECTED]> -- Report problems: http://perl.apache.org/bugs/ Mail list info: http://perl.apache.org/maillist/modperl.html List etiquette: http://perl.apache.org/maillist/email-etiquette.html