|Welcome to the Monastery|
I have been intending to write a full-fledged tutorial for Apache::Session for a while, but still haven't gotten around to it. Though still a work-in-progress, I hope this will be helpful to some people in the meantime. If you have any corrections/suggestions, let me know.
Apache::Session is a Perl module which provides tools for session management.
Session management is primarily used to provide persistent storage of data for a particular user between CGI requests. This requires being able to identify a specific request as belonging to a particular user/session, and linking that user/session to some type of (typically server-side) storage of data.
A few things about Apache::Session may not be obvious:
Here are some things I've learned in the course of using Apache::Session for my own session management needs.
Session ID Generation
When creating a new session, Apache::Session generates a unique ID (using an MD5 hash) which can be used to track the user session.
Apache::Session uses the Storable module for serialization, allowing the storage of complex Perl data structures as session data. This allows your tied session hash to contain references to hashes, arrays, hashes of arrays, arrays of hashes, arrays of arrays, etc.
(Note: The module also provides for the ability to use serialization methods other than Storable.)
Session Data Storage
Apache::Session stores session data using the implementation defined by the particular derived class which is used. Implementations exist for a large number of storage options, including files, various databases, persistent memory, etc.
Session Data Locking
In a multi-user environment (like a web server), multiple users trying to access the data store at one time could cause corruption of the data. Therefore, Apache::Session uses locking mechanisms to protect the data from simultaneous write access.
Session management requires some way of sending a session ID to the client, and having the client send the session ID back with each request, to track which session data to use. Apache::Session does not provide a built-in way to do this, though the documentation does provide simple examples of how you can do this yourself. Standard methods of session tracking include adding the session ID as extra path information or as a GET query string parameter, storing the ID in hidden fields in forms, or using cookies.
(Note: There are also modules on CPAN that wrap Apache::Session to provide session tracking.)
As a general rule, Apache::Session modules do not clean up after themselves. Therefore, it is necessary to create some method for cleaning up old session entries, lock files, etc. One standard way of doing this (on Unix-type operating systems) is to create a cron job to remove old sessions, etc.
The Apache::Session documentation provides examples of how to use an Apache::Session derived class, and each derived class usually provides additional class-specific documentation.
(Note: I may update this document at some point to include some type of usage overview.)
Data Storage Issues
Apache::Session stores changes to session data in memory until the session hash is untied or passes out of scope. It then writes changes to the data store if anything has changed. However, Apache::Session only updates the data store when the top level of the tied hash changes. Therefore, it is sometimes necessary to provide some mechanism for forcing an update. Here is one way:
Several of the Apache::Session modules use the File locking scheme. Since the File locking scheme is dependent on the implementation of the flock function on a specific platform, File locking may not work properly on some platforms. For example, flock is not implemented on the Window 9x OSes, which means you can not use File locking on that platform.
There are several alternative modules for session management on CPAN (many of which merely extend Apache::Session). Since I am comfortable with Apache::Session, and it meets my current needs, I haven't used any of these, though I have looked at a few.
Sherzod Ruzmetov's CGI::Session was originally a front-end to Apache::Session, but is now a standalone module. It provides an object-oriented interface (similar to that of CGI.pm) as well as a tied hash interface (similar to Apache::Session). It also includes (among other features) support for expiring sessions and storing/loading CGI parameters to/from a session.