NAME

Apache::Dispatch - call PerlHandlers with the ease of CGI

SYNOPSIS

httpd.conf:

PerlModule Apache::Dispatch
PerlFixupHandler Apache::Dispatch

DispatchMode Safe
DispatchMethod Handler
DispatchAllow Custom
DispatchDeny Apache Protected

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 - from the browser - without having to load your httpd.conf with a slurry of <Location> tags.

EXAMPLE

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>

CONFIGURATION

All configuration directives apply on a per-server basis. Virtual Hosts inherit any directives from the main server or can delcare their own.

DispatchMode    - Safe:       allow only those methods whose
                              namespace is explitily allowed by 
                              DispatchAllow and explitily not
                              denied by DispatchDeny

                  Brave:      allow only those methods whose
                              namespace is explitily not denied by 
                              DispatchDeny 

                  Foolish:    allow any method

DispatchMethod  - Handler:    assume the method name is handler(),
                              meaning that /Foo/Bar becomes
                              Foo::Bar->handler()

                  Subroutine: assume the method name is the last
                              part of the uri - /Foo/Bar becomes
                              Foo->Bar()

                  Determine:  the method may either be handler() or
                              the last part of the uri.  the last
                              part is checked first, so  this has
                              the additional benefit of allowing
                              both /Foo/Bar/handler and /Foo/Bar to
                              to call Foo::Bar::handler().
                              of course, if Foo->Bar() exists, that
                              will be called since it would be found
                              first.

DispatchAllow   - a list of namespaces allowed execution according
                  to the above rules

DispatchDeny    - a list of namespaces denied execution according
                  to the above rules

NOTES

Apache::Dispatch tries to be a bit intelligent about things. If by the time the uri reaches the fixup phase it can be mapped to a real file, directory, or <Location> tag, Apache::Dispatch declines the request.

DispatchDeny always includes the following namespaces: AUTOLOAD CORE SUPER UNIVERSAL

Like everything in perl, the package names are case sensitive relative to $r->uri.

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. It requires PERL_INIT=1, PERL_LOG_API=1, and maybe other hooks to function properly.

FEATURES/BUGS

DispatchDeny and DispatchAllow work, but not quite the way I want. For instance, DispatchDeny Custom will deny to Customer:: methods, while DispatchAllow Custom will allow Custom::Filter->handler() and Custom->filter(), but deny Customer:: methods. I think DistpatchAllow has the proper behavior, but DispatchDeny may need to be changed. Input is welcome.

SEE ALSO

perl(1), mod_perl(1), Apache(3), Apache::ModuleConfig(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.