B.18 Other Miscellaneous Modules

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::Registry scripts with the mod_include Perl directive.

Apache::Registry scripts 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

Covered in Chapter 13.

Supplied with the mod_perl distribution. See the module manpage for more information.

B.18.12 Apache::SIG—Override Apache Signal Handlers with Perl's Signal Handlers

Covered in Chapter 6.

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).