Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CGI::Application::DispUser(Contributed Perl DocumCGI::Application::Dispatch(3)

       CGI::Application::Dispatch - Dispatch requests to CGI::Application
       based objects

   Out of Box
       Under mod_perl:

	   <Location /app>
	       SetHandler perl-script
	       PerlHandler CGI::Application::Dispatch

       Under normal cgi:

       This would be the instance script for your application, such as

	   use FindBin::Real 'Bin';
	   use lib Bin() . '/../../rel/path/to/my/perllib';
	   use CGI::Application::Dispatch;

   With	a dispatch table
	   package MyApp::Dispatch;
	   use base 'CGI::Application::Dispatch';

	   sub dispatch_args {
	       return {
		   prefix  => 'MyApp',
		   table   => [
		       ''		 => { app => 'Welcome',	rm => 'start' },
		       ':app/:rm'	 => { },
		       'admin/:app/:rm'	 => { prefix   => 'MyApp::Admin' },

       Under mod_perl:

	   <Location /app>
	       SetHandler perl-script
	       PerlHandler MyApp::Dispatch

       Under normal cgi:

       This would be the instance script for your application, such as

	   use FindBin::Real 'Bin';
	   use lib Bin() . '/../../rel/path/to/my/perllib';
	   use MyApp::Dispatch;

       This module provides a way (as a	mod_perl handler or running under
       vanilla CGI) to look at the path	(as returned by	dispatch_path) of the
       incoming	request, parse off the desired module and its run mode,	create
       an instance of that module and run it.

       It currently supports both generations of mod_perl (1.x and 2.x).
       Although, for simplicity, all examples involving	Apache configuration
       and mod_perl code will be shown using mod_perl 1.x.  This may change as
       mp2 usage increases.

       It will translate a URI like this (under	mod_perl):


       or this (vanilla	cgi)


       into something that will	be functionally	similar	to this

	   my $app = Module::Name->new(..);
	   $app->mode_param(sub	{'run_mode'}); #this will set the run mode

       This is the primary method used during dispatch.	Even under mod_perl,
       the handler method uses this under the hood.

	   use strict;
	   use CGI::Application::Dispatch;

	       prefix  => 'MyApp',
	       default => 'module_name',

       This method accepts the following name value pairs:

	   Specify a value to use for the path if one is not available.	 This
	   could be the	case if	the default page is selected (eg: "/" ).

	   This	option will set	the string that	will be	prepended to the name
	   of the application module before it is loaded and created. So to
	   use our previous example request of


	   This	would by default load and create a module named
	   'Module::Name'. But let's say that you have all of your application
	   specific modules under the 'My' namespace. If you set this option
	   to 'My' then	it would instead load the 'My::Module::Name'
	   application module instead.

	   This	is a hash of arguments that are	passed into the	"new()"
	   constructor of the application.

	   In most cases, simply using Dispatch	with the "default" and
	   "prefix" is enough to simplify your application and your URLs, but
	   there are many cases	where you want more power. Enter the dispatch
	   table. Since	this table can be slightly complicated,	a whole
	   section exists on its use. Please see the "DISPATCH TABLE" section.

	   Set to a true value to send debugging output	for this module	to
	   STDERR. Off by default.

	   This	string is similar to Apache ErrorDocument directive. If	this
	   value is not	present, then Dispatch will return a NOT FOUND error
	   either to the browser with simple hardcoded message (under CGI) or
	   to Apache (under mod_perl).

	   This	value can be one of the	following:

	   A string with error message - if it starts with a single double-
	   quote character ("""). This double-quote character will be trimmed
	   from	final output.

	   A file with content of error	document - if it starts	with less-than
	   sign	("<"). First character will be excluded	as well. Path of this
	   file	should be relative to server DOCUMENT_ROOT.

	   A URI to which the application will be redirected - if no leading
	   """ or "<" will be found.

	   Custom messages will	be displayed in	non mod_perl environment only.
	   (Under mod_perl, please use ErrorDocument directive in Apache
	   configuration files.)  This value can contain %s placeholder	for
	   sprintf Perl	function. This placeholder will	be replaced with
	   numeric HTTP	error code. Currently CGI::Application::Dispatch uses
	   three HTTP errors:

	   400 Bad Request - If	there are invalid characters in	module name
	   (parameter :app) or runmode name (parameter :rm).

	   404 Not Found - When	the path does not match	anything in the
	   "DISPATCH TABLE", or	module could not be found in @INC, or run mode
	   did not exist.

	   500 Internal	Server Error - If application error occurs.

	   Examples of using error_document (assume error 404 have been

	       # return	in browser 'Opss... HTTP Error #404'
	       error_document => '"Opss... HTTP	Error #%s'

	       # return	contents of file $ENV{DOCUMENT_ROOT}/errors/error404.html
	       error_document => '</errors/error%s.html'

	       # internal redirect to /errors/error404.html
	       error_document => '/errors/error%s.html'

	       # external redirect to
	       # http://host.domain/cgi-bin/errors.cgi?error=404
	       error_document => 'http://host.domain/cgi-bin/errors.cgi?error=%s'

	   This	tells Dispatch that you	are using REST by default and that you
	   care	about which HTTP method	is being used. Dispatch	will append
	   the HTTP method name	(upper case by default)	to the run mode	that
	   is determined after finding the appropriate dispatch	rule. So a GET
	   request that	translates into	"MyApp::Module->foo" will become

	   This	can be overridden on a per-rule	basis in a custom dispatch

	   In combinaion with auto_rest	this tells Dispatch that you prefer
	   lower cased HTTP method names.  So instead of "foo_POST" and
	   "foo_GET" you'll have "foo_post" and	"foo_get".

       This method returns the path that is to be processed.

       By default it returns the value of $ENV{PATH_INFO} (or "$r->path_info"
       under mod_perl) which should work for most cases.  It allows the
       ability for subclasses to override the value if they need to do
       something more specific.

       This method is used so that this	module can be run as a mod_perl
       handler.	 When it creates the application module	it passes the $r
       argument	into the PARAMS	hash of	new()

	   <Location /app>
	       SetHandler perl-script
	       PerlHandler CGI::Application::Dispatch
	       PerlSetVar  CGIAPP_DISPATCH_DEFAULT /module_name

       The above example would tell apache that	any url	beginning with /app
       will be handled by CGI::Application::Dispatch. It also sets the prefix
       used to create the application module to	'MyApp'	and it tells
       CGI::Application::Dispatch that it shouldn't set	the run	mode but that
       it will be determined by	the application	module as usual	(through the
       query string). It also sets a default application module	to be used if
       there is	no path.  So, a	url of "/app/module_name" would	create an
       instance	of "MyApp::Module::Name".

       Using this method will add the "Apache-"request>	object to your
       application's "PARAMS" as 'r'.

	   # inside your app
	   my $request = $self->param('r');

       If you need more	customization than can be accomplished with just
       prefix and default, then	it would be best to just subclass
       CGI::Application::Dispatch and override dispatch_args since "handler()"
       uses dispatch to	do the heavy lifting.

	   package MyApp::Dispatch;
	   use base 'CGI::Application::Dispatch';

	   sub dispatch_args {
	       return {
		   prefix  => 'MyApp',
		   table   => [
		       ''		 => { app => 'Welcome',	rm => 'start' },
		       ':app/:rm'	 => { },
		       'admin/:app/:rm'	 => { prefix   => 'MyApp::Admin' },
		   args_to_new => {
		       PARAMS => {
			   foo => 'bar',
			   baz => 'bam',


       And then	in your	httpd.conf

	   <Location /app>
	       SetHandler perl-script
	       PerlHandler MyApp::Dispatch

       Returns a hashref of args that will be passed to	dispatch(). It will
       return the following structure by default.

	       prefix	   => '',
	       args_to_new => {},
	       table	   => [
		   ':app'      => {},
		   ':app/:rm'  => {},

       This is the perfect place to override when creating a subclass to
       provide a richer	dispatch table.

       When called, it receives	1 argument, which is a reference to the	hash
       of args passed into dispatch.

       This method is used to control how the module name is translated	from
       the matching section of the path	(see "Path Parsing").  The main	reason
       that this method	exists is so that it can be overridden if it doesn't
       do exactly what you want.

       The following transformations are performed on the input:

       The text	is split on '_'s (underscores) and each	word has its first
       letter capitalized. The words are then joined back together and each
       instance	of an underscore is replaced by	'::'.
       The text	is split on '-'s (hyphens) and each word has its first letter
       capitalized. The	words are then joined back together and	each instance
       of a hyphen removed.

       Here are	some examples to make it even clearer:

	   module_name	       => Module::Name
	   module-name	       => ModuleName
	   admin_top-scores    => Admin::TopScores

       This class method is used internally by CGI::Application::Dispatch to
       take a module name (supplied by get_module_name)	and require it in a
       secure fashion. It is provided as a public class	method so that if you
       override	other functionality of this module, you	can still safely
       require user specified modules. If there	are any	problems requiring the
       named module, then we will "croak".


       Sometimes it's easiest to explain with an example, so here you go:

	   prefix      => 'MyApp',
	   args_to_new => {
	       TMPL_PATH => 'myapp/templates'
	   table       => [
	       ''			  => { app => 'Blog', rm => 'recent'},
	       'posts/:category'	  => { app => 'Blog', rm => 'posts' },
	       ':app/:rm/:id'		  => { app => 'Blog' },
	       'date/:year/:month?/:day?' => {
		   app	       => 'Blog',
		   rm	       => 'by_date',
		   args_to_new => { TMPL_PATH => "events/" },

       So first, this call to dispatch sets the	prefix and passes a
       "TMPL_PATH" into	args_to_new. Next it sets the table.

       Just so we all understand what we're talking about....

       A table is an array where the elements are gouped as pairs (similar to
       a hash's	key-value pairs, but as	an array to preserve order). The first
       element of each pair is called a	"rule".	The second element in the pair
       is called the rule's "arg list".	 Inside	a rule there are slashes "/".
       Anything	set of characters between slashes is called a "token".

       When a URL comes	in, Dispatch tries to match it against each rule in
       the table in the	order in which the rules are given. The	first one to
       match wins.

       A rule consists of slashes and tokens. A	token can one of the following

	   Any token which does	not start with a colon (":") is	taken to be a
	   literal string and must appear exactly as-is	in the URL in order to
	   match. In the rule


	   "posts" is a	literal	token.

	   Any token which begins with a colon (":") is	a variable token.
	   These are simply wild-card place holders in the rule	that will
	   match anything in the URL that isn't	a slash. These variables can
	   later be referred to	by using the "$self->param" mechanism. In the


	   ":category" is a variable token. If the URL matched this rule, then
	   you could retrieve the value	of that	token from whithin your
	   application like so:

	       my $category = $self->param('category');

	   There are some variable tokens which	are special. These can be used
	   to further customize	the dispatching.

	       This is the module name of the application. The value of	this
	       token will be sent to the translate_module_name method and then
	       prefixed	with the prefix	if there is one.

	   :rm This is the run mode of the application.	The value of this
	       token will be the actual	name of	the run	mode used. The run
	       mode can	be optional, as	noted below. Example:


	       If no run mode is found,	it will	default	to using the
	       "start_mode()", just like invoking CGI::Application directly.
	       Both of these URLs would	end up dispatching to the start	mode
	       associated with /foo:


	   Any token which begins with a colon (":") and ends with a question
	   mark	(<?>) is considered optional. If the rest of the URL matches
	   the rest of the rule, then it doesn't matter	whether	it contains
	   this	token or not. It's best	to only	include	optional-variable
	   tokens at the end of	your rule. In the rule


	   ":month?" and ":day?" are optional-variable tokens.

	   Just	like with variable tokens, optional-variable tokens' values
	   can also be retrieved by the	application, if	they existed in	the

	       if( defined $self->param('month') ) {

	   The wildcard	token "*" allows for partial matches. The token	MUST
	   appear at the end of	the rule.


	   By default, the "dispatch_url_remainder" param is set to the
	   remainder of	the URL	matched	by the *. The name of the param	can be
	   changed by setting "*" argument in the "ARG LIST".

	     'posts/list/*' => { '*' =>	'post_list_filter' }

	   You can also	dispatch based on HTTP method. This is similar to
	   using auto_rest but offers more fine	grained	control. You include
	   the method (case insensitive) at the	end of the rule	and enclose it
	   in square brackets.

	     ':app/news[post]'	 => { rm => 'add_news'	  },
	     ':app/news[get]'	 => { rm => 'news'	  },
	     ':app/news[delete]' => { rm => 'delete_news' },

       The main	reason that we don't use regular expressions for dispatch
       rules is	that regular expressions provide no mechanism for named	back
       references, like	variable tokens	do.

       Each rule can have an accompanying arg-list. This arg list can contain
       special arguments that override something set higher up in dispatch for
       this particular URL, or just have additional args passed	available in

       For instance, if	you want to override prefix for	a specific rule, then
       you can do so.

	   'admin/:app/:rm' => { prefix	=> 'MyApp::Admin' },

Path Parsing
       This section will describe how the application module and run mode are
       determined from the path	if no "DISPATCH	TABLE" is present, and what
       options you have	to customize the process.  The value for the path to
       be parsed is retrieved from the dispatch_path method, which by default
       uses the	"PATH_INFO" environment	variable.

   Getting the module name
       To get the name of the application module the path is split on
       backslahes ("/").  The second element of	the returned list (the first
       is empty) is used to create the application module. So if we have a
       path of


       then the	string 'module_name' is	used. This is passed through the
       translate_module_name method. Then if there is a	"prefix" (and there
       should always be	a prefix) it is	added to the beginning of this new
       module name with	a double colon "::" separating the two.

       If you don't like the exact way that this is done, don't	fret you do
       have a couple of	options.  First, you can specify a "DISPATCH TABLE"
       which is	much more powerful and flexible	(in fact this default behavior
       is actually implemented internally with a dispatch table).  Or if you
       want something a	little simpler,	you can	simply subclass	and extend the
       translate_module_name method.

   Getting the run mode
       Just like the module name is retrieved from splitting the path on
       slashes,	so is the run mode. Only instead of using the second element
       of the resulting	list, we use the third as the run mode.	So, using the
       same example, if	we have	a path of


       Then the	string 'mode2' is used as the run mode.

       o       CGI query strings

	       CGI query strings are unaffected	by the use of "PATH_INFO" to
	       obtain the module name and run mode.  This means	that any other
	       modules you use to get access to	you query argument (ie,	CGI,
	       Apache::Request)	should not be affected.	But, since the run
	       mode may	be determined by CGI::Application::Dispatch having a
	       query argument named 'rm' will be ignored by your application

       With a dispatch script, you can fairly clean URLS like this:


       However,	including "/cgi-bin/dispatch.cgi" in ever URL doesn't add any
       value to	the URL, so it's nice to remove	it. This is easily done	if you
       are using the Apache web	server with "mod_rewrite" available. Adding
       the following to	a ".htaccess" file would allow you to simply use:


       If you have problems with mod_rewrite, turn on debugging	to see exactly
       what's happening:

	RewriteLog /home/project/logs/alpha-rewrite.log
	RewriteLogLevel	9

   mod_rewrite related code in the dispatch script.
       This seemed necessary to	put in the dispatch script to make mod_rewrite
       happy.  Perhaps it's specific to	using "RewriteBase".

	 # mod_rewrite alters the PATH_INFO by turning it into a file system path,
	 # so we repair	it.

   Simple Apache Example
	 RewriteEngine On

	 # You may want	to change the base if you are using the	dispatcher within a
	 # specific directory.
	 RewriteBase /

	 # If an actual	file or	directory is requested,	serve directly
	 RewriteCond %{REQUEST_FILENAME} !-f
	 RewriteCond %{REQUEST_FILENAME} !-d

	 # Otherwise, pass everything through to the dispatcher
	 RewriteRule ^(.*)$ /cgi-bin/dispatch.cgi/$1 [L,QSA]

   More	complex	rewrite: dispatching "/" and multiple developers
       Here is a more complex example that dispatches "/", which would
       otherwise be treated as a directory, and	also supports multiple
       developer directories, so "/~mark" has its own separate dispatching
       system beneath it.

       Note that order matters here! The Location block	for "/"	needs to come
       before the user blocks.

	 <Location />
	   RewriteEngine On
	   RewriteBase /

	   # Run "/" through the dispatcher
	   RewriteRule ^home/project/www/$ /cgi-bin/dispatch.cgi [L,QSA]

	   # Don't apply this rule to the users	sub directories.
	   RewriteCond %{REQUEST_URI} !^/~.*$
	   # If	an actual file or directory is requested, serve	directly
	   RewriteCond %{REQUEST_FILENAME} !-f
	   RewriteCond %{REQUEST_FILENAME} !-d
	   # Otherwise,	pass everything	through	to the dispatcher
	   RewriteRule ^(.*)$ /cgi-bin/dispatch.cgi/$1 [L,QSA]

	 <Location /~mark>
	   RewriteEngine On
	   RewriteBase /~mark

	   # Run "/" through the dispatcher
	   RewriteRule ^/home/mark/www/$ /~mark/cgi-bin/dispatch.cgi [L,QSA]

	   # Otherwise,	if an actual file or directory is requested,
	   # serve directly
	   RewriteCond %{REQUEST_FILENAME} !-f
	   RewriteCond %{REQUEST_FILENAME} !-d

	   # Otherwise,	pass everything	through	to the dispatcher
	   RewriteRule ^(.*)$ /~mark/cgi-bin/dispatch.cgi/$1 [L,QSA]

	   # These examples may	also be	helpful, but are unrelated to dispatching.
	   SetEnv DEVMODE mark
	   SetEnv PERL5LIB /home/mark/perllib:/home/mark/config
	   ErrorDocument 404 /~mark/errdocs/404.html
	   ErrorDocument 500 /~mark/errdocs/500.html

       While Dispatch tries to be flexible, it won't be	able to	do everything
       that people want. Hopefully we've made it flexible enough so that if it
       doesn't do The Right Thing you can easily subclass it.

       Michael Peters <>

       Thanks to Plus Three, LP	( for sponsoring my
       work on this module

       This module is a	part of	the larger CGI::Application community. If you
       have questions or comments about	this module then please	join us	on the
       cgiapp mailing list by sending a	blank message to
       "". There is also a community wiki
       located at <>

       A public	source code repository for this	project	is hosted here:

       o   Shawn Sorichetti

       o   Timothy Appnel

       o   dsteinbrunner

       o   ZACKSE

       o   Stew	Heckenberg

       o   Drew	Taylor <>

       o   James Freeman <>

       o   Michael Graham <>

       o   Cees	Hek <>

       o   Mark	Stosberg <>

       o   Viacheslav Sheveliov	<>

       Since C::A::Dispatch will dynamically choose which modules to use as
       the content generators, it may give someone the ability to execute
       random modules on your system if	those modules can be found in you
       path. Of	course those modules would have	to behave like
       CGI::Application	based modules, but that	still opens up the door	more
       than most want. This should only	be a problem if	you don't use a
       prefix. By using	this option you	are only allowing Dispatch to pick
       from a namespace	of modules to run.

       CGI::Application, Apache::Dispatch

       Copyright Michael Peters	and Mark Stosberg 2008,	all rights reserved.

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.0			  2020-08-20	 CGI::Application::Dispatch(3)


Want to link to this manual page? Use this URL:

home | help