1Dancer2::Core::App(3) User Contributed Perl DocumentationDancer2::Core::App(3)
2
6 Dancer2::Core::App - encapsulation of Dancer2 packages
7
9 version 0.400001
10
12 Everything a package that uses Dancer2 does is encapsulated into a
13 "Dancer2::Core::App" instance. This class defines all that can be done
14 in such objects.
15 Mainly, it will contain all the route handlers, the configuration
17 settings and the hooks that are defined in the calling package.
18 Note that with Dancer2, everything that is done within a package is
20 scoped to that package, thanks to that encapsulation.
21
23 plugins
24 runner_config
25 default_config
26 with_return
27 Used to cache the coderef that will return from back to the dispatcher,
28 across an arbitrary number of stack frames.
29 destroyed_session
31 We cache a destroyed session here; once this is set we must not attempt
32 to retrieve the session from the cookie in the request. If no new
33 session is created, this is set (with expiration) as a cookie to force
34 the browser to expire the cookie.
35
37 has_session
38 Returns true if session engine has been defined and if either a session
39 object has been instantiated or if a session cookie was found and not
40 subsequently invalidated.
41 change_session_id
43 Changes the session ID used by the current session. This should be used
44 on any change of privilege level, for example on login. Returns the new
45 session ID.
46 destroy_session
48 Destroys the current session and ensures any subsequent session is
49 created from scratch and not from the request session cookie
50 register_plugin
52 with_plugins( @plugin_names )
53 Creates instances of the given plugins and tie them to the app. The
54 plugin classes are automatically loaded. Returns the newly created
55 plugins.
56 The plugin names are expected to be without the leading
58 "Dancer2::Plugin". I.e., use "Foo" to mean "Dancer2::Plugin::Foo".
59 If a given plugin is already tied to the app, the already-existing
61 instance will be used and returned by "with_plugins" (think of it as
62 using a role).
63 my @plugins = $app->with_plugins( 'Foo', 'Bar' );
65 # now $app uses the plugins Dancer2::Plugin::Foo
67 # and Dancer2::Plugin::Bar
68 with_plugin( $plugin_name )
70 Just like "with_plugin", but for a single plugin.
71 my $plugin = $app->with_plugin('Foo');
73 add_route
75 Register a new route handler.
76 $app->add_route(
78 method => 'get',
79 regexp => '/somewhere',
80 code => sub { ... },
81 options => $conditions,
82 );
83 Returns a new Dancer2::Core::Route object created with the passed
85 arguments.
86 route_exists
88 Returns a true value if a route already exists, otherwise false.
89 my $route = Dancer2::Core::Route->new(...);
91 if ($app->route_exists($route)) {
92 ...
93 }
94 routes_regexps_for
96 Sugar for getting the ordered list of all registered route regexps by
97 method.
98 my $regexps = $app->routes_regexps_for( 'get' );
100 Returns an ArrayRef with the results.
102 redirect($destination, $status)
104 Sets a redirect in the response object. If $destination is not an
105 absolute URI, then it will be made into an absolute URI, relative to
106 the URI in the request.
107 halt
109 Flag the response object as 'halted'.
110 If called during request dispatch, immediately returns the response to
112 the dispatcher and after hooks will not be run.
113 pass
115 Flag the response object as 'passed'.
116 If called during request dispatch, immediately returns the response to
118 the dispatcher.
119 forward
121 Create a new request which is a clone of the current one, apart from
122 the path location, which points instead to the new location. This is
123 used internally to chain requests using the forward keyword.
124 This method takes 3 parameters: the url to forward to, followed by an
126 optional hashref of parameters added to the current request parameters,
127 followed by a hashref of options regarding the redirect, such as
128 "method" to change the request method.
129 For example:
131 forward '/login', { login_failed => 1 }, { method => 'GET' });
133 app
135 Returns itself. This is simply available as a shim to help transition
136 from a previous version in which hooks were sent a context object
137 (originally "Dancer2::Core::Context") which has since been removed.
138 # before
140 hook before => sub {
141 my $ctx = shift;
142 my $app = $ctx->app;
143 };
144 # after
146 hook before => sub {
147 my $app = shift;
148 };
149 This meant that "$app->app" would fail, so this method has been
151 provided to make it work.
152 # now
154 hook before => sub {
155 my $WannaBeCtx = shift;
156 my $app = $WannaBeContext->app; # works
157 };
158 lexical_prefix
160 Allow for setting a lexical prefix
161 $app->lexical_prefix('/blog', sub {
163 ...
164 });
165 All the route defined within the callback will have a prefix appended
167 to the current one.
168 $SIG{__DIE__} Compatibility via $Dancer2::Core::App::EVAL_SHIM
170 If an installation wishes to use $SIG{__DIE__} hooks to enhance their
171 error handling then it may be required to ensure that certain
172 bookkeeping code is executed within every "eval BLOCK" that Dancer2
173 performs. This can be accomplished by overriding the global variable
174 $Dancer2::Core::App::EVAL_SHIM with a subroutine which does whatever
175 logic is required.
176 This routine must perform the equivalent of the following subroutine:
178 our $EVAL_SHIM = sub {
180 my $code = shift;
181 return $code->(@_);
182 };
183 An example of overriding this sub might be as follows:
185 $Dancer2::Core::App::EVAL_SHIM = sub {
187 my $code = shift;
188 local $IGNORE_EVAL_COUNTER = $IGNORE_EVAL_COUNTER + 1;
189 return $code->(@_);
190 };
191 Note: that this is a GLOBAL setting, which must be set up before any
193 form of dispatch or use of Dancer2.
194
196 Dancer Core Developers
197
199 This software is copyright (c) 2023 by Alexis Sukrieh.
200 This is free software; you can redistribute it and/or modify it under
202 the same terms as the Perl 5 programming language system itself.
203perl v5.38.0 2023-07-20 Dancer2::Core::App(3)