Dancer2::Core::App(3)

✨ Dancer2::Core::App — the whole vibe ✨

okay bestie, so this is Dancer2::Core::App from the User Contributed Perl Documentation section of the manual, and it's literally the class that holds your entire Dancer2 app's soul 🫶

VERSION: version 2.2.1 — that's the one, no cap 💅

---

🌸 NAME 🌸

Dancer2::Core::App — encapsulation of Dancer2 packages. it's giving "your whole app, but in one object" ✨

---

🦋 VERSION 🦋

version 2.2.1. periodt.

---

💖 DESCRIPTION 💖

okay so literally everything a package that uses Dancer2 does gets encapsulated into a Dancer2::Core::App instance. this class defines all the stuff you can do with those objects. main character energy fr fr 👑

mainly, it's gonna contain all the route handlers, the configuration settings, and the hooks that are defined in the calling package. the whole trio, iconic.

note that with Dancer2, everything done within a package is scoped to that package, thanks to that encapsulation. so your package's stuff stays your package's stuff, no leaking, we love boundaries 💅

---

🎀 ATTRIBUTES 🎀

🌈 plugins

🌈 runner_config

🌈 default_config

(yeah these three are just vibes, they're listed, they exist, moving on 🦋)

🌈 with_return

used to cache the coderef that will return from back to the dispatcher, across an arbitrary number of stack frames. like a little elevator that skips all the floors, lowkey genius.

🌈 destroyed_session

we cache a destroyed session here; once this is set we must not attempt to retrieve the session from the cookie in the request. if no new session is created, this is set (with expiration) as a cookie to force the browser to expire the cookie. so basically we're telling the browser "bestie that cookie is dead, let it go" 🍪💀

---

👑 METHODS 👑

💜 has_session

returns true if session engine has been defined and if either a session object has been instantiated or if a session cookie was found and not subsequently invalidated. vibe check on the session, essentially.

💜 change_session_id

changes the session ID used by the current session. this should be used on any change of privilege level, for example on login. returns the new session ID. pls use this when privilege changes, it's the responsible thing to do 🙈

💜 destroy_session

destroys the current session and ensures any subsequent session is created from scratch and not from the request session cookie. clean slate, we love a fresh start ✨

💜 register_plugin

💜 with_plugins( @plugin_names )

creates instances of the given plugins and ties them to the app. the plugin classes are automatically loaded. returns the newly created plugins.

the plugin names are expected to be without the leading Dancer2::Plugin. i.e., use Foo to mean Dancer2::Plugin::Foo.

if a given plugin is already tied to the app, the already-existing instance will be used and returned by with_plugins (think of it as using a role).

my @plugins = $app->with_plugins( 'Foo', 'Bar' );

# now $app uses the plugins Dancer2::Plugin::Foo
# and Dancer2::Plugin::Bar

💜 with_plugin( $plugin_name )

just like with_plugin, but for a single plugin. one plugin, one vibe.

my $plugin = $app->with_plugin('Foo');

💜 add_route

register a new route handler.

$app->add_route(
    method  => 'get',
    regexp  => '/somewhere',
    code    => sub { ... },
    options => $conditions,
);

returns a new Dancer2::Core::Route object created with the passed arguments. slay 🔥

💜 route_exists

returns a true value if a route already exists, otherwise false.

my $route = Dancer2::Core::Route->new(...);
if ($app->route_exists($route)) {
    ...
}

💜 routes_regexps_for

sugar for getting the ordered list of all registered route regexps by method. yes it's sugar, it's sweet, it's fine 🍓

my $regexps = $app->routes_regexps_for( 'get' );

returns an ArrayRef with the results.

💜 redirect($destination, $status)

sets a redirect in the response object. if $destination is not an absolute URI, then it will be made into an absolute URI, relative to the URI in the request. we're gonna make it absolute, bestie, whether it wanted to be or not 💅

💜 halt

flag the response object as 'halted'.

if called during request dispatch, immediately returns the response to the dispatcher and after hooks will not be run. yeah that's the whole point. bye bye after hooks 👋

💜 pass

flag the response object as 'passed'.

if called during request dispatch, immediately returns the response to the dispatcher.

💜 forward

create a new request which is a clone of the current one, apart from the path location, which points instead to the new location. this is used internally to chain requests using the forward keyword.

this method takes 3 parameters: the url to forward to, followed by an optional hashref of parameters added to the current request parameters, followed by a hashref of options regarding the redirect, such as method to change the request method.

for example:

forward '/login', { login_failed => 1 }, { method => 'GET' });

💜 app

returns itself. this is simply available as a shim to help transition from a previous version in which hooks were sent a context object (originally Dancer2::Core::Context) which has since been removed. it's a lil nostalgia shim, it's fine 🥲

# before
hook before => sub {
    my $ctx = shift;
    my $app = $ctx->app;
};

# after
hook before => sub {
    my $app = shift;
};

this meant that $app->app would fail, so this method has been provided to make it work.

# now
hook before => sub {
    my $WannaBeCtx = shift;
    my $app        = $WannaBeContext->app; # works
};

💜 lexical_prefix

allow for setting a lexical prefix

$app->lexical_prefix('/blog', sub {
    ...
});

all the route defined within the callback will have a prefix appended to the current one. nesting your routes, cute 🌸

💜 $SIG{__DIE__} Compatibility via $Dancer2::Core::App::EVAL_SHIM

if an installation wishes to use $SIG{__DIE__} hooks to enhance their error handling then it may be required to ensure that certain bookkeeping code is executed within every eval BLOCK that Dancer2 performs. this can be accomplished by overriding the global variable $Dancer2::Core::App::EVAL_SHIM with a subroutine which does whatever logic is required.

this routine must perform the equivalent of the following subroutine:

our $EVAL_SHIM = sub {
    my $code = shift;
    return $code->(@_);
};

an example of overriding this sub might be as follows:

$Dancer2::Core::App::EVAL_SHIM = sub {
    my $code = shift;
    local $IGNORE_EVAL_COUNTER = $IGNORE_EVAL_COUNTER + 1;
    return $code->(@_);
};

note: that this is a GLOBAL setting, which must be set up before any form of dispatch or use of Dancer2. like, before. we mean it. 🙈

---

🌟 AUTHOR 🌟

Dancer Core Developers 💖 y'all ate.

---

🌈 COPYRIGHT AND LICENSE 🌈

this software is copyright (c) 2026 by Alexis Sukrieh.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free as in freedom, iconic 🕊️

---

and that's the whole page bestie 💜 this was written up as perl v5.42.3, dated 2026-09-20, and yeah the page is literally called Dancer2::Core::App(3) — go build something cute with it 🎀✨