Plack::App::URLMux(3p)

NAME
Plack::App::URLMux - Map multiple applications by different url path.

SYNOPSYS
    use Plack::App::URLMux;

    my $app1 = sub { ... };
    my $app2 = sub { ... };
    my $app3 = sub { ... };

    my $urlmap = Plack::App::URLMux->new;
    $urlmap->map("/" => $app1, foo => bar);
    $urlmap->map("/foo/:name/bar" => $app2);
    $urlmap->map("/foo/test/bar"  => $app3);
    $urlmap->map("http://bar.example.com/" => $app4);
    $urlmap->map("/foo/:bar*/baz" => $app2);

    my $app = $urlmap->to_app;

DESCRIPTION
Plack::App::URLMux is a PSGI application that can dispatch multiple applications based on URL path and host names (a.k.a "virtual hosting") and takes care of rewriting "SCRIPT_NAME" and "PATH_INFO" (See "HOW THIS WORKS" for details). This module is based on Plack::App::URLMap module but optimizied to handle a lot of urls and has additional rules for parameterized URL and add additional parameteres provided to application at mapping URL.

Mapping rules for url with parameters /foo/:name/bar will mapped to any URL wich contains /foo/some/bar and call $app2 with additional parameters at environmentas name => 'some'. But if you mount /for/test/bar the same time, then for this URL /for/test/bar mapping will be exactly to $app3 to this URL without parameter and other URLs contain anything between /foo/ and /bar will be mapped to $app2 with parameter 'name'.

Format for parameters :name, parameter names may be repeated, mapper returned values as array of pairs name=>value in order as they meet in URL.

ENVIRONMENT
On call mapper provide next environment in request:

plack.urlmux.params.map
    Array of pairs key=>value specified when mount app

    -item plack.urlmux.params.url

    Array of pairs name=>value extracted from url path by url format specified when mount app

METHODS

map
      $urlmap->map("/foo" => $app);
      $urlmap->map("http://bar.example.com/" => $another_app);
      $urlmap->map("/foo/:name/bar" => $app2);
      $urlmap->map('' => $app_not_found);

    Maps URL an absolute URL to a PSGI application. Module splits url path by '/' delimeter and add it into builded search tree structure.

    URL paths need to match from the beginning and should match completely until the path separator (or the end of the path). For example, if you register the path "/foo", it will match with the request "/foo", "/foo/" or "/foo/bar" but it won't match with "/foox".

    Mapping URLs with host names is also possible, and in that case the URL mapping works like a virtual host.

    Also possible handle 404 error by outer application that handles 'Not found' event by mapping the application to an empty location.

mount
    Alias for "map".

to_app
      my $handler = $urlmap->to_app;

    Returns the PSGI application code reference.

PERFORMANCE
No restriction on number of urls, of course perl has trouble to store 1M records, it takes a lot of memory. Mounting hundreds of applications cause a small affect on runtime request performance. Algorithm complexity is near logN.

AUTHOR
Aleksey Ozhigov

SEE ALSO
Plack::App::URLMap