1Dancer2::Manual(3) User Contributed Perl Documentation Dancer2::Manual(3)
2
6 Dancer2::Manual - A gentle introduction to Dancer2
7
9 version 0.300005
10
12 Dancer2 is a free and open source web application framework written in
13 Perl.
14 It's a complete rewrite of Dancer, based on Moo and using a more robust
16 and extensible fully-OO design.
17 It's designed to be powerful and flexible, but also easy to use -
19 getting up and running with your web app is trivial, and an ecosystem
20 of adaptors for common template engines, session storage, logging
21 methods, serializers, and plugins to make common tasks easy means you
22 can do what you want to do, your way, easily.
23
25 Installation of Dancer2 is simple, using your favourite method to
26 install from CPAN, e.g.:
27 perl -MCPAN -e 'install Dancer2'
29 Thanks to the magic of cpanminus, if you do not have CPAN.pm
31 configured, or just want a quickfire way to get running, the following
32 should work, at least on Unix-like systems:
33 wget -O - http://cpanmin.us | sudo perl - Dancer2
35 (If you don't have root access, omit the 'sudo', and cpanminus will
37 install Dancer2 and prereqs into "~/perl5".)
38 Dancer2 is also available as a package from the package repository of
40 several distributions, for example on Debian/Ubuntu you should be able
41 to just:
42 apt-get install libdancer2-perl
44 Do be aware, though, that distribution-packaged versions sometimes lag
46 behind the most recent version on CPAN.
47
49 Create a web application using the dancer script:
50 $ dancer2 -a MyApp && cd MyApp
52 + MyApp
53 + MyApp/config.yml
54 + MyApp/Makefile.PL
55 + MyApp/MANIFEST.SKIP
56 + MyApp/.dancer
57 + MyApp/cpanfile
58 + MyApp/bin
59 + MyApp/bin/app.psgi
60 + MyApp/environments
61 + MyApp/environments/development.yml
62 + MyApp/environments/production.yml
63 + MyApp/lib
64 + MyApp/lib/MyApp.pm
65 + MyApp/public
66 + MyApp/public/favicon.ico
67 + MyApp/public/500.html
68 + MyApp/public/dispatch.cgi
69 + MyApp/public/404.html
70 + MyApp/public/dispatch.fcgi
71 + MyApp/public/css
72 + MyApp/public/css/error.css
73 + MyApp/public/css/style.css
74 + MyApp/public/images
75 + MyApp/public/images/perldancer.jpg
76 + MyApp/public/images/perldancer-bg.jpg
77 + MyApp/public/javascripts
78 + MyApp/public/javascripts/jquery.js
79 + MyApp/t
80 + MyApp/t/001_base.t
81 + MyApp/t/002_index_route.t
82 + MyApp/views
83 + MyApp/views/index.tt
84 + MyApp/views/layouts
85 + MyApp/views/layouts/main.tt
86 It creates a directory named after the name of the app, along with a
88 configuration file, a views directory (where your templates and layouts
89 will live), an environments directory (where environment-specific
90 settings live), a module containing the actual guts of your
91 application, and a script to start it. A default skeleton is used to
92 bootstrap the new application, but you can use the "-s" option to
93 provide another skeleton. For example:
94 $ dancer2 -a MyApp -s ~/mydancerskel
96 For an example of a skeleton directory check the default one available
98 in the "share/" directory of your Dancer2 distribution.
99 (In what follows we will refer to the directory in which you have
101 created your Dancer2 application -- e.g., what "MyApp" was above -- as
102 the "appdir".)
103 Because Dancer2 is a PSGI web application framework, you can use the
105 "plackup" tool (provided by Plack) for launching the application:
106 plackup -p 5000 bin/app.psgi
108 View the web application at:
110 http://localhost:5000
112
114 When Dancer2 is imported to a script, that script becomes a webapp, and
115 at this point, all the script has to do is declare a list of routes. A
116 route handler is composed by an HTTP method, a path pattern and a code
117 block. "strict", "warnings" and "utf8" pragmas are also imported with
118 Dancer2.
119 The code block given to the route handler has to return a string which
121 will be used as the content to render to the client.
122 Routes are defined for a given HTTP method. For each method supported,
124 a keyword is exported by the module.
125 HTTP Methods
127 Here are some of the standard HTTP methods which you can use to define
128 your route handlers.
129 • GET The GET method retrieves information, and is the most common
131 GET requests should be used for typical "fetch" requests -
133 retrieving information. They should not be used for requests which
134 change data on the server or have other effects.
135 When defining a route handler for the GET method, Dancer2
137 automatically defines a route handler for the HEAD method (in order
138 to honour HEAD requests for each of your GET route handlers).
139 To define a GET action, use the get keyword.
141 • POST The POST method is used to create a resource on the server.
143 To define a POST action, use the post keyword.
145 • PUT The PUT method is used to replace an existing resource.
147 To define a PUT action, use the put keyword.
149 a PUT request should replace the existing resource with that
151 specified - for instance - if you wanted to just update an email
152 address for a user, you'd have to specify all attributes of the
153 user again; to make a partial update, a PATCH request is used.
154 • PATCH The PATCH method updates some attributes of an existing
156 resource.
157 To define a PATCH action, use the patch keyword.
159 • DELETE The DELETE method requests that the origin server delete the
161 resource identified by the Request-URI.
162 To define a DELETE action, use the del keyword.
164 Handling multiple HTTP request methods
166 Routes can use "any" to match all, or a specified list of HTTP methods.
168 The following will match any HTTP request to the path "/myaction":
170 any '/myaction' => sub {
172 # code
173 }
174 The following will match GET or POST requests to "/myaction":
176 any ['get', 'post'] => '/myaction' => sub {
178 # code
179 };
180 For convenience, any route which matches GET requests will also match
182 HEAD requests.
183 Route Handlers
185 The route action is the code reference declared. It can access
186 parameters through the specific route_parameters, query_parameters, and
187 body_parameters keywords, which return a Hash::MultiValue object. This
188 hashref is a merge of the route pattern matches and the request params.
189 You can find more details about how params are built and how to access
191 them in the Dancer2::Core::Request documentation.
192 Declaring Routes
194 To control what happens when a web request is received by your webapp,
196 you'll need to declare "routes". A route declaration indicates which
197 HTTP method(s) it is valid for, the path it matches (e.g. "/foo/bar"),
198 and a coderef to execute, which returns the response.
199 get '/hello/:name' => sub {
201 return "Hi there " . route_parameters->get('name');
202 };
203 The above route specifies that, for GET requests to "/hello/...", the
205 code block provided should be executed.
206 Retrieving request parameters
208 The query_parameters, route_parameters, and body_parameters keywords
210 provide a Hash::MultiValue result from the three different parameters.
211 Named matching
213 A route pattern can contain one or more tokens (a word prefixed with
215 ':'). Each token found in a route pattern is used as a named-pattern
216 match. Any match will be set in the route parameters.
217 get '/hello/:name' => sub {
219 return "Hey " . route_parameters->get('name') . ", welcome here!";
220 };
221 Tokens can be optional, for example:
223 get '/hello/:name?' => sub {
225 my $name = route_parameters->get('name') // 'Whoever you are';
226 return "Hello there, $name";
227 };
228 Named matching with type constraints
230 Type constraints can be added to tokens.
232 get '/user/:id[Int]' => sub {
234 # matches /user/34 but not /user/jamesdean
235 my $user_id = route_parameters->get('id');
236 };
237 get '/user/:username[Str]' => sub {
239 # matches /user/jamesdean but not /user/34 since that is caught
240 # by previous route
241 my $username = route_parameters->get('username');
242 };
243 You can even use type constraints to add a regexp check:
245 get '/book/:date[StrMatch[qr{\d\d\d\d-\d\d-\d\d}]]' => sub {
247 # matches /book/2014-02-04
248 my $date = route_parameters->get('date');
249 };
250 The default type library is Dancer2::Core::Types but any type library
252 built using Type::Tiny's Type::Library can be used instead. If you'd
253 like to use a different default type library you must declare it in the
254 configuration file, for example:
255 type_library: My::Type::Library
257 Alternatively you can specify the type library in which the type is
259 defined as part of the route definition:
260 get '/user/:username[My::Type::Library::Username]' => sub {
262 my $username = route_parameters->get('username');
263 };
264 This will load "My::Type::Library" and from it use the type "Username".
266 This allows types to be used that are not part of the type library
267 defined by config's "type_library".
268 More complex constructs are allowed such as:
270 get '/some/:thing[Int|MyDate]' => sub {
272 ...;
273 };
274 See "lookup($name)" in Type::Registry for more details.
276 Wildcard Matching
278 A route can contain a wildcard (represented by a "*"). Each wildcard
280 match will be placed in a list, which the "splat" keyword returns.
281 get '/download/*.*' => sub {
283 my ($file, $ext) = splat;
284 # do something with $file.$ext here
285 };
286 An extensive, greedier wildcard represented by "**" (A.K.A.
288 "megasplat") can be used to define a route. The additional path is
289 broken down and returned as an arrayref:
290 get '/entry/*/tags/**' => sub {
292 my ( $entry_id, $tags ) = splat;
293 my @tags = @{$tags};
294 };
295 The "splat" keyword in the above example for the route
297 /entry/1/tags/one/two would set $entry_id to 1 and $tags to "['one',
298 'two']".
299 Mixed named and wildcard matching
301 A route can combine named (token) matching and wildcard matching. This
303 is useful when chaining actions:
304 get '/team/:team/**' => sub {
306 var team => route_parameters->get('team');
307 pass;
308 };
309 prefix '/team/:team';
311 get '/player/*' => sub {
313 my ($player) = splat;
314 # etc...
316 };
317 get '/score' => sub {
319 return score_for( vars->{'team'} );
320 };
321 Regular Expression Matching
323 A route can be defined with a Perl regular expression.
325 In order to tell Dancer2 to consider the route as a real regexp, the
327 route must be defined explicitly with "qr{}", like the following:
328 get qr{/hello/([\w]+)} => sub {
330 my ($name) = splat;
331 return "Hello $name";
332 };
333 For Perl 5.10+, a route regex may use named capture groups. The
335 "captures" keyword will return a reference to a copy of "%+".
336 Conditional Matching
338 Routes may include some matching conditions (on content_type, agent,
340 user_agent, content_length and path_info):
341 get '/foo', {agent => 'Songbird (\d\.\d)[\d\/]*?'} => sub {
343 'foo method for songbird'
344 }
345 get '/foo' => sub {
347 'all browsers except songbird'
348 }
349 Prefix
351 A prefix can be defined for each route handler, like this:
352 prefix '/home';
354 From here, any route handler is defined to /home/*
356 get '/page1' => sub {}; # will match '/home/page1'
358 You can unset the prefix value
360 prefix '/'; # or: prefix undef;
362 get '/page1' => sub {}; # will match /page1
363 Alternatively, to prevent you from ever forgetting to undef the prefix,
365 you can use lexical prefix like this:
366 prefix '/home' => sub {
368 get '/page1' => sub {}; # will match '/home/page1'
369 }; ## prefix reset to previous value on exit
370 get '/page1' => sub {}; # will match /page1
372 Delayed responses (Async/Streaming)
374 Dancer2 can provide delayed (otherwise known as asynchronous) responses
375 using the "delayed" keyword. These responses are streamed, although you
376 can set the content all at once, if you prefer.
377 get '/status' => sub {
379 delayed {
380 response_header 'X-Foo' => 'Bar';
381 # flush headers (in case of streaming)
383 flush;
384 # send content to the user
386 content 'Hello, world!';
387 # you can write more content
389 # all streaming
390 content 'Hello, again!';
391 # when done, close the connection
393 done;
394 # do whatever you want else, asynchronously
396 # the user socket closed by now
397 ...
398 };
399 };
400 If you are streaming (calling "content" several times), you must call
402 "flush" first. If you're sending only once, you don't need to call
403 "flush".
404 Here is an example of using delayed responses with AnyEvent:
406 use Dancer2;
408 use AnyEvent;
409 my %timers;
411 my $count = 5;
412 get '/drums' => sub {
413 delayed {
414 print "Stretching...\n";
415 flush; # necessary, since we're streaming
416 $timers{'Snare'} = AE::timer 1, 1, delayed {
418 $timers{'HiHat'} ||= AE::timer 0, 0.5, delayed {
419 content "Tss...\n";
420 };
421 content "Bap!\n";
423 if ( $count-- == 0 ) {
425 %timers = ();
426 content "Tugu tugu tugu dum!\n";
427 done;
428 print "<enter sound of applause>\n\n";
430 $timers{'Applause'} = AE::timer 3, 0, sub {
431 # the DSL will not available here
432 # because we didn't call the "delayed" keyword
433 print "<applause dies out>\n";
434 };
435 }
436 };
437 };
438 };
439 If an error happens during a write operation, a warning will be issued
441 to the logger.
442 You can handle the error yourself by providing an "on_error" handler:
444 get '/' => sub {
446 delayed {
447 flush;
448 content "works";
449 # ... user disconnected here ...
451 content "fails";
453 # ... error triggered ...
455 done; # doesn't even get run
457 } on_error => sub {
458 # delayed{} not needed, DSL already available
459 my ($error) = @_;
460 # do something with $error
461 };
462 };
463 Here is an example that asynchronously streams the contents of a CSV
465 file:
466 use Dancer2;
468 use Text::CSV_XS qw< csv >;
469 use Path::Tiny qw< path >;
470 use JSON::MaybeXS qw< encode_json >;
471 # Create CSV parser
472 my $csv = Text::CSV_XS->new({
473 binary => 1,
474 auto_diag => 1,
475 });
476 get '/' => sub {
477 # delayed response:
478 delayed {
479 # streaming content
480 flush;
481 # Read each row and stream it in JSON
482 my $fh = path('filename.csv')->openr_utf8;
483 while ( my $row = $csv->getline($fh) ) {
484 content encode_json $row;
485 }
486 # close user connection
487 done;
488 } on_error => sub {
489 my ($error) = @_;
490 warning 'Failed to stream to user: ' . request->remote_address;
491 };
492 };
493 NOTE: If you just want to send a file's contents asynchronously, use
495 "send_file($filename)" instead of "delayed", as it will automatically
496 take advantage of any asynchronous capability.
497 Action Skipping
499 An action can choose not to serve the current request and ask Dancer2
500 to process the request with the next matching route.
501 This is done with the pass keyword, like in the following example
503 get '/say/:word' => sub {
505 pass if route_parameters->get('word') =~ /^\d+$/;
506 "I say a word: " . route_parameters->get('word');
507 };
508 get '/say/:number' => sub {
510 "I say a number: " . route_parameters->get('number');
511 };
512
514 Hooks are code references (or anonymous subroutines) that are triggered
515 at specific moments during the resolution of a request. They are set
516 up using the hook keyword.
517 Many of them are provided by Dancer2's core, but plugins and engines
519 can also define their own.
520 • "before" hooks
522 "before" hooks are evaluated before each request within the context
524 of the request and receives as argument the app (a
525 Dancer2::Core::App object).
526 It's possible to define variables which will be accessible in the
528 action blocks with the var keyword.
529 hook before => sub {
531 var note => 'Hi there';
532 };
533 get '/foo/*' => sub {
535 my ($match) = splat; # 'oversee';
536 vars->{note}; # 'Hi there'
537 };
538 For another example, this can be used along with session support to
540 easily give non-logged-in users a login page:
541 hook before => sub {
543 if (!session('user') && request->path !~ m{^/login}) {
544 # Pass the original path requested along to the handler:
545 forward '/login', { requested_path => request->path };
546 }
547 };
548 The request keyword returns the current Dancer2::Core::Request
550 object representing the incoming request.
551 • "after" hooks
553 "after" hooks are evaluated after the response has been built by a
555 route handler, and can alter the response itself, just before it's
556 sent to the client.
557 This hook runs after a request has been processed, but before the
559 response is sent.
560 It receives a Dancer2::Core::Response object, which it can modify
562 if it needs to make changes to the response which is about to be
563 sent.
564 The hook can use other keywords in order to do whatever it wants.
566 hook after => sub {
568 response->content(
569 q{The "after" hook can alter the response's content here!}
570 );
571 };
572 Templates
574 • "before_template_render"
575 "before_template_render" hooks are called whenever a template is
577 going to be processed, they are passed the tokens hash which they
578 can alter.
579 hook before_template_render => sub {
581 my $tokens = shift;
582 $tokens->{foo} = 'bar';
583 };
584 The tokens hash will then be passed to the template with all the
586 modifications performed by the hook. This is a good way to setup
587 some global vars you like to have in all your templates, like the
588 name of the user logged in or a section name.
589 • "after_template_render"
591 "after_template_render" hooks are called after the view has been
593 rendered. They receive as their first argument the reference to
594 the content that has been produced. This can be used to post-
595 process the content rendered by the template engine.
596 hook after_template_render => sub {
598 my $ref_content = shift;
599 my $content = ${$ref_content};
600 # do something with $content
602 ${$ref_content} = $content;
603 };
604 • "before_layout_render"
606 "before_layout_render" hooks are called whenever the layout is
608 going to be applied to the current content. The arguments received
609 by the hook are the current tokens hashref and a reference to the
610 current content.
611 hook before_layout_render => sub {
613 my ($tokens, $ref_content) = @_;
614 $tokens->{new_stuff} = 42;
615 $ref_content = \"new content";
616 };
617 • "after_layout_render"
619 "after_layout_render" hooks are called once the complete content of
621 the view has been produced, after the layout has been applied to
622 the content. The argument received by the hook is a reference to
623 the complete content string.
624 hook after_layout_render => sub {
626 my $ref_content = shift;
627 # do something with ${ $ref_content }, which reflects directly
628 # in the caller
629 };
630 Error Handling
632 Refer to Error Hooks for details about the following hooks:
633 • "init_error"
635 • "before_error"
637 • "after_error"
639 • "on_route_exception"
641 File Rendering
643 Refer to File Handler for details on the following hooks:
644 • "before_file_render"
646 • "after_file_render"
648 Serializers
650 • "before_serializer" is called before serializing the content, and
651 receives the content to serialize as an argument.
652 hook before_serializer => sub {
654 my $content = shift;
655 ...
656 };
657 • "after_serializer" is called after the payload has been serialized,
659 and receives the serialized content as an argument.
660 hook after_serializer => sub {
662 my $serialized_content = shift;
663 ...
664 };
665
667 File Handler
668 Whenever a content is produced out of the parsing of a static file, the
669 Dancer2::Handler::File component is used. This component provides two
670 hooks, "before_file_render" and "after_file_render".
671 "before_file_render" hooks are called just before starting to parse the
673 file, the hook receives as its first argument the file path that is
674 going to be processed.
675 hook before_file_render => sub {
677 my $path = shift;
678 };
679 "after_file_render" hooks are called after the file has been parsed and
681 the response content produced. It receives the response object
682 (Dancer2::Core::Response) produced.
683 hook after_file_render => sub {
685 my $response = shift;
686 };
687 Auto page
689 Whenever a page that matches an existing template needs to be served,
690 the Dancer2::Handler::AutoPage component is used.
691 Writing your own
693 A route handler is a class that consumes the
694 Dancer2::Core::Role::Handler role. The class must implement a set of
695 methods: "methods", "regexp" and "code" which will be used to declare
696 the route.
697 Let's look at Dancer2::Handler::AutoPage for example.
699 First, the matching methods are "get" and "head":
701 sub methods { qw(head get) }
703 Then, the "regexp" or the path we want to match:
705 sub regexp { '/:page' }
707 Anything will be matched by this route, since we want to check if
709 there's a view named with the value of the "page" token. If not, the
710 route needs to "pass", letting the dispatching flow to proceed further.
711 sub code {
713 sub {
714 my $app = shift;
715 my $prefix = shift;
716 my $template = $app->template_engine;
718 if ( !defined $template ) {
719 $app->response->has_passed(1);
720 return;
721 }
722 my $page = $app->request->path;
724 my $layout_dir = $template->layout_dir;
725 if ( $page =~ m{^/\Q$layout_dir\E/} ) {
726 $app->response->has_passed(1);
727 return;
728 }
729 # remove leading '/', ensuring paths relative to the view
731 $page =~ s{^/}{};
732 my $view_path = $template->view_pathname($page);
733 if ( ! $template->pathname_exists( $view_path ) ) {
735 $app->response->has_passed(1);
736 return;
737 }
738 my $ct = $template->process( $page );
740 return ( $app->request->method eq 'GET' ) ? $ct : '';
741 };
742 }
743 The "code" method passed the Dancer2::Core::App object which provides
745 access to anything needed to process the request.
746 A "register" is then implemented to add the route to the registry and
748 if the "auto_page setting" is off, it does nothing.
749 sub register {
751 my ($self, $app) = @_;
752 return unless $app->config->{auto_page};
754 $app->add_route(
756 method => $_,
757 regexp => $self->regexp,
758 code => $self->code,
759 ) for $self->methods;
760 }
761 The config parser looks for a "route_handlers" section and any handler
763 defined there is loaded. Thus, any random handler can be added to your
764 app. For example, the default config file for any Dancer2 application
765 is as follows:
766 route_handlers:
768 File:
769 public_dir: /path/to/public
770 AutoPage: 1
771
773 Error Pages
774 When an HTTP error occurs (i.e. the action responds with a status code
775 other than 200), this is how Dancer2 determines what page to display.
776 • Looks in the "views/" directory for a corresponding template file
778 matching the error code (e.g. "500.tt" or "404.tt"). If such a file
779 exists, it's used to report the error.
780 • Next, looks in the "public/" directory for a corresponding HTML
782 file matching the error code (e.g. "500.html" or "404.html"). If
783 such a file exists, it's used to report the error. (Note, however,
784 that if show_errors is set to true, in the case of a 500 error the
785 static HTML page will not be shown, but will be replaced with a
786 default error page containing more informative diagnostics. For
787 more information see Dancer2::Config.)
788 • As default, render a generic error page on the fly.
790 Execution Errors
792 When an error occurs during the route execution, Dancer2 will render an
793 error page with the HTTP status code 500.
794 It's possible either to display the content of the error message or to
796 hide it with a generic error page. This is a choice left to the end-
797 user and can be controlled with the show_errors setting (see above).
798 Error Hooks
800 When an error is caught by Dancer2's core, an exception object is built
801 (of the class Dancer2::Core::Error). This class provides a hook to let
802 the user alter the error workflow if needed.
803 "init_error" hooks are called whenever an error object is built, the
805 object is passed to the hook.
806 hook init_error => sub {
808 my $error = shift;
809 # do something with $error
810 };
811 This hook was named before_error_init in Dancer, both names currently
813 are synonyms for backward-compatibility.
814 "before_error" hooks are called whenever an error is going to be
816 thrown, it receives the error object as its sole argument.
817 hook before_error => sub {
819 my $error = shift;
820 # do something with $error
821 };
822 This hook was named before_error_render in Dancer, both names currently
824 are synonyms for backward-compatibility.
825 "after_error" hooks are called whenever an error object has been
827 thrown, it receives a Dancer2::Core::Response object as its sole
828 argument.
829 hook after_error => sub {
831 my $response = shift;
832 };
833 This hook was named after_error_render in Dancer, both names currently
835 are synonyms for backward-compatibility.
836 "on_route_exception" is called when an exception has been caught, at
838 the route level, just before rethrowing it higher. This hook receives a
839 Dancer2::Core::App and the error as arguments.
840 hook on_route_exception => sub {
842 my ($app, $error) = @_;
843 };
844
846 Handling sessions
847 It's common to want to use sessions to give your web applications
848 state; for instance, allowing a user to log in, creating a session, and
849 checking that session on subsequent requests.
850 By default Dancer 2 has Simple sessions enabled. It implements a very
852 simple in-memory session storage. This will be fast and useful for
853 testing, but such sessions will not persist between restarts of your
854 app.
855 If you'd like to use a different session engine you must declare it in
857 the configuration file.
858 For example to use YAML file base sessions you need to add the
860 following to your config.yml:
861 session: YAML
863 Or, to enable session support from within your code,
865 set session => 'YAML';
867 (However, controlling settings is best done from your config file.)
869 The Dancer2::Session::YAML backend implements a file-based YAML session
871 storage to help with debugging, but shouldn't be used on production
872 systems.
873 There are other session backends, such as Dancer2::Session::Memcached,
875 which are recommended for production use.
876 You can then use the session keyword to manipulate the session:
878 Storing data in the session
880 Storing data in the session is as easy as:
882 session varname => 'value';
884 Retrieving data from the session
886 Retrieving data from the session is as easy as:
888 session('varname')
890 Or, alternatively,
892 session->read("varname")
894 Controlling where sessions are stored
896 For disc-based session backends like Dancer2::Session::YAML, session
898 files are written to the session dir specified by the "session_dir"
899 setting, which defaults to "./sessions" if not specifically set.
900 If you need to control where session files are created, you can do so
902 quickly and easily within your config file, for example:
903 session: YAML
905 engines:
906 session:
907 YAML:
908 session_dir: /tmp/dancer-sessions
909 If the directory you specify does not exist, Dancer2 will attempt to
911 create it for you.
912 Changing session ID
914 If you wish to change the session ID (for example on privilege level
916 change):
917 my $new_session_id = app->change_session_id
919 Destroying a session
921 When you're done with your session, you can destroy it:
923 app->destroy_session
925 Sessions and logging in
927 A common requirement is to check the user is logged in, and, if not,
928 require them to log in before continuing.
929 This can easily be handled using a before hook to check their session:
931 use Dancer2;
933 set session => "Simple";
934 hook before => sub {
936 if (!session('user') && request->path !~ m{^/login}) {
937 forward '/login', { requested_path => request->path };
938 }
939 };
940 get '/' => sub { return "Home Page"; };
942 get '/secret' => sub { return "Top Secret Stuff here"; };
944 get '/login' => sub {
946 # Display a login page; the original URL they requested is available as
947 # query_parameters->get('requested_path'), so could be put in a hidden field in the form
948 template 'login', { path => query_parameters->get('requested_path') };
949 };
950 post '/login' => sub {
952 # Validate the username and password they supplied
953 if (body_parameters->get('user') eq 'bob' && body_parameters->get('pass') eq 'letmein') {
954 session user => body_parameters->get('user');
955 redirect body_parameters->get('path') || '/';
956 } else {
957 redirect '/login?failed=1';
958 }
959 };
960 dance();
962 Here is what the corresponding "login.tt" file should look like. You
964 should place it in a directory called "views/":
965 <html>
967 <head>
968 <title>Session and logging in</title>
969 </head>
970 <body>
971 <form action='/login' method='POST'>
972 User Name : <input type='text' name='user'/>
973 Password: <input type='password' name='pass' />
974 <!-- Put the original path requested into a hidden
976 field so it's sent back in the POST and can be
977 used to redirect to the right page after login -->
978 <input type='hidden' name='path' value='<% path %>'/>
979 <input type='submit' value='Login' />
981 </form>
982 </body>
983 </html>
984 Of course, you'll probably want to validate your users against a
986 database table, or maybe via IMAP/LDAP/SSH/POP3/local system accounts
987 via PAM etc. Authen::Simple is probably a good starting point here!
988 A simple working example of handling authentication against a database
990 table yourself (using Dancer2::Plugin::Database which provides the
991 "database" keyword, and Crypt::SaltedHash to handle salted hashed
992 passwords (well, you wouldn't store your users passwords in the clear,
993 would you?)) follows:
994 post '/login' => sub {
996 my $user_value = body_parameters->get('user');
997 my $pass_value = body_parameters->get('pass');
998 my $user = database->quick_select('users',
1000 { username => $user_value }
1001 );
1002 if (!$user) {
1003 warning "Failed login for unrecognised user $user_value";
1004 redirect '/login?failed=1';
1005 } else {
1006 if (Crypt::SaltedHash->validate($user->{password}, $pass_value))
1007 {
1008 debug "Password correct";
1009 # Logged in successfully
1010 session user => $user;
1011 redirect body_parameters->get('path') || '/';
1012 } else {
1013 debug("Login failed - password incorrect for " . $user_value);
1014 redirect '/login?failed=1';
1015 }
1016 }
1017 };
1018 Retrieve complete hash stored in session
1020 Get complete hash stored in session:
1022 my $hash = session;
1024 Writing a session engine
1026 In Dancer 2, a session backend consumes the role
1027 Dancer2::Core::Role::SessionFactory.
1028 The following example using the Redis session demonstrates how session
1030 engines are written in Dancer 2.
1031 First thing to do is to create the class for the session engine, we'll
1033 name it "Dancer2::Session::Redis":
1034 package Dancer2::Session::Redis;
1036 use Moo;
1037 with 'Dancer2::Core::Role::SessionFactory';
1038 we want our backend to have a handle over a Redis connection. To do
1040 that, we'll create an attribute "redis"
1041 use JSON;
1043 use Redis;
1044 use Dancer2::Core::Types; # brings helper for types
1045 has redis => (
1047 is => 'rw',
1048 isa => InstanceOf['Redis'],
1049 lazy => 1,
1050 builder => '_build_redis',
1051 );
1052 The lazy attribute says to Moo that this attribute will be built
1054 (initialized) only when called the first time. It means that the
1055 connection to Redis won't be opened until necessary.
1056 sub _build_redis {
1058 my ($self) = @_;
1059 Redis->new(
1060 server => $self->server,
1061 password => $self->password,
1062 encoding => undef,
1063 );
1064 }
1065 Two more attributes, "server" and "password" need to be created. We do
1067 this by defining them in the config file. Dancer2 passes anything
1068 defined in the config to the engine creation.
1069 # config.yml
1071 ...
1072 engines:
1073 session:
1074 Redis:
1075 server: foo.mydomain.com
1076 password: S3Cr3t
1077 The server and password entries are now passed to the constructor of
1079 the Redis session engine and can be accessed from there.
1080 has server => (is => 'ro', required => 1);
1082 has password => (is => 'ro');
1083 Next, we define the subroutine "_retrieve" which will return a session
1085 object for a session ID it has passed. Since in this case, sessions are
1086 going to be stored in Redis, the session ID will be the key, the
1087 session the value. So retrieving is as easy as doing a get and
1088 decoding the JSON string returned:
1089 sub _retrieve {
1091 my ($self, $session_id) = @_;
1092 my $json = $self->redis->get($session_id);
1093 my $hash = from_json( $json );
1094 return bless $hash, 'Dancer2::Core::Session';
1095 }
1096 The "_flush" method is called by Dancer when the session needs to be
1098 stored in the backend. That is actually a write to Redis. The method
1099 receives a "Dancer2::Core::Session" object and is supposed to store it.
1100 sub _flush {
1102 my ($self, $session) = @_;
1103 my $json = encode_json( { %{ $session } } );
1104 $self->redis->set($session->id, $json);
1105 }
1106 For the "_destroy" method which is supposed to remove a session from
1108 the backend, deleting the key from Redis is enough.
1109 sub _destroy {
1111 my ($self, $session_id) = @_;
1112 $self->redis->del($session_id);
1113 }
1114 The "_sessions" method which is supposed to list all the session IDs
1116 currently stored in the backend is done by listing all the keys that
1117 Redis has.
1118 sub _sessions {
1120 my ($self) = @_;
1121 my @keys = $self->redis->keys('*');
1122 return \@keys;
1123 }
1124 The session engine is now ready.
1126 The Session keyword
1128 Dancer2 maintains two session layers.
1130 The first layer, Dancer2::Core::Session provides a session object which
1132 represents the current session. You can read from it as many times as
1133 you want, and write to it as many times as you want.
1134 The second layer is the session engine (Dancer2::Session::Simple is one
1136 example), which is used in order to implement the reading and writing
1137 from the actual storage. This is read only once, when a request comes
1138 in (using a cookie whose value is "dancer.session" by default). At the
1139 end of a request, all the data you've written will be flushed to the
1140 engine itself, which will do the actual write to the storage (whether
1141 it's in a hash in memory, in Memcache, or in a database).
1142
1144 Returning plain content is all well and good for examples or trivial
1145 apps, but soon you'll want to use templates to maintain separation
1146 between your code and your content. Dancer2 makes this easy.
1147 Your route handlers can use the template keyword to render templates.
1149 Views
1151 In Dancer2, a file which holds a template is called a view. Views are
1152 located in the "appdir/views" directory.
1153 You can change this location by changing the setting 'views'. For
1155 instance if your templates are located in the 'templates' directory, do
1156 the following:
1157 set views => path( app->location , 'templates' );
1159 By default, the internal template engine Dancer2::Template::Simple is
1161 used, but you may want to upgrade to Template Toolkit
1162 <http://www.template-toolkit.org/>. If you do so, you have to enable
1163 this engine in your settings as explained in
1164 Dancer2::Template::TemplateToolkit and you'll also have to install the
1165 Template module.
1166 In order to render a view, just call the template keyword at the end of
1168 the action by giving the view name and the HASHREF of tokens to
1169 interpolate in the view (note that for convenience, the request,
1170 session, params and vars are automatically accessible in the view,
1171 named "request", "session", "params", and "vars") - for example:
1172 hook before => sub { var time => scalar(localtime) };
1174 get '/hello/:name' => sub {
1176 my $name = route_parameters->get('name');
1177 template 'hello.tt', { name => $name };
1178 };
1179 The template "hello.tt" could contain, for example:
1181 <p>Hi there, [% name %]!</p>
1183 <p>You're using [% request.user_agent %]</p>
1184 [% IF session.username %]
1185 <p>You're logged in as [% session.username %]</p>
1186 [% END %]
1187 It's currently [% vars.time %]
1188 For a full list of the tokens automatically added to your template
1190 (like "session", "request", and "vars", refer to
1191 Dancer2::Core::Role::Template).
1192 By default, views use a .tt extension. This can be overridden by
1194 setting the "extension" attribute in the template engine configuration:
1195 set engines => {
1197 template => {
1198 template_toolkit => {
1199 extension => 'foo',
1200 },
1201 },
1202 };
1203 Layouts
1205 A layout is a special view, located in the layouts directory (inside
1206 the views directory) which must have a token named "content". That
1207 token marks the place where to render the action view. This lets you
1208 define a global layout for your actions, and have each individual view
1209 contain only specific content. This is a good thing and helps avoid
1210 lots of needless duplication of HTML. :)
1211 For example, the layout views/layouts/main.tt:
1213 <html>
1215 <head>...</head>
1216 <body>
1217 <div id="header">
1218 ...
1219 </div>
1220 <div id="content">
1222 [% content %]
1223 </div>
1224 </body>
1226 </html>
1227 You can tell your app which layout to use with "layout: name" in the
1229 config file, or within your code:
1230 set layout => 'main';
1232 You can control which layout to use (or whether to use a layout at all)
1234 for a specific request without altering the layout setting by passing
1235 an options hashref as the third param to the template keyword:
1236 template 'index.tt', {}, { layout => undef };
1238 If your application is not mounted under root ("/"), you can use a
1240 "before_template_render" hook instead of hardcoding the path into your
1241 application for your CSS, images and JavaScript:
1242 hook before_template_render => sub {
1244 my $tokens = shift;
1245 $tokens->{uri_base} = request->base->path;
1246 };
1247 Then in your layout, modify your CSS inclusion as follows:
1249 <link rel="stylesheet" href="[% uri_base %]/css/style.css" />
1251 From now on you can mount your application wherever you want, without
1253 any further modification of the CSS inclusion.
1254 Encoding
1256 If you use Plack and have a Unicode problem with your Dancer2
1257 application, don't forget to check if you have set your template engine
1258 to use Unicode, and set the default charset to UTF-8. So, if you are
1259 using template toolkit, your config file will look like this:
1260 charset: UTF-8
1262 engines:
1263 template:
1264 template_toolkit:
1265 ENCODING: utf8
1266 Default Template Variables
1268 Every template knows about the following variables, which are provided
1269 by Dancer2::Core::Role::Template. Some are similar to the keywords you
1270 can use in the Perl part of your Dancer2 application.
1271 • perl_version
1273 Current version of perl, effectively $^V
1275 <http://perldoc.perl.org/perlvar.html#%24%5eV>.
1276 • dancer_version
1278 Current version of Dancer2, effectively "Dancer2->VERSION".
1280 • settings
1282 A hash of the application configuration. This is like the config
1284 keyword.
1285 • request
1287 The current request object. This is like the request keyword.
1289 • params
1291 A hash reference of all the parameters.
1293 Currently the equivalent of "$request->params", and like the params
1295 keyword.
1296 • vars
1298 The list of request variables, which is what you would get if you
1300 called the vars keyword.
1301 • session
1303 The current session data, if a session exists. This is like the
1305 session keyword.
1306
1308 Static Directory
1309 Static files are served from the ./public directory. You can specify a
1310 different location by setting the "public_dir" option:
1311 set public_dir => path( app->location , 'static' );
1313 When you modify default public_dir you have to set "static_handler"
1315 option.
1316 set static_handler => true;
1318 Note that the public directory name is not included in the URL. A file
1320 ./public/css/style.css is made available as
1321 <http://example.com/css/style.css>.
1322 Static File from a Route Handler
1324 It's possible for a route handler to send a static file, as follows:
1325 get '/download/*' => sub {
1327 my ($file) = splat;
1328 send_file $file;
1330 };
1331 Or even if you want your index page to be a plain old index.html file,
1333 just do:
1334 get '/' => sub {
1336 send_file '/index.html'
1337 };
1338
1340 Files are uploaded in Dancer2 using the class
1341 Dancer2::Core::Request::Upload. The objects are accessible within the
1342 route handlers using the "upload" keyword:
1343 post '/upload' => sub {
1345 my $upload = upload('file_input_name'); # upload object
1346 $upload->copy_to('Uploads/');
1347 };
1348
1350 Configuration and environments
1351 Configuring a Dancer2 application can be done in many ways. The easiest
1352 one (and maybe the dirtiest) is to put all your settings statements at
1353 the top of your script, before calling the "dance()" method.
1354 Other ways are possible: for example, you can define all your settings
1356 in the file "appdir/config.yml". For this, you must have installed the
1357 YAML module, and of course, write the config file in YAML.
1358 That's better than the first option, but it's still not perfect as you
1360 can't switch easily from an environment to another without rewriting
1361 the config file.
1362 A better solution is to have one config.yml file with default global
1364 settings, like the following:
1365 # appdir/config.yml
1367 logger: 'file'
1368 layout: 'main'
1369 And then write as many environment files as you like in
1371 "appdir/environments". That way, the appropriate environment config
1372 file will be loaded according to the running environment (if none is
1373 specified, it will be 'development').
1374 You can change the running environment when starting your app using the
1376 "plackup" command's "--env" or "--E" switch:
1377 plackup -E production bin/app.psgi
1379 Altenatively, you can set the "DANCER_ENVIRONMENT"
1381 <https://metacpan.org/pod/Dancer2::Config#DANCER_ENVIRONMENT>
1382 environment variable in the shell or in your web server's configuration
1383 file.
1384 Typically, you'll want to set the following values in a development
1386 config file:
1387 # appdir/environments/development.yml
1389 log: 'debug'
1390 startup_info: 1
1391 show_errors: 1
1392 And in a production one:
1394 # appdir/environments/production.yml
1396 log: 'warning'
1397 startup_info: 0
1398 show_errors: 0
1399 Please note that you are not limited to writing configuration files in
1401 YAML. Dancer2 supports any file format that is supported by
1402 Config::Any, such as JSON, XML, INI files, and Apache-style config
1403 files. See the Dancer2 configuration guide
1404 <https://metacpan.org/pod/Dancer2::Config#MANIPULATING-SETTINGS-VIA-
1405 CONFIGURATION-FILES> for more information.
1406 Accessing configuration information
1408 A Dancer2 application can use the "config" keyword to easily access the
1409 settings within its config file, for instance:
1410 get '/appname' => sub {
1412 return "This is " . config->{appname};
1413 };
1414 This makes keeping your application's settings all in one place simple
1416 and easy - you shouldn't need to worry about implementing all that
1417 yourself. :)
1418 Settings
1420 It's possible to change almost every parameter of the application via
1421 the settings mechanism.
1422 A setting is a key/value pair assigned by the keyword set:
1424 set setting_name => 'setting_value';
1426 More usefully, settings can be defined in a configuration file.
1428 Environment-specific settings can also be defined in environment-
1429 specific files (for instance, you do not want to show error stacktraces
1430 in production, and might want extra logging in development).
1431 Serializers
1433 When writing a webservice, data serialization/deserialization is a
1434 common issue to deal with. Dancer2 can automatically handle that for
1435 you, via a serializer.
1436 When setting up a serializer, a new behaviour is authorized for any
1438 route handler you define: any non-scalar response will be rendered as a
1439 serialized string, via the current serializer.
1440 Here is an example of a route handler that will return a hashref:
1442 use Dancer2;
1444 set serializer => 'JSON';
1445 get '/user/:id/' => sub {
1447 { foo => 42,
1448 number => 100234,
1449 list => [qw(one two three)],
1450 }
1451 };
1452 Dancer2 will render the response via the current serializer.
1454 Hence, with the JSON serializer set, the route handler above would
1456 result in a content like the following:
1457 {"number":100234,"foo":42,"list":["one","two","three"]}
1459 If you send a value which is validated serialized data, but is not in
1461 the form a key and value pair (such as a serialized string or a JSON
1462 array), the data will not be available in "params" but will be
1463 available in "request->data".
1464 The following serializers are available, be aware they dynamically
1466 depend on Perl modules you may not have on your system.
1467 • JSON
1469 Requires JSON.
1471 • YAML
1473 Requires YAML,
1475 • XML
1477 Requires XML::Simple.
1479 • Mutable
1481 Will try to find the appropriate serializer using the Content-Type
1483 and Accept-type header of the request.
1484 Importing using Appname
1486 An app in Dancer2 uses the class name (defined by the "package"
1487 function) to define the App name. Thus separating the App to multiple
1488 files, actually means creating multiple applications. This means that
1489 any engine defined in an application, because the application is a
1490 complete separate scope, will not be available to a different
1491 application:
1492 package MyApp::User {
1494 use Dancer2;
1495 set serializer => 'JSON';
1496 get '/view' => sub {...};
1497 }
1498 package MyApp::User::Edit {
1500 use Dancer2;
1501 get '/edit' => sub {...};
1502 }
1503 These are two different Dancer2 Apps. They have different scopes,
1505 contexts, and thus different engines. While "MyApp::User" has a
1506 serializer defined, "MyApp::User::Edit" will not have that
1507 configuration.
1508 By using the import option "appname", we can ask Dancer2 to extend an
1510 App without creating a new one:
1511 package MyApp::User {
1513 use Dancer2;
1514 set serializer => 'JSON';
1515 get '/view' => sub {...};
1516 }
1517 package MyApp::User::Edit {
1519 use Dancer2 appname => 'MyApp::User'; # extending MyApp::User
1520 get '/edit' => sub {...};
1521 }
1522 The import option "appname" allows you to seamlessly extend Dancer2
1524 Apps without creating unnecessary additional applications or repeat any
1525 definitions. This allows you to spread your application routes across
1526 multiple files and allow ease of mind when developing it, and
1527 accommodate multiple developers working on the same codebase.
1528 # app.pl
1530 use MyApp::User;
1531 use MyApp::User::Edit;
1532 # single application composed of routes provided in multiple files
1534 MyApp::User->to_app;
1535 This way only one class needs to be loaded while creating an app:
1537 # app.pl:
1539 use MyApp::User;
1540 MyApp::User->to_app;
1541
1543 Configuring logging
1544 It's possible to log messages generated by the application and by
1545 Dancer2 itself.
1546 To start logging, select the logging engine you wish to use with the
1548 "logger" setting; Dancer2 includes built-in log engines named "file"
1549 and "console", which log to a logfile and to the console respectively.
1550 To enable logging to a file, add the following to your config file:
1552 logger: 'file'
1554 Then you can choose which kind of messages you want to actually log:
1556 log: 'core' # will log debug, info, warnings, errors,
1558 # and messages from Dancer2 itself
1559 log: 'debug' # will log debug, info, warning and errors
1560 log: 'info' # will log info, warning and errors
1561 log: 'warning' # will log warning and errors
1562 log: 'error' # will log only errors
1563 If you're using the "file" logging engine, a directory "appdir/logs"
1565 will be created and will host one logfile per environment. The log
1566 message contains the time it was written, the PID of the current
1567 process, the message and the caller information (file and line).
1568 Logging your own messages
1570 Just call debug <https://metacpan.org/pod/Dancer2::Manual#debug>, info
1571 <https://metacpan.org/pod/Dancer2::Manual#info>, warning
1572 <https://metacpan.org/pod/Dancer2::Manual#warning> or error
1573 <https://metacpan.org/pod/Dancer2::Manual#error> with your message:
1574 debug "This is a debug message from my app.";
1576
1578 Using Plack::Test
1579 Plack::Test receives a common web request (using standard HTTP::Request
1580 objects), fakes a web server in order to create a proper PSGI request,
1581 and sends it to the web application. When the web application returns a
1582 PSGI response (which Dancer applications do), it will then convert it
1583 to a common web response (as a standard HTTP::Response object).
1584 This allows you to then create requests in your test, create the code
1586 reference for your web application, call them, and receive a response
1587 object, which can then be tested.
1588 Basic Example
1590 Assuming there is a web application:
1592 # MyApp.pm
1594 package MyApp;
1595 use Dancer2;
1596 get '/' => sub {'OK'};
1597 1;
1598 The following test base.t is created:
1600 # base.t
1602 use strict;
1603 use warnings;
1604 use Test::More tests => 2;
1605 use Plack::Test;
1606 use HTTP::Request;
1607 use MyApp;
1608 Creating a coderef for the application using the "to_app" keyword:
1610 my $app = MyApp->to_app;
1612 Creating a test object from Plack::Test for the application:
1614 my $test = Plack::Test->create($app);
1616 Creating the first request object and sending it to the test object to
1618 receive a response:
1619 my $request = HTTP::Request->new( GET => '/' );
1621 my $response = $test->request($request);
1622 It can now be tested:
1624 ok( $response->is_success, '[GET /] Successful request' );
1626 is( $response->content, 'OK', '[GET /] Correct content' );
1627 Putting it together
1629 # base.t
1631 use strict;
1632 use warnings;
1633 use Test::More;
1634 use Plack::Test;
1635 use HTTP::Request::Common;
1636 use MyApp;
1637 my $test = Plack::Test->create( MyApp->to_app );
1639 my $response = $test->request( GET '/' );
1640 ok( $response->is_success, '[GET /] Successful request' );
1642 is( $response->content, 'OK', '[GET /] Correct content' );
1643 done_testing();
1645 Subtests
1647 Tests can be separated using Test::More's "subtest" functionality, thus
1649 creating multiple self-contained tests that don't overwrite each other.
1650 Assuming we have a different app that has two states we want to test:
1652 # MyApp.pm
1654 package MyApp;
1655 use Dancer2;
1656 set serializer => 'JSON';
1657 get '/:user' => sub {
1659 my $user = route_parameters->get('user');
1660 $user and return { user => $user };
1662 return {};
1664 };
1665 1;
1667 This is a contrived example of a route that checks for a user
1669 parameter. If it exists, it returns it in a hash with the key 'user'.
1670 If not, it returns an empty hash
1671 # param.t
1673 use strict;
1674 use warnings;
1675 use Test::More;
1676 use Plack::Test;
1677 use HTTP::Request::Common;
1678 use MyApp;
1679 my $test = Plack::Test->create( MyApp->to_app );
1681 subtest 'A empty request' => sub {
1683 my $res = $test->request( GET '/' );
1684 ok( $res->is_success, 'Successful request' );
1685 is( $res->content '{}', 'Empty response back' );
1686 };
1687 subtest 'Request with user' => sub {
1689 my $res = $test->request( GET '/?user=sawyer_x' );
1690 ok( $res->is_success, 'Successful request' );
1691 is( $res->content '{"user":"sawyer_x"}', 'Empty response back' );
1692 };
1693 done_testing();
1695 Cookies
1697 To handle cookies, which are mostly used for maintaining sessions, the
1699 following modules can be used:
1700 • Test::WWW::Mechanize::PSGI
1702 • LWP::Protocol::PSGI
1704 • HTTP::Cookies
1706 Taking the previous test, assuming it actually creates and uses cookies
1708 for sessions:
1709 # ... all the use statements
1711 use HTTP::Cookies;
1712 my $jar = HTTP::Cookies->new;
1714 my $test = Plack::Test->create( MyApp->to_app );
1715 subtest 'A empty request' => sub {
1717 my $res = $test->request( GET '/' );
1718 ok( $res->is_success, 'Successful request' );
1719 is( $res->content '{}', 'Empty response back' );
1720 $jar->extract_cookies($res);
1721 ok( $jar->as_string, 'We have cookies!' );
1722 };
1723 subtest 'Request with user' => sub {
1725 my $req = GET '/?user=sawyer_x';
1726 $jar->add_cookie_header($req);
1727 my $res = $test->request($req);
1728 ok( $res->is_success, 'Successful request' );
1729 is( $res->content '{"user":"sawyer_x"}', 'Empty response back' );
1730 $jar->extract_cookies($res);
1731 ok( ! $jar->as_string, 'All cookies deleted' );
1733 };
1734 done_testing();
1736 Here a cookie jar is created, all requests and responses, existing
1738 cookies, as well as cookies that were deleted by the response, are
1739 checked.
1740 Accessing the configuration file
1742 By importing Dancer2 in the command line scripts, there is full access
1744 to the configuration using the imported keywords:
1745 use strict;
1747 use warnings;
1748 use Test::More;
1749 use Plack::Test;
1750 use HTTP::Request::Common;
1751 use MyApp;
1752 use Dancer2;
1753 my $appname = config->{'appname'};
1755 diag "Testing $appname";
1756 # ...
1758
1760 Carton
1761 What it does
1762 Carton sets up a local copy of your project prerequisites. You only
1764 need to define them in a file and ask Carton to download all of them
1765 and set them up. When you want to deploy your app, you just carry the
1766 git clone and ask Carton to set up the environment again and you will
1767 then be able to run it.
1768 The benefits are multifold:
1770 • Local Directory copy
1772 By putting all the dependencies in a local directory, you can make
1774 sure they aren't updated by someone else by accident and their
1775 versions locked to the version you picked.
1776 • Sync versions
1778 Deciding which versions of the dependent modules your project needs
1780 allows you to sync this with other developers as well. Now you're
1781 all using the same version and they don't change unless you want
1782 update the versions you want. When updated everyone again uses the
1783 same new version of everything.
1784 • Carry only the requirement, not bundled modules
1786 Instead of bundling the modules, you only actually bundle the
1788 requirements. Carton builds them for you when you need it.
1789 Setting it up
1791 First set up a new app:
1793 $ dancer2 -a MyApp
1795 ...
1796 Delete the files that are not needed:
1798 $ rm -f Makefile.PL MANIFEST MANIFEST.SKIP
1800 Create a git repo:
1802 $ git init && git add . && git commit -m "initial commit"
1804 Add a requirement using the cpanfile format:
1806 $ cat > cpanfile
1808 requires 'Dancer2' => 0.155000;
1809 requires 'Template' => 0;
1810 recommends 'URL::Encode::XS' => 0;
1811 recommends 'CGI::Deurl::XS' => 0;
1812 recommends 'HTTP::Parser::XS' => 0;
1813 Ask carton to set it up:
1815 $ carton install
1817 Installing modules using [...]
1818 Successfully installed [...]
1819 ...
1820 Complete! Modules were install into [...]/local
1821 Now we have two files: cpanfile and cpanfile.snapshot. We add both of
1823 them to our Git repository and we make sure we don't accidentally add
1824 the local/ directory Carton created which holds the modules it
1825 installed:
1826 $ echo local/ >> .gitignore
1828 $ git add .gitignore cpanfile cpanfile.snapshot
1829 $ git commit -m "Start using carton"
1830 When we want to update the versions on the production machine, we
1832 simply call:
1833 $ carton install --deployment
1835 By using --deployment we make sure we only install the modules we have
1837 in our cpanfile.snapshot file and do not fallback to querying the CPAN.
1838 FatPacker
1840 App::FatPacker (using its command line interface, fatpack) packs
1841 dependencies into a single file, allowing you to carry a single file
1842 instead of a directory tree.
1843 As long as your application is pure-Perl, you could create a single
1845 file with your application and all of Dancer2 in it.
1846 The following example will demonstrate how this can be done:
1848 Assuming we have an application in lib/MyApp.pm:
1850 package MyApp;
1852 use Dancer2;
1853 get '/' => sub {'OK'};
1854 1;
1855 And we have a handler in bin/app.pl:
1857 use strict;
1859 use warnings;
1860 use FindBin;
1861 use lib "$FindBin::Bin/../lib";
1862 use MyApp;
1863 MyApp->to_app;
1865 To fatpack it, we begin by tracing the script:
1867 $ fatpack trace bin/app.pl
1869 This creates a fatpacker.trace file. From this we create the packlists:
1871 $ fatpack packlists-for `cat fatpacker.trace` > packlists
1873 The packlists are stored in a file called packlists.
1875 Now we create the tree using the following command:
1877 $ fatpack tree `cat packlists`
1879 The tree is created under the directory fatlib.
1881 Now we create a file containing the dependency tree, and add our script
1883 to it, using the following command:
1884 $ (fatpack file; cat bin/app.pl) > myapp.pl
1886 This creates a file called myapp.pl with everything in it. Dancer2 uses
1888 MIME::Types which has a database of all MIME types and helps translate
1889 those. The small database file containing all of these types is a
1890 binary and therefore cannot be fatpacked. Hence, it needs to be copied
1891 to the current directory so our script can find it:
1892 $ cp fatlib/MIME/types.db .
1894
1896 Plack middlewares
1897 If you want to use Plack middlewares, you need to enable them using
1898 Plack::Builder as such:
1899 # in app.psgi or any other handler
1901 use MyApp;
1902 use Plack::Builder;
1903 builder {
1905 enable 'Deflater';
1906 enable 'Session', store => 'File';
1907 enable 'Debug', panels => [ qw<DBITrace Memory Timer> ];
1908 MyApp->to_app;
1909 };
1910 The nice thing about this setup is that it will work seamlessly through
1912 Plack or through the internal web server.
1913 # load dev web server (without middlewares)
1915 perl -Ilib app.psgi
1916 # load plack web server (with middlewares)
1918 plackup -I lib app.psgi
1919 You do not need to provide different files for either server.
1921 Path-based middlewares
1923 If you want to set up a middleware for a specific path, you can do that
1925 using Plack::Builder which uses Plack::App::URLMap:
1926 # in your app.psgi or any other handler
1928 use MyApp;
1929 use Plack::Builder;
1930 my $special_handler = sub { ... };
1932 builder {
1934 mount '/special' => $special_handler;
1935 mount '/' => MyApp->to_app;
1936 };
1937 Removing default middlewares
1939 By default, a Dancer2 app is automatically wrapped with the following
1941 middleware
1942 • Plack::Middleware::FixMissingBodyInRedirect
1944 • Plack::Middleware::Head
1946 You can configure the setting "no_default_middleware" to a true value
1948 to stop your Dancer2 app being wrapped with these default middleware
1949 layers.
1950 # in you Dancer2 app or config.yml
1952 package MyApp;
1953 use Dancer2
1954 set no_default_middleware => true;
1956 This is necessary if you need to add eTag or ContentMD5 headers to
1958 "HEAD" requests, and you are encouraged to manually add those default
1959 middleware back into your PSGI stack.
1960 Running on Perl web servers with plackup
1962 A number of Perl web servers supporting PSGI are available on CPAN:
1964 • Starman
1966 "Starman" is a high performance web server, with support for
1968 preforking, signals, multiple interfaces, graceful restarts and
1969 dynamic worker pool configuration.
1970 • Twiggy
1972 "Twiggy" is an "AnyEvent" web server, it's light and fast.
1974 • Corona
1976 "Corona" is a "Coro" based web server.
1978 To start your application, just run plackup (see Plack and specific
1980 servers above for all available options):
1981 $ plackup bin/app.psgi
1983 $ plackup -E deployment -s Starman --workers=10 -p 5001 -a bin/app.psgi
1984 As you can see, the scaffolded Perl script for your app can be used as
1986 a PSGI startup file.
1987 Enabling content compression
1989 Content compression (gzip, deflate) can be easily enabled via a Plack
1991 middleware (see "Plack::Middleware" in Plack):
1992 Plack::Middleware::Deflater. It's a middleware to encode the response
1993 body in gzip or deflate, based on the "Accept-Encoding" HTTP request
1994 header.
1995 Enable it as you would enable any Plack middleware. First you need to
1997 install Plack::Middleware::Deflater, then in the handler (usually
1998 app.psgi) edit it to use Plack::Builder, as described above:
1999 use Dancer2;
2001 use MyApp;
2002 use Plack::Builder;
2003 builder {
2005 enable 'Deflater';
2006 MyApp->to_app;
2007 };
2008 To test if content compression works, trace the HTTP request and
2010 response before and after enabling this middleware. Among other things,
2011 you should notice that the response is gzip or deflate encoded, and
2012 contains a header "Content-Encoding" set to "gzip" or "deflate".
2013 Running multiple apps with Plack::Builder
2015 You can use Plack::Builder to mount multiple Dancer2 applications on a
2017 PSGI webserver like Starman.
2018 Start by creating a simple app.psgi file:
2020 use OurWiki; # first app
2022 use OurForum; # second app
2023 use Plack::Builder;
2024 builder {
2026 mount '/wiki' => OurWiki->to_app;
2027 mount '/forum' => OurForum->to_app;
2028 };
2029 and now use Starman
2031 plackup -a app.psgi -s Starman
2033 Currently this still demands the same appdir for both (default
2035 circumstance) but in a future version this will be easier to change
2036 while staying very simple to mount.
2037 Running from Apache with Plack
2039 You can run your app from Apache using PSGI (Plack), with a config like
2041 the following:
2042 <VirtualHost myapp.example.com>
2044 ServerName www.myapp.example.com
2045 ServerAlias myapp.example.com
2046 DocumentRoot /websites/myapp.example.com
2047 <Directory /home/myapp/myapp>
2049 AllowOverride None
2050 Order allow,deny
2051 Allow from all
2052 </Directory>
2053 <Location />
2055 SetHandler perl-script
2056 PerlResponseHandler Plack::Handler::Apache2
2057 PerlSetVar psgi_app /websites/myapp.example.com/app.psgi
2058 </Location>
2059 ErrorLog /websites/myapp.example.com/logs/error_log
2061 CustomLog /websites/myapp.example.com/logs/access_log common
2062 </VirtualHost>
2063 To set the environment you want to use for your application (production
2065 or development), you can set it this way:
2066 <VirtualHost>
2068 ...
2069 SetEnv DANCER_ENVIRONMENT "production"
2070 ...
2071 </VirtualHost>
2072
2074 Writing a plugin
2075 See "Writing the plugin" in Dancer2::Plugin for information on how to
2076 author a new plugin for Dancer2.
2077
2079 By default, "use Dancer2" exports all the DSL keywords and sets up the
2080 webapp under the name of the current package. The following tags
2081 control exports and webapp namespace.
2082 • !keyword
2084 If you want to prevent Dancer2 from exporting specific keywords
2086 (perhaps you plan to implement them yourself in a different way, or
2087 they clash with another module you're loading), you can simply
2088 exclude them:
2089 use Test::More;
2091 use Dancer2 qw(!pass);
2092 The above would import all keywords as usual, with the exception of
2094 "pass".
2095 • appname
2097 A larger application may split its source between several packages
2099 to aid maintainability. Dancer2 will create a separate application
2100 for each package, each having separate hooks, config and/or
2101 engines. You can force Dancer2 to collect the route and hooks into
2102 a single application with the "appname" tag; e.g.
2103 package MyApp;
2105 use Dancer2;
2106 get '/foo' => sub {...};
2107 package MyApp::Private;
2109 use Dancer2 appname => MyApp;
2110 get '/bar' => sub {...};
2111 The above would add the "bar" route to the MyApp application.
2113 Dancer2 will not create an application with the name
2114 "MyApp::Private".
2115 • :nopragmas
2117 By default Dancer2 will import three pragmas: strict, warnings, and
2119 utf8. If you require control over the imported pragmas, you can add
2120 :nopragmas to the importing flags, in which case Dancer2 will not
2121 import any pragmas:
2122 use strict;
2124 use warnings;
2125 no warnings 'experimental::smartmatch'; # for example...
2126 use Dancer2 ':nopragmas'; # do not touch the existing pragmas
2127 This way importing "Dancer2" does not change the existing pragmas
2129 setup you have.
2130 When you "use Dancer2", you get an "import" method added into the
2132 current package. This will override previously declared import methods
2133 from other sources, such as Exporter. Dancer2 applications support the
2134 following tags on import:
2135 • with
2137 The "with" tag allows an app to pass one or more config entries to
2139 another app, when it "use"s it.
2140 package MyApp;
2142 use Dancer2;
2143 BEGIN { set session => 'YAML' };
2145 use Blog with => { session => engine('session') };
2146 In this example, the session engine is passed to the "Blog" app.
2148 That way, anything done in the session will be shared between both
2149 apps.
2150 Anything that is defined in the config entry can be passed that
2152 way. If we want to pass the whole config object, it can be done
2153 like so:
2154 use SomeApp with => { %{config()} };
2156
2158 Dancer2 provides you with a DSL (Domain-Specific Language) which makes
2159 implementing your web application trivial.
2160 For example, take the following example:
2162 use Dancer2;
2164 get '/hello/:name' => sub {
2166 my $name = route_parameters->get('name');
2167 };
2168 dance;
2169 "get" and "route_parameters" are keywords provided by Dancer2.
2171 This document lists all keywords provided by Dancer2. It does not cover
2173 additional keywords which may be provided by loaded plugins; see the
2174 documentation for plugins you use to see which additional keywords they
2175 make available to you.
2176 any
2178 Defines a route for multiple HTTP methods at once:
2179 any ['get', 'post'] => '/myaction' => sub {
2181 # code
2182 };
2183 Or even, a route handler that would match any HTTP methods:
2185 any '/myaction' => sub {
2187 # code
2188 };
2189 cookies
2191 Accesses cookies values, it returns a hashref of Dancer2::Core::Cookie
2192 objects:
2193 get '/some_action' => sub {
2195 my $cookie = cookies->{name};
2196 return $cookie->value;
2197 };
2198 In case you have stored something other than a scalar in your cookie:
2200 get '/some_action' => sub {
2202 my $cookie = cookies->{oauth};
2203 my %values = $cookie->value;
2204 return ($values{token}, $values{token_secret});
2205 };
2206 cookie
2208 Accesses a cookie value (or sets it). Note that this method will
2209 eventually be preferred over "set_cookie".
2210 cookie lang => "fr-FR"; # set a cookie and return its value
2212 cookie lang => "fr-FR", expires => "2 hours"; # extra cookie info
2213 cookie "lang" # return a cookie value
2214 If your cookie value is a key/value URI string, like
2216 token=ABC&user=foo
2218 "cookie" will only return the first part ("token=ABC") if called in
2220 scalar context. Use list context to fetch them all:
2221 my @values = cookie "name";
2223 config
2225 Accesses the configuration of the application:
2226 get '/appname' => sub {
2228 return "This is " . config->{appname};
2229 };
2230 content
2232 Sets the content for the response. This only works within a delayed
2233 response.
2234 This will crash:
2236 get '/' => sub {
2238 # THIS WILL CRASH
2239 content 'Hello, world!';
2240 };
2241 But this will work just fine:
2243 get '/' => sub {
2245 delayed {
2246 content 'Hello, world!';
2247 ...
2248 };
2249 };
2250 content_type
2252 Sets the content-type rendered, for the current route handler:
2253 get '/cat/:txtfile' => sub {
2255 content_type 'text/plain';
2256 # here we can dump the contents of route_parameters->get('txtfile')
2258 };
2259 You can use abbreviations for content types. For instance:
2261 get '/svg/:id' => sub {
2263 content_type 'svg';
2264 # here we can dump the image with id route_parameters->get('id')
2266 };
2267 Note that if you want to change the default content-type for every
2269 route, it is easier to change the "content_type" setting instead.
2270 dance
2272 Alias for the "start" keyword.
2273 dancer_version
2275 Returns the version of Dancer. If you need the major version, do
2276 something like:
2277 int(dancer_version);
2279 debug
2281 Logs a message of debug level:
2282 debug "This is a debug message";
2284 See Dancer2::Core::Role::Logger for details on how to configure where
2286 log messages go.
2287 decode_json ($string)
2289 Deserializes a JSON structure from an UTF-8 binary string.
2290 dirname
2292 Returns the dirname of the path given:
2293 my $dir = dirname($some_path);
2295 encode_json ($structure)
2297 Serializes a structure to a UTF-8 binary JSON string.
2298 Calling this function will not trigger the serialization's hooks.
2300 engine
2302 Given a namespace, returns the current engine object
2303 my $template_engine = engine 'template';
2305 my $html = $template_engine->apply_renderer(...);
2306 $template_engine->apply_layout($html);
2307 error
2309 Logs a message of error level:
2310 error "This is an error message";
2312 See Dancer2::Core::Role::Logger for details on how to configure where
2314 log messages go.
2315 false
2317 Constant that returns a false value (0).
2318 forward
2320 Runs an "internal redirect" of the current route to another route. More
2321 formally; when "forward" is executed, the current dispatch of the route
2322 is aborted, the request is modified (altering query params or request
2323 method), and the modified request following a new route is dispatched
2324 again. Any remaining code (route and hooks) from the current dispatch
2325 will never be run and the modified route's dispatch will execute hooks
2326 for the new route normally.
2327 It effectively lets you chain routes together in a clean manner.
2329 get '/demo/articles/:article_id' => sub {
2331 # you'll have to implement this next sub yourself :)
2333 change_the_main_database_to_demo();
2334 forward "/articles/" . route_parameters->get('article_id');
2336 };
2337 In the above example, the users that reach /demo/articles/30 will
2339 actually reach /articles/30 but we've changed the database to demo
2340 before.
2341 This is pretty cool because it lets us retain our paths and offer a
2343 demo database by merely going to /demo/....
2344 You'll notice that in the example we didn't indicate whether it was GET
2346 or POST. That is because "forward" chains the same type of route the
2347 user reached. If it was a GET, it will remain a GET (but if you do need
2348 to change the method, you can do so; read on below for details.)
2349 Also notice that "forward" only redirects to a new route. It does not
2351 redirect the requests involving static files. This is because static
2352 files are handled before Dancer2 tries to match the request to a route
2353 - static files take higher precedence.
2354 This means that you will not be able to "forward" to a static file. If
2356 you wish to do so, you have two options: either redirect (asking the
2357 browser to make another request, but to a file path instead) or use
2358 "send_file" to provide a file.
2359 WARNING: Any code after a "forward" is ignored, until the end of the
2361 route. It's not necessary to use "return" with "forward" anymore.
2362 get '/foo/:article_id' => sub {
2364 if ($condition) {
2365 forward "/articles/" . route_parameters->get('article_id');
2366 # The following code WILL NOT BE executed
2367 do_stuff();
2368 }
2369 more_stuff();
2371 };
2372 Note that "forward" doesn't parse GET arguments. So, you can't use
2374 something like:
2375 forward '/home?authorized=1';
2377 But "forward" supports an optional hashref with parameters to be added
2379 to the actual parameters:
2380 forward '/home', { authorized => 1 };
2382 Finally, you can add some more options to the "forward" method, in a
2384 third argument, also as a hashref. That option is currently only used
2385 to change the method of your request. Use with caution.
2386 forward '/home', { auth => 1 }, { method => 'POST' };
2388 from_dumper ($structure)
2390 Deserializes a Data::Dumper structure.
2391 from_json ($string, \%options)
2393 Deserializes a JSON structure from a string. You should probably use
2394 "decode_json" which expects a UTF-8 encoded binary string and handles
2395 decoding it for you.
2396 from_yaml ($structure)
2398 Deserializes a YAML structure.
2399 get
2401 Defines a route for HTTP GET requests to the given path:
2402 get '/' => sub {
2404 return "Hello world";
2405 }
2406 Note that a route to match HEAD requests is automatically created as
2408 well.
2409 halt
2411 Sets a response object with the content given.
2412 When used as a return value from a hook, this breaks the execution flow
2414 and renders the response immediately:
2415 hook before => sub {
2417 if ($some_condition) {
2418 halt("Unauthorized");
2419 # this code is not executed
2421 do_stuff();
2422 }
2423 };
2424 get '/' => sub {
2426 "hello there";
2427 };
2428 WARNING: Issuing a halt immediately exits the current route, and
2430 performs the halt. Thus, any code after a halt is ignored, until the
2431 end of the route. Hence, it's not necessary anymore to use "return"
2432 with halt.
2433 response_headers
2435 Adds custom headers to response:
2436 get '/send/headers', sub {
2438 response_headers 'X-Foo' => 'bar', 'X-Bar' => 'foo';
2439 }
2440 response_header
2442 Adds a custom header to response:
2443 get '/send/header', sub {
2445 response_header 'x-my-header' => 'shazam!';
2446 }
2447 Note that it will overwrite the old value of the header, if any. To
2449 avoid that, see "push_response_header".
2450 push_response_header
2452 Do the same as "response_header", but allow for multiple headers with
2453 the same name.
2454 get '/send/header', sub {
2456 push_response_header 'x-my-header' => '1';
2457 push_response_header 'x-my-header' => '2';
2458 # will result in two headers "x-my-header" in the response
2459 }
2460 prepare_app
2462 You can introduce code you want to run when your app is loaded, similar
2463 to the "prepare_app" in Plack::Middleware.
2464 prepare_app {
2466 my $app = shift;
2467 ... # do your thing
2469 };
2470 You should not close over the App instance, since you receive it as a
2472 first argument. If you close over it, you will have a memory leak.
2473 my $app = app();
2475 prepare_app {
2477 do_something_with_app($app); # MEMORY LEAK
2478 };
2479 hook
2481 Adds a hook at some position. For example :
2482 hook before_serializer => sub {
2484 my $content = shift;
2485 ...
2486 };
2487 There can be multiple hooks assigned to a given position, and each will
2489 be executed in order.
2490 See the HOOKS section for a list of available hooks.
2492 info
2494 Logs a message of "info" level:
2495 info "This is an info message";
2497 See Dancer2::Core::Role::Logger for details on how to configure where
2499 log messages go.
2500 mime
2502 Shortcut to access the instance object of Dancer2::Core::MIME. You
2503 should read the Dancer2::Core::MIME documentation for full details, but
2504 the most commonly-used methods are summarized below:
2505 # set a new mime type
2507 mime->add_type( foo => 'text/foo' );
2508 # set a mime type alias
2510 mime->add_alias( f => 'foo' );
2511 # get mime type for an alias
2513 my $m = mime->for_name( 'f' );
2514 # get mime type for a file (based on extension)
2516 my $m = mime->for_file( "foo.bar" );
2517 # get current defined default mime type
2519 my $d = mime->default;
2520 # set the default mime type using config.yml
2522 # or using the set keyword
2523 set default_mime_type => 'text/plain';
2524 params
2526 This method should be called from a route handler. It's an alias for
2527 the Dancer2::Core::Request params accessor. It returns a hash (in list
2528 context) or a hash reference (in scalar context) to all defined
2529 parameters. Check "param" below to access quickly to a single parameter
2530 value.
2531 post '/login' => sub {
2533 # get all parameters as a single hash
2534 my %all_parameters = params;
2535 // request all parmameters from a specific source: body, query, route
2537 my %body_parameters = params('body');
2538 my %route_parameters = params('route');
2539 my %query_parameters = params('query');
2540 # any $source that is not body, query, or route generates an exception
2542 params('fake_source'); // Unknown source params "fake_source"
2543 };
2544 We now recommend using one of the specific keywords for parameters
2546 ("route_parameters", "query_parameters", and "body_parameters") instead
2547 of "params" or "param".
2548 param
2550 This method should be called from a route handler. This method is an
2551 accessor to the parameters hash table.
2552 post '/login' => sub {
2554 my $username = param "user";
2555 my $password = param "pass";
2556 # ...
2557 };
2558 We now recommend using one of the specific keywords for parameters
2560 ("route_parameters", "query_parameters", and "body_parameters") instead
2561 of "params" or "param".
2562 route_parameters
2564 Returns a Hash::MultiValue object from the route parameters.
2565 # /hello
2567 get '/:foo' => sub {
2568 my $foo = route_parameters->get('foo');
2569 };
2570 query_parameters
2572 Returns a Hash::MultiValue object from the request parameters.
2573 /?foo=hello
2575 get '/' => sub {
2576 my $name = query_parameters->get('foo');
2577 };
2578 /?name=Alice&name=Bob
2580 get '/' => sub {
2581 my @names = query_parameters->get_all('name');
2582 };
2583 body_parameters
2585 Returns a Hash::MultiValue object from the body parameters.
2586 post '/' => sub {
2588 my $last_name = body_parameters->get('name');
2589 my @all_names = body_parameters->get_all('name');
2590 };
2591 pass
2593 This method should be called from a route handler. Tells Dancer2 to
2594 pass the processing of the request to the next matching route.
2595 WARNING: Issuing a pass immediately exits the current route, and
2597 performs the pass. Thus, any code after a pass is ignored, until the
2598 end of the route. Hence, it's not necessary anymore to use "return"
2599 with pass.
2600 get '/some/route' => sub {
2602 if (...) {
2603 # we want to let the next matching route handler process this one
2604 pass(...);
2605 # this code will be ignored
2607 do_stuff();
2608 }
2609 };
2610 WARNING: You cannot set the content before passing and have it remain,
2612 even if you use the "content" keyword or set it directly in the
2613 response object.
2614 patch
2616 Defines a route for HTTP PATCH requests to the given URL:
2617 patch '/resource' => sub { ... };
2619 ("PATCH" is a relatively new and not-yet-common HTTP verb, which is
2621 intended to work as a "partial-PUT", transferring just the changes;
2622 please see RFC5789 <http://tools.ietf.org/html/rfc5789> for further
2623 details.)
2624 path
2626 Concatenates multiple paths together, without worrying about the
2627 underlying operating system:
2628 my $path = path(dirname($0), 'lib', 'File.pm');
2630 It also normalizes (cleans) the path aesthetically. It does not verify
2632 whether the path exists, though.
2633 post
2635 Defines a route for HTTP POST requests to the given URL:
2636 post '/' => sub {
2638 return "Hello world";
2639 }
2640 prefix
2642 Defines a prefix for each route handler, like this:
2643 prefix '/home';
2645 From here, any route handler is defined to /home/*:
2647 get '/page1' => sub {}; # will match '/home/page1'
2649 You can unset the prefix value:
2651 prefix undef;
2653 get '/page1' => sub {}; # will match /page1
2654 For a safer alternative you can use lexical prefix like this:
2656 prefix '/home' => sub {
2658 ## Prefix is set to '/home' here
2659 get ...;
2661 get ...;
2662 };
2663 ## prefix reset to the previous version here
2664 This makes it possible to nest prefixes:
2666 prefix '/home' => sub {
2668 ## some routes
2669 prefix '/private' => sub {
2671 ## here we are under /home/private...
2672 ## some more routes
2674 };
2675 ## back to /home
2676 };
2677 ## back to the root
2678 Notice: Once you have a prefix set, do not add a caret to the regex:
2680 prefix '/foo';
2682 get qr{^/bar} => sub { ... } # BAD BAD BAD
2683 get qr{/bar} => sub { ... } # Good!
2684 del
2686 Defines a route for HTTP DELETE requests to the given URL:
2687 del '/resource' => sub { ... };
2689 options
2691 Defines a route for HTTP OPTIONS requests to the given URL:
2692 options '/resource' => sub { ... };
2694 put
2696 Defines a route for HTTP PUT requests to the given URL:
2697 put '/resource' => sub { ... };
2699 redirect
2701 Generates a HTTP redirect (302). You can either redirect to a complete
2702 different site or within the application:
2703 get '/twitter', sub {
2705 redirect 'http://twitter.com/me';
2706 # Any code after the redirect will not be executed.
2707 };
2708 WARNING: Issuing a "redirect" immediately exits the current route.
2710 Thus, any code after a "redirect" is ignored, until the end of the
2711 route. Hence, it's not necessary anymore to use "return" with
2712 "redirect".
2713 You can also force Dancer to return a specific 300-ish HTTP response
2715 code:
2716 get '/old/:resource', sub {
2718 redirect '/new/' . route_parameters->get('resource'), 301;
2719 };
2720 request
2722 Returns a Dancer2::Core::Request object representing the current
2723 request.
2724 See the Dancer2::Core::Request documentation for the methods you can
2726 call, for example:
2727 request->referer; # value of the HTTP referer header
2729 request->remote_address; # user's IP address
2730 request->user_agent; # User-Agent header value
2731 request_header
2733 Returns request header(s).
2734 get '/get/headers' => sub {
2736 my $xfoo = request_header 'X-Foo';
2737 ...
2738 };
2739 send_as
2741 Allows the current route handler to return specific content types to
2742 the client using either a specified serializer or as html.
2743 Any Dancer2 serializer may be used. The specified serializer class will
2745 be loaded if required, or an error generated if the class can not be
2746 found. Serializer configuration may be added to your apps "engines"
2747 configuration.
2748 If "html" is specified, the content will be returned assuming it is
2750 HTML with appropriate "Content-Type" headers and encoded using the apps
2751 configured "charset" (or UTF-8).
2752 set serializer => 'YAML';
2754 set template => 'TemplateToolkit';
2755 # returns html (not YAML)
2757 get '/' => sub { send_as html => template 'welcome.tt' };
2758 # return json (not YAML)
2760 get '/json' => sub {
2761 send_as JSON => [ some => { data => 'structure' } ];
2762 };
2763 "send_as" uses "send_file" to return the content immediately. You may
2765 pass any option "send_file" supports as an extra option. For example:
2766 # return json with a custom content_type header
2768 get '/json' => sub {
2769 send_as JSON => [ some => { data => 'structure' } ],
2770 { content_type => 'application/json; charset=UTF-8' },
2771 };
2772 WARNING: Issuing a send_as immediately exits the current route, and
2774 performs the "send_as". Thus, any code after a "send_as" is ignored,
2775 until the end of the route. Hence, it's not necessary to use "return"
2776 with "send_as".
2777 get '/some/route' => sub {
2779 if (...) {
2780 send_as JSON => $some_data;
2781 # this code will be ignored
2783 do_stuff();
2784 }
2785 };
2786 send_error
2788 Returns a HTTP error. By default the HTTP code returned is 500:
2789 get '/photo/:id' => sub {
2791 if (...) {
2792 send_error("Not allowed", 403);
2793 } else {
2794 # return content
2795 }
2796 }
2797 WARNING: Issuing a send_error immediately exits the current route, and
2799 performs the "send_error". Thus, any code after a "send_error" is
2800 ignored, until the end of the route. Hence, it's not necessary anymore
2801 to use "return" with "send_error".
2802 get '/some/route' => sub {
2804 if (...) {
2805 # Something bad happened, stop immediately!
2806 send_error(..);
2807 # this code will be ignored
2809 do_stuff();
2810 }
2811 };
2812 send_file
2814 Lets the current route handler send a file to the client. Note that the
2815 path of the file must be relative to the public directory unless you
2816 use the "system_path" option (see below).
2817 get '/download/:file' => sub {
2819 return send_file(route_parameters->get('file'));
2820 }
2821 WARNING: Issuing a "send_file" immediately exits the current route, and
2823 performs the "send_file". Thus, any code after a "send_file" is
2824 ignored, until the end of the route. Hence, it's not necessary anymore
2825 to use "return" with "send_file".
2826 get '/some/route' => sub {
2828 if (...) {
2829 # OK, send her what she wants...
2830 send_file(...);
2831 # this code will be ignored
2833 do_stuff();
2834 }
2835 };
2836 "send_file" will use PSGI streaming if the server supports it (most, if
2838 not all, do). You can explicitly disable streaming by passing
2839 "streaming => 0" as an option to "send_file".
2840 get '/download/:file' => sub {
2842 send_file( route_parameters->get('file'), streaming => 0 );
2843 }
2844 The content-type will be set depending on the current MIME types
2846 definition (see "mime" if you want to define your own).
2847 If your filename does not have an extension, you are passing in a
2849 filehandle, or you need to force a specific mime type, you can pass it
2850 to "send_file" as follows:
2851 send_file(route_parameters->get('file'), content_type => 'image/png');
2853 send_file($fh, content_type => 'image/png');
2854 Also, you can use your aliases or file extension names on
2856 "content_type", like this:
2857 send_file(route_parameters->get('file'), content_type => 'png');
2859 The encoding of the file or filehandle may be specified by passing both
2861 the "content_type" and "charset" options. For example:
2862 send_file($fh, content_type => 'text/csv', charset => 'utf-8' );
2864 For files outside your public folder, you can use the "system_path"
2866 switch. Just bear in mind that its use needs caution as it can be
2867 dangerous.
2868 send_file('/etc/passwd', system_path => 1);
2870 If you have your data in a scalar variable, "send_file" can be useful
2872 as well. Pass a reference to that scalar, and "send_file" will behave
2873 as if there was a file with that contents:
2874 send_file( \$data, content_type => 'image/png' );
2876 Note that Dancer is unable to guess the content type from the data
2878 contents. Therefore you might need to set the "content_type" properly.
2879 For this kind of usage an attribute named "filename" can be useful. It
2880 is used as the Content-Disposition header, to hint the browser about
2881 the filename it should use.
2882 send_file( \$data, content_type => 'image/png'
2884 filename => 'onion.png' );
2885 By default the Content-Disposition header uses the "attachment" type,
2887 which triggers a "Save" dialog in some browsers. Supply a
2888 "content_disposition" attribute of "inline" to have the file displayed
2889 inline by the browser.
2890 set
2892 Defines a setting:
2893 set something => 'value';
2895 You can set more than one value at once:
2897 set something => 'value', otherthing => 'othervalue';
2899 setting
2901 Returns the value of a given setting:
2902 setting('something'); # 'value'
2904 session
2906 Provides access to all data stored in the user's session (if any).
2907 It can also be used as a setter to store data in the session:
2909 # getter example
2911 get '/user' => sub {
2912 if (session('user')) {
2913 return "Hello, ".session('user')->name;
2914 }
2915 };
2916 # setter example
2918 post '/user/login' => sub {
2919 ...
2920 if ($logged_in) {
2921 session user => $user;
2922 }
2923 ...
2924 };
2925 You may also need to clear a session:
2927 # destroy session
2929 get '/logout' => sub {
2930 ...
2931 app->destroy_session;
2932 ...
2933 };
2934 If you need to fetch the session ID being used for any reason:
2936 my $id = session->id;
2938 splat
2940 Returns the list of captures made from a route handler with a route
2941 pattern which includes wildcards:
2942 get '/file/*.*' => sub {
2944 my ($file, $extension) = splat;
2945 ...
2946 };
2947 There is also the extensive splat (A.K.A. "megasplat"), which allows
2949 extensive greedier matching, available using two asterisks. The
2950 additional path is broken down and returned as an arrayref:
2951 get '/entry/*/tags/**' => sub {
2953 my ( $entry_id, $tags ) = splat;
2954 my @tags = @{$tags};
2955 };
2956 The "splat" keyword in the above example for the route
2958 /entry/1/tags/one/two would set $entry_id to 1 and $tags to "['one',
2959 'two']".
2960 start
2962 Starts the application or the standalone server (depending on the
2963 deployment choices).
2964 This keyword should be called at the very end of the script, once all
2966 routes are defined. At this point, Dancer2 takes over.
2967 to_app
2969 Returns the PSGI coderef for the current (and only the current)
2970 application.
2971 You can call it as a method on the class or as a DSL:
2973 my $app = MyApp->to_app;
2975 # or
2977 my $app = to_app;
2979 There is a Dancer Advent Calendar article
2981 <http://advent.perldancer.org/2014/9> covering this keyword and its
2982 usage further.
2983 psgi_app
2985 Provides the same functionality as "to_app" but uses the deprecated
2986 Dispatcher engine. You should use "to_app" instead.
2987 status
2989 Changes the status code provided by an action. By default, an action
2990 will produce an "HTTP 200 OK" status code, meaning everything is OK:
2991 get '/download/:file' => {
2993 if (! -f route_parameters->get('file')) {
2994 status 'not_found';
2995 return "File does not exist, unable to download";
2996 }
2997 # serving the file...
2998 };
2999 In that example, Dancer will notice that the status has changed, and
3001 will render the response accordingly.
3002 The "status" keyword receives either a numeric status code or its name
3004 in lower case, with underscores as a separator for blanks - see the
3005 list in "HTTP CODES" in Dancer2::Core::HTTP. As an example, The above
3006 call translates to setting the code to 404.
3007 template
3009 Returns the response of processing the given template with the given
3010 parameters (and optional settings), wrapping it in the default or
3011 specified layout too, if layouts are in use.
3012 An example of a route handler which returns the result of using
3014 template to build a response with the current template engine:
3015 get '/' => sub {
3017 ...
3018 return template 'some_view', { token => 'value'};
3019 };
3020 Note that "template" simply returns the content, so when you use it in
3022 a route handler, if execution of the route handler should stop at that
3023 point, make sure you use "return" to ensure your route handler returns
3024 the content.
3025 Since "template" just returns the result of rendering the template, you
3027 can also use it to perform other templating tasks, e.g. generating
3028 emails:
3029 post '/some/route' => sub {
3031 if (...) {
3032 email {
3033 to => 'someone@example.com',
3034 from => 'foo@example.com',
3035 subject => 'Hello there',
3036 msg => template('emails/foo', { name => body_parameters->get('name') }),
3037 };
3038 return template 'message_sent';
3040 } else {
3041 return template 'error';
3042 }
3043 };
3044 Compatibility notice: "template" was changed in version 1.3090 to
3046 immediately interrupt execution of a route handler and return the
3047 content, as it's typically used at the end of a route handler to return
3048 content. However, this caused issues for some people who were using
3049 "template" to generate emails etc, rather than accessing the template
3050 engine directly, so this change has been reverted in 1.3091.
3051 The first parameter should be a template available in the views
3053 directory, the second one (optional) is a hashref of tokens to
3054 interpolate, and the third (again optional) is a hashref of options.
3055 For example, to disable the layout for a specific request:
3057 get '/' => sub {
3059 template 'index', {}, { layout => undef };
3060 };
3061 Or to request a specific layout, of course:
3063 get '/user' => sub {
3065 template 'user', {}, { layout => 'user' };
3066 };
3067 Some tokens are automatically added to your template ("perl_version",
3069 "dancer_version", "settings", "request", "vars" and, if you have
3070 sessions enabled, "session"). Check Default Template Variables for
3071 further details.
3072 to_dumper ($structure)
3074 Serializes a structure with Data::Dumper.
3075 Calling this function will not trigger the serialization's hooks.
3077 to_json ($structure, \%options)
3079 Serializes a structure to JSON. You should probably use "encode_json"
3080 instead which handles encoding the result for you.
3081 to_yaml ($structure)
3083 Serializes a structure to YAML.
3084 Calling this function will not trigger the serialization's hooks.
3086 true
3088 Constant that returns a true value (1).
3089 upload
3091 Provides access to file uploads. Any uploaded file is accessible as a
3092 Dancer2::Core::Request::Upload object. You can access all parsed
3093 uploads via:
3094 post '/some/route' => sub {
3096 my $file = upload('file_input_foo');
3097 # $file is a Dancer2::Core::Request::Upload object
3098 };
3099 If you named multiple inputs of type "file" with the same name, the
3101 "upload" keyword would return an Array of
3102 Dancer2::Core::Request::Upload objects:
3103 post '/some/route' => sub {
3105 my ($file1, $file2) = upload('files_input');
3106 # $file1 and $file2 are Dancer2::Core::Request::Upload objects
3107 };
3108 You can also access the raw hashref of parsed uploads via the current
3110 "request" object:
3111 post '/some/route' => sub {
3113 my $all_uploads = request->uploads;
3114 # $all_uploads->{'file_input_foo'} is a Dancer2::Core::Request::Upload object
3115 # $all_uploads->{'files_input'} is an arrayref of Dancer2::Core::Request::Upload objects
3116 };
3117 Note that you can also access the filename of the upload received via
3119 the "body_parameters" keyword:
3120 post '/some/route' => sub {
3122 # body_parameters->get('files_input') is the filename of the file uploaded
3123 };
3124 See Dancer2::Core::Request::Upload for details about the interface
3126 provided.
3127 uri_for
3129 Returns a fully-qualified URI for the given path:
3130 get '/' => sub {
3132 redirect uri_for('/path');
3133 # can be something like: http://localhost:5000/path
3134 };
3135 Query string parameters can be provided by passing a hashref as a
3137 second param:
3138 uri_for('/path', { foo => 'bar' });
3140 # would return e.g. http://localhost:5000/path?foo=bar
3141 By default, the parameters will be URL encoded:
3143 uri_for('/path', { foo => 'hope;faith' });
3145 # would return http://localhost:5000/path?foo=hope%3Bfaith
3146 If desired (for example, if you've already encoded your query
3148 parameters and you want to prevent double encoding) you can disable URL
3149 encoding via a third parameter:
3150 uri_for('/path', { foo => 'qux%3Dquo' }, 1);
3152 # would return http://localhost:5000/path?foo=qux%3Dquo
3153 captures
3155 Returns a reference to a copy of "%+", if there are named captures in
3156 the route's regular expression.
3157 Named captures are a feature of Perl 5.10, and are not supported in
3159 earlier versions:
3160 get qr{
3162 / (?<object> user | ticket | comment )
3163 / (?<action> delete | find )
3164 / (?<id> \d+ )
3165 /?$
3166 }x
3167 , sub {
3168 my $value_for = captures;
3169 "i don't want to $$value_for{action} the $$value_for{object} $$value_for{id} !"
3170 };
3171 var
3173 Provides an accessor for variables shared between hooks and route
3174 handlers. Given a key/value pair, it sets a variable:
3175 hook before => sub {
3177 var foo => 42;
3178 };
3179 Later, route handlers and other hooks will be able to read that
3181 variable:
3182 get '/path' => sub {
3184 my $foo = var 'foo';
3185 ...
3186 };
3187 vars
3189 Returns the hashref of all shared variables set during the hook/route
3190 chain with the "var" keyword:
3191 get '/path' => sub {
3193 if (vars->{foo} eq 42) {
3194 ...
3195 }
3196 };
3197 warning
3199 Logs a warning message through the current logger engine:
3200 warning "This is a warning";
3202 See Dancer2::Core::Role::Logger for details on how to configure where
3204 log messages go.
3205
3207 Dancer Core Developers
3208
3210 This software is copyright (c) 2021 by Alexis Sukrieh.
3211 This is free software; you can redistribute it and/or modify it under
3213 the same terms as the Perl 5 programming language system itself.
3214perl v5.32.1 2021-01-31 Dancer2::Manual(3)