This is the most important chapter of this book. In this chapter, we
cover all the nuances the programmer should know when porting an
existing CGI script to work under mod_perl, or when writing one from
scratch.
This chapter's main goal is to teach the reader how
to think in mod_perl. It involves showing most of the mod_perl
peculiarities and possible traps the programmer might fall into. It
also shows you some of the things that are impossible with vanilla
CGI but easily done with mod_perl.
6.1. Before You Start to Code
There are three important things you need to know before you start
your journey in a mod_perl world: how to access mod_perl and related
documentation, and how to develop your Perl code when the
strict and warnings modes are
enabled.
6.1.1. Accessing Documentation
mod_perl
doesn't
tolerate sloppy programming. Although we're
confident that you're a talented, meticulously
careful programmer whose programs run perfectly every time, you still
might want to tighten up some of your Perl programming practices.
In this chapter, we include discussions that rely on prior knowledge
of some areas of Perl, and we provide short refreshers where
necessary. We assume that you can already program in Perl and that
you are comfortable with finding Perl-related information in books
and Perl documentation. There are many Perl books that you may find
helpful. We list some of these in Section 6.13 at the end
of each chapter.
If you prefer the
documentation that comes with
Perl, you can use either its online version (start at http://www.perldoc.com/ or http://theoryx5.uwinnipeg.ca/CPAN/perl/) or
the perldoc utility, which provides access to the
documentation installed on your system.
To find out what Perl manpages
are available, execute:
panic% perldoc perl
For example, to find what
functions Perl has and to learn about
their usage, execute:
panic% perldoc perlfunc
To learn the
syntax and to find examples of a
specific function, use the -f flag and the name
of the function. For example, to learn more about open(
), execute:
panic% perldoc -f open
The perldoc supplied with Perl versions prior to
5.6.0 presents the information in POD (Plain Old Documentation)
format. From 5.6.0 onwards, the documentation is shown in manpage
format.
You may find the
perlfaq
manpages
very useful, too. To find all the FAQs (Frequently Asked Questions)
about a function, use the -q flag. For example,
to search through the FAQs for the open( )
function, execute:
panic% perldoc -q open
This will show you all the relevant question and
answer sections.
Finally, to learn about perldoc itself, refer to
the perldoc
manpage:
panic% perldoc perldoc
The documentation available through perldoc
provides good information and examples, and should be able to answer
most Perl questions that arise.
Chapter 23 provides more information about mod_perl
and related documentation.
6.1.2. The strict Pragma
We're sure you
already do this, but
it's absolutely essential to start all your scripts
and modules with:
use strict;
It's especially important to have the
strict pragma enabled under mod_perl. While
it's not required by the language, its use cannot be
too strongly recommended. It will save you a great deal of time. And,
of course, clean scripts will still run under mod_cgi!
In the rare cases where it is necessary, you can turn off the
strict pragma, or a part of it, inside a block.
For example, if you want to use symbolic references (see the
perlref manpage) inside a particular block, you
can use no strict
'refs';, as follows:
use strict;
{
no strict 'refs';
my $var_ref = 'foo';
$$var_ref = 1;
}
Starting the block with no strict 'refs'; allows
you to use symbolic references in the rest of the block. Outside this
block, the use of symbolic references will trigger a runtime error.
6.1.3. Enabling Warnings
It's
also important to develop your code with Perl
reporting every possible relevant warning. Under mod_perl, you can
turn this mode on globally, just like you would by using the
-w command-line switch to Perl. Add this
directive to httpd.conf:
PerlWarn On
In Perl 5.6.0 and later, you can also enable warnings only for the
scope of a file, by adding:
use warnings;
at the top of your code. You can turn them off in the same way as
strict for certain blocks. See the
warnings manpage for more information.
We will talk extensively about warnings in many sections of the book.
Perl code written for mod_perl should run without generating any
warnings with both the strict and
warnings pragmas in effect (that is, with
use strict and
PerlWarn On or
use warnings).
Warnings are almost always caused by errors in your code, but on some
occasions you may get warnings for totally legitimate code.
That's part of why they're warnings
and not errors. In the unlikely event that your code really does
reveal a spurious warning, it is possible to switch off the warning.
