[Chapter 11] 11.3 mod_perl Handlers
Author: Ellen Siever, Stephen Spainhour & Nathan Patwardhan
Date: 1999-07-02T01:56:03Z

#

| Chapter 11 Web Server Programming with mod_perl |

## 11.3 mod_perl Handlers

To understand mod_perl, you should understand how the Apache server works. When Apache receives a request, it processes it in several stages. First, it translates the URL to the associated resource (i.e., filename, CGI script, etc.) on the server machine. Then it checks to see if the user is authorized to access that resource, perhaps by requesting and checking an ID and password. Once the user has passed inspection, the server figures out what kind of data it's sending back (e.g., it decides a file ending in .html is probably a `text/html` file), creates some headers, and sends those headers back to the client with the resource itself. When all is said and done, the server makes a log entry.

At each stage of this process, Apache looks for routines to "handle" the request. Apache supplies its own handlers; for example, one of the default handlers is `cgi-script`, often seen applied to /cgi-bin:

>     <Location /cgi-bin>
>       ...
>     SetHandler cgi-script
>       ...
>     </Location\>

mod_perl allows you to write your own handlers in Perl, by embedding the Perl runtime library directly into the Apache httpd server executable. To use mod_perl for CGI (which is all that most people want to do with it), you assign the `SetHandler` directive to `perl-script`, and then assign the mod_perl-specific `PerlHandler` directive to a special Perl module called Apache::Registry.

>     SetHandler perl-script
>     PerlHandler Apache::Registry

`PerlHandler` is the mod_perl handler for the content retrieval stage of the transaction.

To use other handlers, you don't need to reassign `SetHandler`. For example, to identify a handler for the logging stage of the request:

>     <Location /snoop/>
>     PerlLogHandler Apache::DumpHeaders
>     </Location\>

In order for this to work, mod_perl must have been built with the logging hooks enabled (as described in the previous section), and the Apache::DumpHeaders module must have been installed. mod_perl looks in Apache::DumpHeaders for a routine called `handler()` and executes it as the logging handler for that resource.

The following is a list of each of the handler directives that can be enabled by mod_perl, and the stages that each is used for. Only `PerlHandler` is enabled by default.

Handler | Purpose
--- | ---
`PerlAccessHandler` | Access stage
`PerlAuthenHandler` | Authentication stage
`PerlAuthzHandler` | Authorization stage
`PerlChildInitHandler` | Child initialization stage
`PerlChildExitHandler` | Child termination stage
`PerlCleanupHandler` | Cleanup stage
`PerlFixupHandler` | Fixup stage
`PerlHandler` | Response stage
`PerlHeaderParserHandler` | Header-parsing stage
`PerlInitHandler` | Initialization
`PerlLogHandler` | Logging stage
`PerlPostReadRequestHandler` | Post-request stage
`PerlTransHandler` | Translation stage
`PerlTypeHandler` | Type-handling stage

You can write your own handlers for each of these stages. But there are also dozens of modules that you can download from CPAN, some of which are listed at the end of this chapter.

11.2 Installing mod_perl |  | 11.4 Running CGI Scripts with mod_perl