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.