Plack::App::URLMap(3)

✨ Plack::App::URLMap ✨

okay so bestie, welcome to Plack::App::URLMap — the Perl module that maps a bunch of apps onto different paths 💅

---

🌸 NAME 🌸

Plack::App::URLMap — map multiple apps in different paths 🗺️✨

---

🎀 SYNOPSIS 🎀

like, here's the vibe:

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;

three little apps, three little homes, one urlmap holding it all together 🫶

---

🦋 DESCRIPTION 🦋

okay so 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 it also handles rewriting SCRIPT_NAME and PATH_INFO for you (peep the "HOW THIS WORKS" section for the tea ☕). And fun fact: this module was inspired by Ruby's Rack::URLMap — it's giving cross-language icon behavior, honestly 👑

---

💖 METHODS 💖

🌟 map

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

Maps a 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, no cap 📏

URL paths need to match from the beginning and should match completely up to the path separator (or the end of the path). So like, if you register the path "/foo", it's gonna match the request "/foo", "/foo/" or "/foo/bar" — but it will NOT match "/foox". boundary queen 👑 no half-matches here.

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

Mappings will nest. If $app is already mapped to "/baz" it will match a request for "/foo/baz" but not "/foo". Peep "HOW THIS WORKS" for the full lore.

🌟 mount

Alias for "map". Same energy, different name 💫

🌟 to_app

my $handler = $urlmap->to_app;

Returns the PSGI application code reference. And ngl, there's a fun little detail here: the Plack::App::URLMap object is callable (by overloading the code dereference), so just returning the object itself as a PSGI application should also work. it's giving ✨overachiever✨

---

🔥 PERFORMANCE 🔥

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.

Bestie, real talk: 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 😭 don't do that to yourself.

---

💀 DEBUGGING 💀

You can set the environment variable PLACK_URLMAP_DEBUG to see how this application matches with the incoming request host names and paths 👀🔍 so helpful fr fr.

---

🌈 HOW THIS WORKS 🌈

This application works by fixing SCRIPT_NAME and PATH_INFO before dispatching the incoming request to the relocated applications. like a little glow-up for your paths 💅

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 doing:

# 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. snipped and rehomed, iconic behavior ✂️✨

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. it all just clicks 🫶

---

👑 AUTHOR 👑

Tatsuhiko Miyagawa

---

🍓 SEE ALSO 🍓

• Plack::Builder

---

k that's the whole page, bestie! be safe with your mounts, don't mount a hundred apps, and remember: longest match wins 💖

so yeah, that was Plack::App::URLMap(3) — the Perl documentation, perl v5.42.3, dated 2026-10-18 🌸 go slay your routing ✨💅🎀