cvs commit: modperl-site/faq mod_perl_api.pod

[fd...@hyperreal.org]

fdc         99/02/09 12:42:28

  Modified:    faq      mod_perl_api.pod
  Log:
  Mention $r->set_handlers(..=>undef) and PerlSetEnv.
  
  Revision  Changes    Path
  1.3       +30 -1     modperl-site/faq/mod_perl_api.pod
  
  Index: mod_perl_api.pod
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/faq/mod_perl_api.pod,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- mod_perl_api.pod	1998/05/30 20:29:20	1.2
  +++ mod_perl_api.pod	1999/02/09 20:42:25	1.3
  @@ -1,6 +1,6 @@
   =head1 NAME
   
  -Mod_perl_api - accessing the Apache API via mod_perl ($Date: 1998/05/30 20:29:20 $)
  +Mod_perl_api - accessing the Apache API via mod_perl ($Date: 1999/02/09 20:42:25 $)
   
   =head1 DESCRIPTION
   
  @@ -115,3 +115,32 @@
     <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.