Perl in a Nutshell, 2nd Edition

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 or hostname and IP address. Once the user has passed inspection, the server figures out the 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. That is, if Apache doesn’t find handlers you’ve told it to use, it knows to use its own. For example, if you’ve enabled CGI programs in httpd.conf, Apache knows to execute programs that live in cgi-bin if it encounters the cgi-script directive:

<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), assign the SetHandler directive to perl-script, and the mod_perl-specific PerlHandler directive to a special Perl module called Apache::Registry:

SetHandler ...