Writing Apache Modules with Perl and C

4.7. Chaining Content Handlers

The C-language Apache API only allows a single content handler to completely process a request. Several handlers may be given a shot at it, but the first one to return an OK status will terminate the content handling phase of the transaction.

There are times when it would be nice to chain handlers into a pipeline. For example, one handler could add canned headers and footers to the page, another could correct spelling errors, while a third could add trademark symbols to all proprietary names. Although the native C API can't do this yet,^[3] the Perl API can, using a technique called "stacked handlers."

^[3] At the time this was written, the Apache developers were discussing a layered I/O system which will be part of the Apache 2.0 API.

It is actually quite simple to stack handlers. Instead of declaring a single module or subroutine in the PerlHandler directive, you declare several. Each handler will be called in turn in the order in which it was declared. The exception to this rule is if one of the handlers in the series returns an error code (anything other than OK, DECLINED, or DONE). Handlers can adjust the stacking order themselves, or even arrange to process each other's output.

4.7.1. Simple Case of Stacked Handlers

Example 4.20 gives a very simple example of a stack of three content handlers. It's adapted slightly from the mod_perl manual page. For simplicity, all three handlers are defined in the same file, and are subroutines named header() ...