NAME

Apache::Fake - fake a mod_perl request object

VERSION

This document refers to version 0.9 of Apache::Fake, released November 22, 2001.

SYNOPSIS

Case 1: Using a CGI script as Apache SetHandler

/cgi-bin/nph-modperl-emu.cgi:

#!/usr/bin/perl
use lib '/some/private/lib_path';
use Apache::Fake;
new Apache::Fake('httpd_conf' => '/some/private/httpd.conf',
	'dir_conf' => '.htaccess.emu');

In your httpd.conf or .htaccess, add something like this:

Action modperl-emu /cgi-bin/nph-modperl-emu.cgi
SetHandler modperl-emu

Access page just like under mod_perl. (http://host/real/page/here.html)

Case 2: Exclusively using PATH_INFO

/cgi-bin/nph-modperl-emu.cgi:

	#!/usr/bin/perl
	use lib '/some/private/lib_path';
	use Apache::Fake;

        new Apache::Fake('httpd_conf' => '/some/private/httpd.conf',
    		'dir_conf' => '.htaccess.emu',
    		'handler_cgi' => '/cgi-bin/nph-modperl-emu.cgi',
    		'virtual_root' => '/some/private/document_root');

Access page like: http://host/cgi-bin/nph-modperl-emu.cgi/real/page/here.html

DESCRIPTION

This module fakes a mod_perl request object using the Common Gateway Interface. Everything that works with mod_perl should work with Apache::Fake as well. Apache::Fake parses apache-style config files for any relevant settings. A working mod_perl configuration should work without any modifications given all relevant config files are found. If not, you've found a bug.

Apache::Fake currently emulates the following modules: Apache, Apache::Request, Apache::Table, Apache::Log, mod_perl. Re-use-ing these modules will do no harm, since Apache::Fake sets %INC for these modules.

For documentation, refer to the mod_perl documentation.

Things planned, but not yet working, are: Subrequests, other handlers than PerlHandler, internal_redirect, custom_response, $r->handler().

Things that never will work are: $->get_basic_auth_pw, $r->note_basic_auth_failure.

CONSTRUCTOR

new Apache::Fake([option => value, ...])

The constructor will parse an apache-style config file to retrieve any relevant settings, like PerlHandler and PerlSetVar. It will also obey local .htaccess-style config files. You can use the 'real' config files or provide your own, stripped down versions. The most useful configuration is to use the 'real' httpd.conf, but fake .htaccess files, so you can provide PerlSetVar and PerlHandler even if the web server does not recognize these keywords.

The following settings are used:

httpd_conf => '/etc/apache/httpd.conf'

Path to the main config file. Default is undef, i.e. not used. Neccessary for some subrequest functions.

dir_conf => '.htaccess'

File name of the per-directory config file. Default is '.htaccess'. Only PerlSetVar, PerlModule and PerlHandler are used. <Files> sections are currently ignored.

Caveat: The algorithm searching for a matching file will ascend the physical path, not the logical. So it might miss some files, and find additional ones. This can be considered a feature.

One of these two files is neccessary, since you need a PerlHandler directive.

handler_cgi => '/cgi-bin/nph-mod_perl-handler.cgi'

URI of the handler script. If this parameter is given, 'virtual_root' must be set as well, and Apache::Fake operates in PATH_INFO mode. In this mode, all URLs go like: http://host/cgi-bin/nph-mod_perl-handler.cgi/real/path.

virtual_root => '/home/siteX/modperl_docs'

Path to the virtual root directory of your mod_perl documents/scripts. This directory contains all files accessed through Apache::Fake. It should not be inside your normal document root.

WARNING

This is alpha-quality software. It works for me and for some moderately complex perl modules (the HTML::Mason suite). Not every aspect was tested or checked for strict compatibility to mod_perl 1.27. Please report any problems you find.

TO DO

• Emulate Perl*Handlers by calling them in sequence

• Emulate handler() by emulating some common handlers

• Emulate subrequests and redirects by doing our own URI->filename mapping. Then PerlTransHandlers will work, too.

• Emulate custom_response via previous mapping

• Emulate internal redirects via previous mapping

REQUIRED

perl 5.6.0, Apache::ConfigFile, CGI, CGI::Carp, HTTP::Status

ACKNOWLEDGEMENTS

This module was inspired by a posting on the HTML::Mason mailing list by Alexey Tourbin (alexey_tourbin@mail.ru) and Apache::Emulator by Nigel Wetters (nwetters@cpan.org), both of which were very limited in function. Some ideas have been borrowed from both sources.

AUTHOR

Jörg Walter <ehrlich@ich.bin.kein.hoschi.de>.

VERSION

0.9

SEE ALSO

Apache, Apache::Request

cpanm Apache::Fake

perl -MCPAN -e shell
install Apache::Fake