Appendix B. Apache Perl Modules

Development-Stage Modules
Modules to Aid Debugging
Control and Monitoring Modules
Server Configuration Modules
Authentication-Phase Modules
Authorization-Phase Modules
Access-Phase Modules
Type Handlers
Trans Handlers
Fixup Handlers
Generic Content-Generation Modules
Application-Specific Content-Generation Modules
Database Modules
Toolkits and Frameworks for Content-Generation and Other Phases
Output Filters and Layering Modules
Logging-Phase Handlers
Core Apache Modules
Other Miscellaneous Modules

Many third-party modules have been written to extend mod_perl's core functionality. They may be distributed with the mod_perl source code, or they may be available from CPAN. In this chapter we will attempt to group these modules based on their functionality. Some modules will be discussed in depth, but others will be touched on only briefly.

Since most of these modules are continually evolving, the moment this book is published much of the information in it will be out of date. For this reason, you should refer to the modules' manpages when you start using them; that's where you will find the most up-to-date documentation.

We will consider modules in the following groups:

Development: Modules used mainly during the development process
Debugging: Modules that assist in code debugging
Control and monitoring: Modules to help you monitor the production server and take care of any problems as soon as they appear
Server configuration: Modules used in server configuration
Authentication: Modules used to facilitate authentication
Authorization: Modules used to facilitate authorization
Access: Modules used during the access-verification phase
Type handlers: Modules used as PerlTypeHandlers
Trans handlers: Modules used as PerlTransHandlers
Fixup Handlers: Modules used as PerlFixupHandlers
Generic content-generation phase: Generic modules that assist during the content-generation phase
Application-specific content generation phase: Non-general-purpose content generators
Database: Database-specific modules
Toolkits and framework for content generation and other phases: Mostly large toolkits and frameworks built on top of mod_perl
Output filters and layering: Modules that filter output from the content generation stage
Logging-phase handlers: Modules that assist during the logging stage
Core Apache: Modules that interface with core mod_perl
Miscellaneous: Modules that don't fit into any of the above categories

B.1. Development-Stage Modules

The following modules are mainly useful during the code-development cycle. Some of them can also be useful in the production environment.

B.1.1. Apache::Reload—Automatically Reload Changed Modules

Apache::Reload is used to make specific modules reload themselves when they have changed. It's also very useful for mod_perl module development.

Covered in Chapter 6.

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

B.1.2. Apache::PerlVINC—Allow Module Versioning in <Location> and <VirtualHost> blocks

This module makes it possible to have different @INC values for different <VirtualHost>s, <Location>s, and equivalent configuration blocks.

Suppose two versions of Apache::Status are being hacked on the same server. In this configuration:

PerlModule Apache::PerlVINC

<Location /status-dev/perl>
    SetHandler       perl-script
    PerlHandler      Apache::Status

    PerlINC          /home/httpd/dev/lib
    PerlFixupHandler Apache::PerlVINC
    PerlVersion      Apache/Status.pm
</Location>

<Location /status/perl>
    SetHandler       perl-script
    PerlHandler      Apache::Status

    PerlINC          /home/httpd/prod/lib
    PerlFixupHandler Apache::PerlVINC
    PerlVersion      Apache/Status.pm
</Location>

Apache::PerlVINC is loaded and then two different locations are specified for the same handler Apache::Status, whose development version resides in /home/httpd/dev/lib and production version in /home/httpd/prod/lib.

If a request for /status/perl is issued (the latter configuration section), the fixup handler will internally do:

delete $INC{"Apache/Status.pm"};
unshift @INC, "/home/httpd/prod/lib";
require Apache::Status;

which will load the production version of the module, which will in turn be used to process the request.

If on the other hand the request is for /status-dev/perl (the former configuration section), a different path (/home/httpd/dev/lib) will be prepended to @INC:

delete $INC{"Apache/Status.pm"};
unshift @INC, "/home/httpd/dev/lib";
require Apache::Status;

It's important to be aware that a changed @INC is effective only inside the <Location> block or a similar configuration directive. Apache::PerlVINCsubclasses the PerlRequire directive, marking the file to be reloaded by the fixup handler, using the value of PerlINC for @INC. That's local to the fixup handler, so you won't actually see @INC changed in your script.

Additionally, modules with different versions can be unloaded at the end of the request, using the PerlCleanupHandler:

<Location /status/perl>
    SetHandler         perl-script
    PerlHandler        Apache::Status

    PerlINC            /home/httpd/prod/lib
    PerlFixupHandler   Apache::PerlVINC
    PerlCleanupHandler Apache::PerlVINC
    PerlVersion        Apache/Status.pm
</Location>

Also note that PerlVersion affects things differently depending on where it is placed. If it is placed inside a <Location> or a similar block section, the files will be reloaded only on requests to that location. If it is placed in a server section, all requests to the server or virtual hosts will have these files reloaded.

As you can guess, this module slows down the response time because it reloads some modules on a per-request basis. Hence, this module should be used only in a development environment, not in production.

If you need to do the same in production, a few techniques are suggested in Chapter 4.

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