A callback hook (also known simply as a callback) is a reference to a subroutine. In Perl, we create subroutine references with the following syntax:

$callback = \&subroutine;

In this example, $callback contains a reference to the subroutine called subroutine. Another way to create a callback is to use an anonymous subroutine:

$callback = sub { 'some code' };

Here, $callback contains a reference to the anonymous subroutine. Callbacks are used when we want some action (subroutine call) to occur when some event takes place. Since we don't know exactly when the event will take place, we give the event handler a reference to the subroutine we want to be executed. The handler will call our subroutine at the right time, effectively calling back that subroutine.

By default, most of the callback hooks except for PerlHandler, PerlChildInitHandler, PerlChildExitHandler, PerlConnectionApi, and PerlServerApi are turned off. You may enable them via options to Makefile.PL.

Here is the list of available hooks and the parameters that enable them. The Apache request prcessing phases were explained in Chapter 1.

Directive/Hook              Configuration Option
--------------------------------------------------------
PerlPostReadRequestHandler  PERL_POST_READ_REQUEST
PerlTransHandler            PERL_TRANS
PerlInitHandler             PERL_INIT
PerlHeaderParserHandler     PERL_HEADER_PARSER
PerlAuthenHandler           PERL_AUTHEN
PerlAuthzHandler            PERL_AUTHZ
PerlAccessHandler           PERL_ACCESS
PerlTypeHandler             PERL_TYPE
PerlFixupHandler            PERL_FIXUP
PerlHandler                 PERL_HANDLER
PerlLogHandler              PERL_LOG
PerlCleanupHandler          PERL_CLEANUP
PerlChildInitHandler        PERL_CHILD_INIT
PerlChildExitHandler        PERL_CHILD_EXIT
PerlDispatchHandler         PERL_DISPATCH

As with any parameters that are either defined or not, use OPTION_FOO=1 to enable them (e.g., PERL_AUTHEN=1).

To enable all callback hooks, use:

ALL_HOOKS=1

There are a few more hooks that won't be enabled by default, because they are experimental.

If you are using:

panic% perl Makefile.PL EVERYTHING=1 ...

it already includes the ALL_HOOKS=1 option.