Writing Apache Modules with Perl and C

7.10. Perl Server-Side Includes

Another feature of mod_perl is that it integrates with the Apache mod_include server-side include (SSI) system. Provided that mod_perl was built with the PERL_SSI option (or with the recommended setting of EVERYTHING=1), the Perl API adds a new #perl element to the standard mod_include server-side include system, allowing server-side includes to call Perl subroutines directly.

The syntax for calling Perl from SSI documents looks like this:

<!--#perl sub="subroutine" args="arguments"-->

The tag looks like other server-side include tags but contains the embedded element #perl. The #perl element recognizes two attributes, sub and args. The required sub attribute specifies the subroutine to be invoked. This attribute must occur only once in the tag. It can be the name of any subroutine already loaded into the server (with a PerlModule directive, for instance) or an anonymous subroutine created on the fly. When this subroutine is invoked, it is passed a blessed Apache request object just as if it were a handler for the response phase. Any text that the subroutine prints will appear on the HTML page.

The optional args attribute can occur once or several times in the tag. If present, args attributes specify additional arguments to be passed to the subroutine. They will be presented to the subroutine in the same order in which they occur in the tag.

Example 7.13 shows a simple server-side include page that uses #perl elements. It has two Perl includes. ...