1Dancer2::Core::App(3) User Contributed Perl DocumentationDancer2::Core::App(3)
2
3
4

NAME

6       Dancer2::Core::App - encapsulation of Dancer2 packages
7

VERSION

9       version 0.400001
10

DESCRIPTION

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
16       Mainly, it will contain all the route handlers, the configuration
17       settings and the hooks that are defined in the calling package.
18
19       Note that with Dancer2, everything that is done within a package is
20       scoped to that package, thanks to that encapsulation.
21

ATTRIBUTES

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
30   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

METHODS

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
42   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
47   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
51   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
57       The plugin names are expected to be without the leading
58       "Dancer2::Plugin".  I.e., use "Foo" to mean "Dancer2::Plugin::Foo".
59
60       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
64           my @plugins = $app->with_plugins( 'Foo', 'Bar' );
65
66           # now $app uses the plugins Dancer2::Plugin::Foo
67           # and Dancer2::Plugin::Bar
68
69   with_plugin( $plugin_name )
70       Just like "with_plugin", but for a single plugin.
71
72           my $plugin = $app->with_plugin('Foo');
73
74   add_route
75       Register a new route handler.
76
77           $app->add_route(
78               method  => 'get',
79               regexp  => '/somewhere',
80               code    => sub { ... },
81               options => $conditions,
82           );
83
84       Returns a new Dancer2::Core::Route object created with the passed
85       arguments.
86
87   route_exists
88       Returns a true value if a route already exists, otherwise false.
89
90           my $route = Dancer2::Core::Route->new(...);
91           if ($app->route_exists($route)) {
92               ...
93           }
94
95   routes_regexps_for
96       Sugar for getting the ordered list of all registered route regexps by
97       method.
98
99           my $regexps = $app->routes_regexps_for( 'get' );
100
101       Returns an ArrayRef with the results.
102
103   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
108   halt
109       Flag the response object as 'halted'.
110
111       If called during request dispatch, immediately returns the response to
112       the dispatcher and after hooks will not be run.
113
114   pass
115       Flag the response object as 'passed'.
116
117       If called during request dispatch, immediately returns the response to
118       the dispatcher.
119
120   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
125       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
130       For example:
131
132           forward '/login', { login_failed => 1 }, { method => 'GET' });
133
134   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
139           # before
140           hook before => sub {
141               my $ctx = shift;
142               my $app = $ctx->app;
143           };
144
145           # after
146           hook before => sub {
147               my $app = shift;
148           };
149
150       This meant that "$app->app" would fail, so this method has been
151       provided to make it work.
152
153           # now
154           hook before => sub {
155               my $WannaBeCtx = shift;
156               my $app        = $WannaBeContext->app; # works
157           };
158
159   lexical_prefix
160       Allow for setting a lexical prefix
161
162           $app->lexical_prefix('/blog', sub {
163               ...
164           });
165
166       All the route defined within the callback will have a prefix appended
167       to the current one.
168
169    $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
177       This routine must perform the equivalent of the following subroutine:
178
179           our $EVAL_SHIM = sub {
180               my $code = shift;
181               return $code->(@_);
182           };
183
184       An example of overriding this sub might be as follows:
185
186           $Dancer2::Core::App::EVAL_SHIM = sub {
187               my $code = shift;
188               local $IGNORE_EVAL_COUNTER = $IGNORE_EVAL_COUNTER + 1;
189               return $code->(@_);
190           };
191
192       Note: that this is a GLOBAL setting, which must be set up before any
193       form of dispatch or use of Dancer2.
194

AUTHOR

196       Dancer Core Developers
197
199       This software is copyright (c) 2023 by Alexis Sukrieh.
200
201       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.
203
204
205
206perl v5.38.0                      2023-07-20             Dancer2::Core::App(3)
Impressum