Chapter 7: Using Mason with mod_perl
While Mason can be used in any text generation context, it is most
frequently used to create dynamic web sites. As you probably know,
executing Perl (or anything else for that matter) as a CGI can be very slow.
Mason, because it is not a small amount of code, can be sluggish when run
as a CGI under heavy loads.
To that end, Mason has been designed to play nice when run under
mod_perl. In fact, Mason has quite a number of features that make it
nicely suited to running under mod_perl.
This chapter assumes that you are familiar with Apache, particularly
Apache's configuration files, and with mod_perl. If you're not, here's a
teaser: mod_perl embeds a Perl interpreter inside the Apache web server.
Because Perl is already loaded, no external processes need to be launched to
serve Perl-generated content. mod_perl also allows many server tasks to
be configured and executed using Perl, which can be a great convenience.
More information on Apache can be found via the Apache web site at
/>, as well as in O'Reilly's Apache: The Definitive
Guide, 3rd Edition (Ben and Peter Laurie, 2003).
For more information on mod_perl, the mod_perl site at
/> is useful, as is Stas Bekman's fabulous mod_perl
guide, which can be found at the same location. Also useful is Writing
Apache Modules with Perl and C (the "Eagle Book") by Lincoln Stein and
Doug MacEachern, also published by O'Reilly.
1
Despite the title, it is really
primarily about mod_perl.
A recent book from Sams Publishing, The mod_perl Developer's Cookbook
by Geoffrey Young, Paul Lindner, and Randy Kobes, is also an extremely
valuable resource for anyone who's going to spend a significant amount of
time working with mod_perl. It fills a different niche in the developer's
mental toolkit.

PerlContentHandler . Here is the simplest possible configuration:
SetHandler perl-script
PerlHandler HTML::Mason::ApacheHandler
The SetHandler directive just tells Apache to use mod_perl for this
request. The PerlHandler directive is provided by mod_perl, and it
tells Apache that the given module is a content handler. This means that the
module will respond to the request and generate content to be sent to the
client.
Putting the previous snippet in your configuration file will cause every file
your web server processes to be handled by Mason. This is probably not
what you want most of the time, so let's narrow it down a bit:
<Location /mason>
PerlSetVar MasonCompRoot
/path/to/doc/root/mason
SetHandler perl-script
PerlHandler HTML::Mason::ApacheHandler
</Location>
This tells Apache that only requests that have a path starting with /mason
will be handled by Mason. We've narrowed down the component root
correspondingly, though this is not required. In fact, it's important to realize
that component root and document root are not the same thing. There will be
more on this later.
Alternately, we might want to specify that only certain file extensions will
be handled by Mason:
AddType text/html .mhtml
<LocationMatch "\.mhtml$">
SetHandler perl-script
PerlHandler HTML::Mason::ApacheHandler
</LocationMatch>
The first directive tells Apache that files ending with .mhtml have a content-

<VirtualHost 1.2.3.4>
ServerName www.example.com
DocumentRoot /home/example/htdocs/
PerlSetVar MasonCompRoot /home/example/htdocs
PerlSetVar MasonDataDir /home/example/mason-
data
<LocationMatch "\.mhtml$">
SetHandler perl-script
PerlHandler HTML::Mason::ApacheHandler
</LocationMatch>
</VirtualHost>

<VirtualHost 1.2.3.4
> ServerName hello-kitty-heaven.example.com
DocumentRoot /home/hello-kitty/htdocs/
PerlSetVar MasonCompRoot /home/hello-
kitty/htdocs/mason
PerlSetVar MasonDataDir /home/hello-
kitty/mason-data

<LocationMatch "\.mhtml$">
SetHandler perl-script
PerlHandler HTML::Mason::ApacheHandler
</LocationMatch>
</VirtualHost>
In this case, Mason will find the relevant configuration directives when
asked to handle a request.
When you have only a single Mason configuration for your server, Mason
will attempt to create the objects it needs as early as possible, during the
initial server startup.

file:
PerlRequire handler.pl

<LocationMatch "\.mhtml$">
SetHandler perl-script
PerlHandler MyMason::MyApp
</LocationMatch>
Notice the lack of PerlSetVar directives this time. Also note that the
value given to the PerlHandler directive is now the package you
declared in the handler.pl
file. This combination of script and Apache
configuration would give us the exact same results as in the previous section.
Let's go through this in more detail to understand exactly what it is doing.
Starting with the Apache configuration piece, we see that we set
PerlHandler to MyMason::MyApp. This tells mod_perl to look for a
subroutine called handler() in the MyMason::MyApp namespace.
Mason does not include any such thing, so we have to write it ourselves,
which is what the script does.