B.18.1. Apache::Session—Maintain Session State Across HTTP Requests
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.
B.18.2. Apache::RequestNotes—Easy, Consistent Access to Cookie and Form Data Across Each Request Phase
Apache::RequestNotes provides a simple interface
allowing all phases of the request cycle
access to cookie or form input parameters in a consistent manner.
Behind the scenes, it uses libapreq
(Apache::Request) functions to parse request data
and puts references to the data in pnotes( ).
Once the request is past the PerlInitHandler
phase, all other phases can have access to form input and cookie data
without parsing it themselves. This relieves some strain, especially
when the GET or POST data is
required by numerous handlers along the way.
Available from CPAN. See the module manpage for more information.
B.18.3. Apache::Cookie—HTTP Cookies Class
The Apache::Cookie module is a Perl interface
to the cookie routines in
libapreq. The interface is based on the
CGI::Cookie module.
Available from CPAN. See the module manpage for more information.
B.18.4. Apache::Icon—Look Up Icon Images
This module rips out the icon guts
of mod_autoindex and provides a Perl
interface for looking up icon images. The motivation is to piggy-back
the existing AddIcon and related directives for
mapping file extensions and names to icons, while keeping things as
small and fast as mod_autoindex does.
Available from CPAN. See the module manpage for more information.
B.18.5. Apache::Include—Utilities for mod_perl/mod_include Integration
The Apache::Include module provides
a handler, making it simple to include
Apache::Registryscripts with the mod_include Perl
directive.
Apache::Registryscripts can also be used in
mod_include-parsed documents using a virtual
include.
The virtual( ) method may be called to include the
output of a given URI in your Perl scripts. For example:
use Apache::Include ( );
print "Content-type: text/html\n\n";
print "before include\n";
my $uri = "/perl/env.pl";
Apache::Include->virtual($uri);
print "after include\n";
The output of the perl CGI script located at
/perl/env.pl will be inserted between the
"before include" and
"after include" strings and printed
to the client.
Supplied with the mod_perl distribution. See the module manpage for
more information.
B.18.6. Apache::Language—Perl Transparent Language Support for Apache Modules and mod_perl Scripts
The goal of this module is to provide
a simple way for mod_perl module writers
to include support for multiple language requests.
An Apache::Language object acts like a
language-aware hash. It stores key/language/value triplets. Using the
Accept-Language header field sent by the web
client, it can choose the most appropriate language for the client.
Its usage is transparent to the client.
Available from CPAN. See the module manpage for more information.
B.18.7. Apache::Mmap—Perl Interface to the mmap(2) System Call
The Apache::Mmap module lets you use
mmap to map in a file as a Perl variable
rather than reading the file into dynamically allocated memory. It
works only if your OS supports Unix or POSIX.1b mmap(
). Apache::Mmap can be used just like
Mmap under mod_perl.
Available from CPAN. See the module manpage for more information.
B.18.8. Apache::GD::Graph—Generate Graphs in an Apache Handler
The primary purpose of this module is
to provide a very easy-to-use,
lightweight, and fast charting capability for static pages, dynamic
pages, and CGI scripts, with the chart-creation process abstracted
and placed on any server.
Available from CPAN. See the module manpage for more information.
B.18.9. Apache::Motd—Provide motd (Message of the Day) Functionality to a Web Server
This module provides an alternative and
more efficient method of notifying your
web users of potential downtime or problems affecting your web server
and web services.
Available from CPAN. See the module manpage for more information.
B.18.10. Apache::ParseLog—Object-Oriented Perl Extension for Parsing Apache Log Files
Apache::ParseLog provides an easy way to
parse the Apache log files, using
object-oriented constructs. The module is flexible, and the data it
generates can be used for your own applications (CGI scripts, simple
text-only report generators, feeding an RDBMS, data for Perl/Tk-based
GUI applications, etc.).
Available from CPAN. See the module manpage for more information.
B.18.11. Apache::RegistryLoader—Compile Apache::Registry Scripts at Server Startup
Supplied with the mod_perl
distribution. See the module manpage for
more information.
B.18.13. Apache::TempFile—Allocate Temporary Filenames for the Duration of a Request
This module provides unique
paths for temporary files and ensures
that they are removed when the current request is completed.
Available from CPAN. See the module manpage for more information.
B.18.14. Xmms—Perl Interface to the xmms Media Player
A collection of Perl interfaces
for
the xmms media player. Includes a module that
allows you to control xmms from the browser.
mod_perl generates a page with an index of available MP3 files and
control buttons. You click on the links and xmms
plays the files for you.
Available from CPAN. See the module manpage for more information.
B.18.15. Module::Use—Log and Load Used Perl Modules
Module::Use records the modules
used over the
course of the Perl interpreter's lifetime. If the
logging module is able, the old logs are read and frequently used
modules are loaded automatically.
For example, if configured as:
<Perl>
use Module::Use (Counting, Logger => "Debug");
</Perl>
PerlChildExitHandler Module::Use
it will record the used modules only when the child exists, logging
everything (debug level).
