Practical mod_perl, from O'Reilly. | 26

Practical mod_perl: Chapter 6: Coding with mod_perl in Mind

Converting into a Perl Content Handler

Let's now convert this script into a content handler. There are two parts to this task: first configure Apache to run the new code as a Perl handler, then modify the code itself.

First we add the following snippet to httpd.conf:

PerlModule Book::Cookie
<Location /test/cookie>
    SetHandler perl-script
    PerlHandler Book::Cookie
</Location>

and restart the server.

When a request whose URI starts with /test/cookie is received, Apache will execute the Book::Cookie::handler( ) subroutine (which we will look at presently) as a content handler. We made sure we preloaded the Book::Cookie module at server startup with the PerlModule directive.

Now we modify the script itself. We copy its contents to the file Cookie.pm and place it into one of the directories listed in @INC. In this example, we'll use /home/httpd/perl, which we added to @INC. Since we want to call this package Book::Cookie, we'll put Cookie.pm into the /home/httpd/perl/Book/ directory.

The changed code is in Example 6-19. As the subroutines were left unmodified from the original script, they aren't reproduced here (so you'll see the differences more clearly.)

Example 6-19: Book/Cookie.pm

package Book::Cookie;
use Apache::Constants qw(:common);
 
use strict;
use CGI;
use CGI::Cookie;
use vars qw($q $switch $status $sessionID);
 
sub handler {
    my $r = shift;
         
    init(  );
    print_header(  );
    print_status(  );
    
    return OK;
}
 
# all subroutines unchanged
 
1;

Two lines have been added to the beginning of the code:

package Book::Cookie;
use Apache::Constants qw(:common);

The first line declares the package name, and the second line imports constants commonly used in mod_perl handlers to return status codes. In our case, we use the OK constant only when returning from the handler( ) subroutine.

The following code is left unchanged:

use strict;
use CGI;
use CGI::Cookie;
use vars qw($q $switch $status $sessionID);

We add some new code around the subroutine calls:

sub handler {
    my $r = shift;
 
    init(  );
    print_header(  );
    print_status(  );
 
    return OK;
}

Each content handler (and any other handler) should begin with a subroutine called handler( ). This subroutine is called when a request's URI starts with /test/cookie, as per our configuration. You can choose a different subroutine name--for example, execute( )--but then you must explicitly specify that name in the configuration directives in the following way:

PerlModule Book::Cookie
<Location /test/cookie>
    SetHandler perl-script
    PerlHandler Book::Cookie::execute
</Location>

We will use the default name, handler( ).

The handler( ) subroutine is just like any other subroutine, but generally it has the following structure:

sub handler {
    my $r = shift;
 
    # the code
 
    # status (OK, DECLINED or else)
    return OK;
}

First, we retrieve a reference to the request object by shifting it from @_ and assigning it to the $r variable. We'll need this a bit later.

Second, we write the code that processes the request.

Third, we return the status of the execution. There are many possible statuses; the most commonly used are OK and DECLINED. OK tells the server that the handler has completed the request phase to which it was assigned. DECLINED means the opposite, in which case another handler will process this request. Apache::Constants exports these and other commonly used status codes.

In our example, all we had to do was to wrap the three calls:

init(  );
print_header(  );
print_status(  );

inside the handler( ) skeleton:

sub handler {
    my $r = shift;
 
    return OK;
}

Last, we need to add 1; at the end of the module, as we do with any Perl module. This ensures that PerlModule doesn't fail when it tries to load Book::Cookie.

To summarize, we took the original script's code and added the following seven lines:

package Book::Cookie;
use Apache::Constants qw(:common);
 
sub handler {
    my $r = shift;
 
    return OK;
}
1;

and we now have a fully-fledged Perl content handler.

Created: March 27, 2003
Revised: July 23, 2003

URL: https://webreference.com/programming/perl/mod_perl/chap6/3