This module provides mod_perl with a mechanism for storing persistent user data in a global hash, which is independent of the underlying storage mechanism. Currently it supports storage in standard files, DBM files, or a relational database using DBI. Read the manpage of the mechanism you want to use for a complete reference.

Apache::Session provides persistence to a data structure. The data structure has an ID number, and you can retrieve it by using the ID number. In the case of Apache, you would store the ID number in a cookie or the URL to associate it with one browser, but how you handle the ID is completely up to you. The flow of things is generally:

Tie a session to Apache::Session.
Get the ID number.
Store the ID number in a cookie.
End of Request 1.

(time passes)

Get the cookie.
Restore your hash using the ID number in the cookie.
Use whatever data you put in the hash.
End of Request 2.

Using Apache::Session is easy: simply tie a hash to the session object, put any data structure into the hash, and the data you put in automatically persists until the next invocation. Example B-1 is an example that uses cookies to track the user's session.

Example B-1. session.pl

# pull in the required packages
use Apache::Session::MySQL;
use Apache;

use strict;

# read in the cookie if this is an old session
my $r = Apache->request;
my $cookie = $r->header_in('Cookie');
$cookie =~ s/SESSION_ID=(\w+)/$1/;

# create a session object based on the cookie we got from the
# browser, or a new session if we got no cookie
my %session;
eval {
    tie %session, 'Apache::Session::MySQL', $cookie,
        {DataSource => 'dbi:mysql:sessions',
         UserName   => $db_user,
         Password   => $db_pass,
         LockDataSource => 'dbi:mysql:sessions',
         LockUserName   => $db_user,
         LockPassword   => $db_pass,
        };
};
if ($@) {
    # could be a database problem
    die "Couldn't tie session: $@";
}

# might be a new session, so let's give them their cookie back
my $session_cookie = "SESSION_ID=$session{_session_id};";
$r->header_out("Set-Cookie" => $session_cookie);

After %session is tied, you can put anything but file handles and code references into $session{_session_id};, and it will still be there when the user invokes the next page.

It is possible to write an Apache authentication handler using Apache::Session. You can put your authentication token into the session. When a user invokes a page, you open his session, check to see if he has a valid token, and authenticate or forbid based on that.

An alternative to Apache::Session is Apache::ASP, which has session-tracking abilities. HTML::Embperl hooks into Apache::Session for you.

Available from CPAN. See the module manpage for more information.