NAME¶
Plack::App::URLMap - Map multiple apps in different paths
SYNOPSIS¶
use Plack::App::URLMap;
my $app1 = sub { ... };
my $app2 = sub { ... };
my $app3 = sub { ... };
my $urlmap = Plack::App::URLMap->new;
$urlmap->map("/" => $app1);
$urlmap->map("/foo" => $app2);
$urlmap->map("http://bar.example.com/" => $app3);
my $app = $urlmap->to_app;
DESCRIPTION¶
Plack::App::URLMap 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 inspired by Ruby's
Rack::URLMap.
METHODS¶
- map
-
$urlmap->map("/foo" => $app);
$urlmap->map("http://bar.example.com/" => $another_app);
Maps URL path or an absolute URL to a PSGI application. The match order is
sorted by host name length and then path length (longest strings first).
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.
Mappings will nest. If $app is already mapped to "/baz" it will
match a request for "/foo/baz" but not "/foo". See
"HOW THIS WORKS" for more details.
- mount
- Alias for "map".
- to_app
-
my $handler = $urlmap->to_app;
Returns the PSGI application code reference. Note that the
Plack::App::URLMap object is callable (by overloading the code
dereference), so returning the object itself as a PSGI application should
also work.
If you "map" (or "mount" with Plack::Builder) N
applications, Plack::App::URLMap will need to at most iterate through N paths
to match incoming requests.
It is a good idea to use "map" only for a known, limited amount of
applications, since mounting hundreds of applications could affect runtime
request performance.
DEBUGGING¶
You can set the environment variable "PLACK_URLMAP_DEBUG" to see how
this application matches with the incoming request host names and paths.
HOW THIS WORKS¶
This application works by
fixing "SCRIPT_NAME" and
"PATH_INFO" before dispatching the incoming request to the relocated
applications.
Say you have a Wiki application that takes "/index" and
"/page/*" and makes a PSGI application $wiki_app out of it, using
one of supported web frameworks, you can put the whole application under
"/wiki" by:
# MyWikiApp looks at PATH_INFO and handles /index and /page/*
my $wiki_app = sub { MyWikiApp->run(@_) };
use Plack::App::URLMap;
my $app = Plack::App::URLMap->new;
$app->mount("/wiki" => $wiki_app);
When a request comes in with "PATH_INFO" set to
"/wiki/page/foo", the URLMap application $app strips the
"/wiki" part from "PATH_INFO" and
appends that to
"SCRIPT_NAME".
That way, if the $app is mounted under the root (i.e. "SCRIPT_NAME" is
"") with standalone web servers like Starman,
"SCRIPT_NAME" is now locally set to "/wiki" and
"PATH_INFO" is changed to "/page/foo" when $wiki_app gets
called.
AUTHOR¶
Tatsuhiko Miyagawa
SEE ALSO¶
Plack::Builder