The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


CGI::Application::URIMapping - A dispatcher and permalink builder


  # your.cgi
  use MyApp::URIMapping;
  package MyApp::URIMapping;
  use base qw/CGI::Application::URIMapping/;
  use MyApp::Page1;
  use MyApp::Page2;
  package MyApp::Page1;
  use base qw/CGI::Application/;
  # registers subroutine ``page1'' for given path
    path  => 'page1/:p1/:p2?',
    query => [ qw/q1 q2 q3/ ]
  sub page1 {
    my $self = shift;
    # if URI is not in permalink style, redirect
    return if $self->normalize_uri;
  # build_uri, generates: http://host/page1/p-one?q1=q-one&q3=q-three
  my $permalink = MyApp::Page1->build_uri([{
    p1 => 'p-one',
    q1 => 'q-one',
    q3 => 'q-three',


CGI::Application::URIMapping is a dispatcher / permalink builder for CGI::Application. It is implemented as a wrapper of CGI::Application::Dispatch.

As can be seen in the synopsis, CGI::Application::URIMapping is designed to be used as a base class for defining a mapping for each CGI::Application-based web application.



The class method assigns a runmode to more than one paths. There are various ways of calling the function. Runmodes of the registered packages are automatically setup, and Build_uri method will be added to the packages.

    path  => 'path',
    query => [ qw/n1 n2/ ],
    rm       => 'run_mode',
    path     => 'path',
    protocol => 'https',
    host     => '',
    app  => 'MyApp::Page2',
    rm   => 'run_mode',
    path => [
      'path1/:p1/:p2?/:p3?' => {
        query => [ qw/n1 n2/ ],
      'path2' => {
        query => [ qw/p1 p2 p3 n1 n2/ ],

The attributes recognized by the function is as follows.


Name of the package in which the run mode is defined. If ommited, name of the current package is being used.


Name of the runmode. If omitted, basename of the first path attribute is being used.


A path (or an array of paths) to be registered for the runmode. The syntax of the paths are equivalent to that of CGI::Application::Dispatch with the following exceptions. The attributes app and rm need not be defined for each path, since they are already specified. Procotol, host, query attributes are accepted.


Specifies protocol to be used for given runmode when building a permalink.


Limits the registration to given host if specified.


List of parameters to be marshallised when building a premalink. The parameters will be marshallized in the order of the array.


The function is an accessor / mutator for uniformly handling path parameters and query parameters.

  my $value = $cgi_app->all_param($name);   # read paramater
  $cgi_app->all_param($name, $value);       # set parameter

The setter first tries to read from $cgi_app->param($name), and then $cgi_app->query->param($name). The getter sets the value to $cgi_app->param($name, $value).


The function is automatically setup for the registered CGI::Application packages.

  MyApp::Page1->build_uri();      # builds default URI for page1
  MyApp::Page1->build_uri({       # explicitly set runmode
    rm  => 'page1',
  MyApp::Page1->build_uri({       # specify parameters and protocol
    params   => [{
      p1 => 'p-one',
      n1 => 'n-one',
    procotol => 'https',
  MyApp::Page1->build_uri({       # just override 'p1'
    params => [
        p1 => 'p-one',

If called with a hash as the only argument, the function recognizes the following attributes. If called with an array as the only argument, the array is considered as the params attribute.


Name of the runmode. If omitted, the last portion of the package name will be used uncamelized.




An array of hashes or object containing values to be filled in when building the URI. The parameters are searched from the begging of the array to the end, and the first-found value is used. If the array element is an object, its param method is called in order to obtain the variable.


The function, which is automaticaly setup as a instance method of CGI::Application, checks whether the current URI is conforms to the registered format.

  $cgi_app->validate_uri({        # explicitly specify runmode
     rm => 'page1',
  $cgi_app->validate_uri({        # set extra query parameters to be allowed
     extra => [ qw/__extra1 __extra2/ ],

The function accepts following attributes.


Runmode. If omitted, uncamelized basename of the package is used.


Array of query args to be ignored while validating the parameters received.

The return value of the function is one of the following constants.

Current URI conforms the registered format.


Current URI contains an unknown query parameter.


A parameter expected in path_info is being received as a query parameter.


A parameter that should be omitted (since it contains the default value) exists.

The constants are importable by specifying :constants attribute.

  use CGI::Application::URIMapping qw/:constants/;


Copyright (c) 2007 Cybozu Labs, Inc. All rights reserved.

written by Kazuho Oku <>


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