NAME
Apache::Dispatch - call PerlHandlers with the ease of CGI scripts
SYNOPSIS
httpd.conf:
PerlModule Apache::Dispatch
PerlFixupHandler Apache::Dispatch
DispatchMode Safe
DispatchMethod Handler
DispatchAllow Custom
DispatchDeny Apache Protected
<Location /Foo>
PerlModule Bar
DispatchBase Bar
DispatchMethod Prefix
</Location>DESCRIPTION
Apache::Dispatch translates $r->uri into a class and method and runs it as a PerlHandler. Basically, this allows you to call PerlHandlers as you would CGI scripts - directly from the browser - without having to load your httpd.conf with a slurry of <Location> tags.
EXAMPLE
there are two ways of configuring Apache::Dispatch:
per-server: in httpd.conf:
PerlModule Apache::Dispatch
PerlFixupHandler Apache::Dispatch
DispatchMode Safe
DispatchMethod Handler
DispatchAllow Test
in browser:
http://localhost/Foo
the results are the same as if your httpd.conf looked like:
<Location /Foo>
SetHandler perl-script
PerlHandler Foo
</Location>per-location: in httpd.conf
PerlModule Apache::Dispatch
PerlModule Bar
<Location /Foo>
PerlFixupHandler Apache::Dispatch
DispatchBase Bar
DispatchMethod Prefix
</Location>
in browser:
http://localhost/Foo/baz
the results are the same as if your httpd.conf looked like:
<Location /Foo>
SetHandler perl-script
PerlHandler Bar::dispatch_baz
</Location>
The per-location configuration offers additional security and
protection by hiding both the name of the package and method from
the browser. Because any class under the Bar:: hierarchy can be
called, one <Location> directive is be able to handle all the
methods of Bar, Bar::Baz, etc...CONFIGURATION DIRECTIVES
DispatchBase
Applies on a per-location basis only. The base class to be
substituted for the $r->location part of the uri.
DispatchMethod
Applies on a per-server or per directory basis. Each directory
or virtual host will inherit the value of the server if it does
not specify a method itself. It accepts the following values:
Handler - Assume the method name is handler(), for example
/Foo/Bar becomes Foo::Bar->handler().
This is the default value outside of <Location>
directives configured with DispatchBase.
Prefix - Assume the method name is the last part of the
uri and prefix dispatch_ to the method name.
/Foo/Bar becomes Foo->dispatch_bar().
This is the default value within <Location>
directives configured with DispatchBase.
Determine - The method may either be handler() or the last part
of the uri prefixed with dispatch_. The method
will be determined by first trying dispatch_method()
then by trying handler().
DispatchMode
Applies on a per-server basis, except where a <Location> directive
is using DispatchBase. Values of the main server will be inherited
by each virtual host. It accepts the following values:
Safe - Allow only those methods whose namespace is
explicitly allowed by DispatchAllow and explicitly
not denied by DispatchDeny. This is the default.
Brave - Allow only those methods whose namespace is
explicitly not denied by DispatchAllow. This is
primarily intended for development and ought to
work quite nicely with Apache::StatINC. Its
security is not guaranteed.
DispatchAllow
A list of namespaces allowed to be dispatched according to the
above DispatchMethod and DispatchMode rules. Applies on a
per-server basis, except where a <Location> directive is using
DispatchBase. Values of the main server will be inherited by each
virtual host.
DispatchDeny
A list of namespaces denied dispatch according to the above
DispatchMethod and DispatchMode rules. Applies on a per-server
basis, except where a <Location> directive is using DispatchBase.
Values of the main server will be inherited by each virtual host.NOTES
There is no require()ing or use()ing of the packages or methods prior to their use as a PerlHandler. This means that if you try to dispatch a method without a PerlModule directive or use() entry in your startup.pl you probably will not meet with much success. This adds a bit of security and reminds us we should be pre-loading that code in the parent process anyway...
Apache::Dispatch tries to be a bit intelligent about things. If, by the time it reaches the fixup phase, the uri can be mapped to a real file, directory, or <Location> tag (other than one containing a DispatchBase directive), Apache::Dispatch declines to handle the request.
If the uri can be dispatched but contains anything other than [a-zA-Z0-9_/-] Apache::Dispatch declines to handle the request.
DispatchDeny always includes the following namespaces: AUTOLOAD CORE SUPER UNIVERSAL
Like everything in perl, the package names are case sensitive.
Verbose debugging is enabled by setting $Apache::Dispatch::DEBUG=1. Very verbose debugging is enabled at 2. To turn off all debug information set your apache LogLevel directive above info level.
This is alpha software, and as such has not been tested on multiple platforms or environments for security, stability or other concerns. It requires PERL_FIXUP=1, PERL_LOG_API=1, PERL_HANDLER=1, and maybe other hooks to function properly.
FEATURES/BUGS
No known bugs or features at this time...
SEE ALSO
perl(1), mod_perl(1), Apache(3)
AUTHOR
Geoffrey Young <geoff@cpan.org>
COPYRIGHT
Copyright 2000 Geoffrey Young - all rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.