Writing Apache Modules with Perl and C

A.8. The Apache::Include Class

This class provides methods to support integration between mod_include and mod_perl. It makes it possible for parsed HTML files (.shtml) to include Apache::Registry scripts with directives like this one:

<!--#perl sub="Apache::Include" arg="/perl/ssi.pl" -->

When this directive is processed by Apache's standard mod_include module, the Apache::Registry script ssi.pl is run and its output incorporated into the page.

Apache::Include provides a method named virtual() for those who wish to include the contents of another document in the output of their Apache::Registry scripts. It is called with two arguments: the URI you wish to incorporate and the current request object. Only local URIs can be included in this way.

Here's an example:

#!/usr/local/bin/perl
use Apache ();
use Apache::Include ();

my $r = Apache->request;
print "Content-type: text/plain\n\n";
print "I am including a document now:\n";
Apache::Include->virtual('/contents.txt', $r);
print "I am done.\n";

See Chapter 7, Perl Server-Side Includes, for more details on using the #perl element with server-side includes.