=head1 NAME

Mod_perl_api - accessing the Apache API via mod_perl ($Date$)

=head1 DESCRIPTION

This part of the mod_perl FAQ deals with the Apache Application
Programmer's Interface and how to access it from perl via mod_perl.

=head1 Why can't the server find the handler I wrote?

=head2 Did you enable the required hook?

As described in the mod_perl/INSTALL document, the only callback hook
enabled by default is PerlHandler.  If you want to intervene at a
different stage of request processing you must enable the relevant
hook.  So to add a special authentication handler, for instance, you
would start the installation process with:

  perl Makefile.PL PERL_AUTHEN=1

=head2 Is the handler correctly referenced in the configuration?

Apache must be told to load your handler, either as a module with the
C<PerlModule> directive or as a script with C<PerlRequire>.  The
handler subroutine will then be available, but you must also specify
which requests it should process.  This is done by naming it in one of
the Perl*Handler directives (PerlInitHandler, PerlTransHandler, etc.).
If this directive is put in access.conf outside of any restrictive
context, your handler will be called during the given phase of each
request processed by the server.  You can make it more selective by
restricting it to a directory (-hierarchy) in a <Directory ...>
section of access.conf or by putting it in a .htaccess file.

Here is an example of the directives needed to call a handler during
Apache's URI to filename translation phase:

  PerlRequire         /full/path/to/script/Trans.pl
  PerlTransHandler   Trans::handler

Trans.pl would start with the statement C<Package Trans;> and define a
subroutine called C<handler>.

=head1 Where can I find examples to get me started?

Check out the Apache-Perl-contrib tarfile at
http://perl.apache.org/src/

Here is an example from Vivek Khera.  It allows you to filter files
through a perl script based on their location.  Rather than having to
invoke a CGI script, the user just references the file with a normal
URL and it is automagically processed by this code...

  #! /usr/local/bin/perl
  use strict;
  
  # filter a file before returning it to the web client
  # tell Apache to use the PerlHandler FileFilter on file which need
  # filtering in the htaccess file:
  #
  # <Files *.baz>
  #  SetHandler  perl-script
  #  PerlHandler FileFilter
  # </Files>
  
  package FileFilter;
  
  use Apache::Constants ':common';
  
  # find out the file name, then write it out with our header attached
  sub handler {
    my $r = shift;
  
    my $fileName = $r->filename;
  
    open(F,$fileName) or return NOT_FOUND; # file not found
  
    $r->content_type('text/html');
    $r->no_cache(1);              # don't be caching my dynamic documents!
  
    $r->send_http_header;
  
    $r->print("<HEAD><TITLE>This is my personal header!</TITLE></HEAD><BODY>");

    # Now copy the file to the client.  If you do not need to make any
    # changes you can copy it verbatim with the single statement
    #    $r->send_fd(\*F);
    # Otherwise, loop over each line...
    while(<F>) {
      # mangle the contents here if you want
      $r->print ($_);
    }
    close(F);
  
    $r->print("<HR>Document created: ", scalar localtime time);
    $r->print("</BODY>");
  
    OK;
  }
  
  1;

=head1 How can I check if mod_perl is available during configuration?

Ralf Engelschall writes:

When you compiled one httpd with and the other without mod_perl, then
you can simply use <IfModule mod_perl.c>...</IfModule> to surround the
stuff for the httpd compiled with mod_perl. The other then ignores
these lines. Example:

  <IfModule mod_perl.c>
  ...stuff for httpd w/ mod_perl...
  </IfModule>
  <IfModule !mod_perl.c>
  ...stuff for httpd w/o mod_perl...
  </IfModule>

=head1 How can I terminate a chain of handlers?

During each phase of request processing, apache calls handlers which
have registered an interest in looking at and possibly handling the
request.  In some phases it makes sense to let all of the handlers
have a chance to look at the request.  In other phases the first
handler to return "OK" terminates that phase (see the Apache
documentation, /manual/misc/API.html).

If you define more than one PerlHandler for a phase, they are placed
on a stack and all of the handlers on the stack are called
sequentially by mod_perl, as long as they return "DECLINED" or "OK".
Apache sees the return code from the final handler and reacts to it.
If a handler wants to terminate the chain and ensure that no other
handler is called after it, it should set the corresponding stack to
undef.  For instance, when a TransHandler has set $r->filename, it
should terminate with

  $r->set_handlers(PerlTransHandler => undef);
  return OK;

=head1 Why can't my handler see an environment variable that I set in httpd.conf?

The configuration directives SetEnv and PassEnv are handled by
apache's mod_env during the fixup stage, so mod_perl handlers that run
prior to the fixup-stage don't see variables set with them.  You can
use PerlSetEnv/PerlPassEnv instead - they are processed as soon as
possible during a request.

=head1 Why does the server hang when I try to read a FORM?

The C<$r-E<gt>content> method reads C<application/x-www-form-urlencoded>
data directly from the client and it does not keep a copy, so if you
(or another handler) call it again, the server will hang.  One way of
avoiding this, if you do not have full control of all the handlers
involved, is to convert the request from POST to GET in the first
handler that reads the content:

    use Apache::Constants qw(M_GET);
    
    sub My::Test::handler {
    	my $r = shift;
    
    	if ($r->method eq 'POST') { 
    	   my $content = $r->content;
    	   # ...
    	   #make sure nobody else tries to read POST data now that we have
    	   $r->method('GET');
    	   $r->method_number(M_GET);
    	   $r->headers_in->unset('Content-length');
    	}
        # ...
    }