1Mojolicious(3) User Contributed Perl Documentation Mojolicious(3)
2
6 Mojolicious - Real-time web framework
7
9 # Application
10 package MyApp;
11 use Mojo::Base 'Mojolicious';
12 # Route
14 sub startup {
15 my $self = shift;
16 $self->routes->get('/hello')->to('foo#hello');
17 }
18 # Controller
20 package MyApp::Controller::Foo;
21 use Mojo::Base 'Mojolicious::Controller';
22 # Action
24 sub hello {
25 my $self = shift;
26 $self->render(text => 'Hello World!');
27 }
28
30 An amazing real-time web framework built on top of the powerful Mojo
31 web development toolkit. With support for RESTful routes, plugins,
32 commands, Perl-ish templates, content negotiation, session management,
33 form validation, testing framework, static file server, "CGI"/"PSGI"
34 detection, first class Unicode support and much more for you to
35 discover.
36 Take a look at our excellent documentation in Mojolicious::Guides!
38
40 Mojolicious will emit the following hooks in the listed order.
41 before_command
43 Emitted right before the application runs a command through the command
44 line interface. Note that this hook is EXPERIMENTAL and might change
45 without warning!
46 $app->hook(before_command => sub {
48 my ($command, $args) = @_;
49 ...
50 });
51 Useful for reconfiguring the application before running a command or to
53 modify the behavior of a command. (Passed the command object and the
54 command arguments)
55 before_server_start
57 Emitted right before the application server is started, for web servers
58 that support it, which includes all the built-in ones (except for
59 Mojo::Server::CGI).
60 $app->hook(before_server_start => sub {
62 my ($server, $app) = @_;
63 ...
64 });
65 Useful for reconfiguring application servers dynamically or collecting
67 server diagnostics information. (Passed the server and application
68 objects)
69 after_build_tx
71 Emitted right after the transaction is built and before the HTTP
72 request gets parsed.
73 $app->hook(after_build_tx => sub {
75 my ($tx, $app) = @_;
76 ...
77 });
78 This is a very powerful hook and should not be used lightly, it makes
80 some rather advanced features such as upload progress bars possible.
81 Note that this hook will not work for embedded applications, because
82 only the host application gets to build transactions. (Passed the
83 transaction and application objects)
84 around_dispatch
86 Emitted right after a new request has been received and wraps around
87 the whole dispatch process, so you have to manually forward to the next
88 hook if you want to continue the chain. Default exception handling with
89 "reply->exception" in Mojolicious::Plugin::DefaultHelpers is the first
90 hook in the chain and a call to "dispatch" the last, yours will be in
91 between.
92 $app->hook(around_dispatch => sub {
94 my ($next, $c) = @_;
95 ...
96 $next->();
97 ...
98 });
99 This is a very powerful hook and should not be used lightly, it allows
101 you to, for example, customize application-wide exception handling,
102 consider it the sledgehammer in your toolbox. (Passed a callback
103 leading to the next hook and the default controller object)
104 before_dispatch
106 Emitted right before the static file server and router start their
107 work.
108 $app->hook(before_dispatch => sub {
110 my $c = shift;
111 ...
112 });
113 Very useful for rewriting incoming requests and other preprocessing
115 tasks. (Passed the default controller object)
116 after_static
118 Emitted after a static file response has been generated by the static
119 file server.
120 $app->hook(after_static => sub {
122 my $c = shift;
123 ...
124 });
125 Mostly used for post-processing static file responses. (Passed the
127 default controller object)
128 before_routes
130 Emitted after the static file server determined if a static file should
131 be served and before the router starts its work.
132 $app->hook(before_routes => sub {
134 my $c = shift;
135 ...
136 });
137 Mostly used for custom dispatchers and collecting metrics. (Passed the
139 default controller object)
140 around_action
142 Emitted right before an action gets executed and wraps around it, so
143 you have to manually forward to the next hook if you want to continue
144 the chain. Default action dispatching is the last hook in the chain,
145 yours will run before it.
146 $app->hook(around_action => sub {
148 my ($next, $c, $action, $last) = @_;
149 ...
150 return $next->();
151 });
152 This is a very powerful hook and should not be used lightly, it allows
154 you for example to pass additional arguments to actions or handle
155 return values differently. Note that this hook can trigger more than
156 once for the same request if there are nested routes. (Passed a
157 callback leading to the next hook, the current controller object, the
158 action callback and a flag indicating if this action is an endpoint)
159 before_render
161 Emitted before content is generated by the renderer. Note that this
162 hook can trigger out of order due to its dynamic nature, and with
163 embedded applications will only work for the application that is
164 rendering.
165 $app->hook(before_render => sub {
167 my ($c, $args) = @_;
168 ...
169 });
170 Mostly used for pre-processing arguments passed to the renderer.
172 (Passed the current controller object and the render arguments)
173 after_render
175 Emitted after content has been generated by the renderer that will be
176 assigned to the response. Note that this hook can trigger out of order
177 due to its dynamic nature, and with embedded applications will only
178 work for the application that is rendering.
179 $app->hook(after_render => sub {
181 my ($c, $output, $format) = @_;
182 ...
183 });
184 Mostly used for post-processing dynamically generated content. (Passed
186 the current controller object, a reference to the content and the
187 format)
188 after_dispatch
190 Emitted in reverse order after a response has been generated. Note that
191 this hook can trigger out of order due to its dynamic nature, and with
192 embedded applications will only work for the application that is
193 generating the response.
194 $app->hook(after_dispatch => sub {
196 my $c = shift;
197 ...
198 });
199 Useful for rewriting outgoing responses and other post-processing
201 tasks. (Passed the current controller object)
202
204 Mojolicious implements the following attributes.
205 commands
207 my $commands = $app->commands;
208 $app = $app->commands(Mojolicious::Commands->new);
209 Command line interface for your application, defaults to a
211 Mojolicious::Commands object.
212 # Add another namespace to load commands from
214 push @{$app->commands->namespaces}, 'MyApp::Command';
215 controller_class
217 my $class = $app->controller_class;
218 $app = $app->controller_class('Mojolicious::Controller');
219 Class to be used for the default controller, defaults to
221 Mojolicious::Controller. Note that this class needs to have already
222 been loaded before the first request arrives.
223 home
225 my $home = $app->home;
226 $app = $app->home(Mojo::Home->new);
227 The home directory of your application, defaults to a Mojo::Home object
229 which stringifies to the actual path.
230 # Portably generate path relative to home directory
232 my $path = $app->home->child('data', 'important.txt');
233 log
235 my $log = $app->log;
236 $app = $app->log(Mojo::Log->new);
237 The logging layer of your application, defaults to a Mojo::Log object.
239 The level will default to either the "MOJO_LOG_LEVEL" environment
240 variable, "debug" if the "mode" is "development", or "info" otherwise.
241 All messages will be written to "STDERR", or a "log/$mode.log" file if
242 a "log" directory exists.
243 # Log debug message
245 $app->log->debug('It works');
246 max_request_size
248 my $max = $app->max_request_size;
249 $app = $app->max_request_size(16777216);
250 Maximum request size in bytes, defaults to the value of
252 "max_message_size" in Mojo::Message. Setting the value to 0 will allow
253 requests of indefinite size. Note that increasing this value can also
254 drastically increase memory usage, should you for example attempt to
255 parse an excessively large request body with the methods "dom" in
256 Mojo::Message or "json" in Mojo::Message.
257 mode
259 my $mode = $app->mode;
260 $app = $app->mode('production');
261 The operating mode for your application, defaults to a value from the
263 "MOJO_MODE" and "PLACK_ENV" environment variables or "development".
264 moniker
266 my $moniker = $app->moniker;
267 $app = $app->moniker('foo_bar');
268 Moniker of this application, often used as default filename for
270 configuration files and the like, defaults to decamelizing the
271 application class with "decamelize" in Mojo::Util.
272 plugins
274 my $plugins = $app->plugins;
275 $app = $app->plugins(Mojolicious::Plugins->new);
276 The plugin manager, defaults to a Mojolicious::Plugins object. See the
278 "plugin" method below if you want to load a plugin.
279 # Add another namespace to load plugins from
281 push @{$app->plugins->namespaces}, 'MyApp::Plugin';
282 renderer
284 my $renderer = $app->renderer;
285 $app = $app->renderer(Mojolicious::Renderer->new);
286 Used to render content, defaults to a Mojolicious::Renderer object. For
288 more information about how to generate content see
289 Mojolicious::Guides::Rendering.
290 # Enable compression
292 $app->renderer->compress(1);
293 # Add another "templates" directory
295 push @{$app->renderer->paths}, '/home/sri/templates';
296 # Add another "templates" directory with higher precedence
298 unshift @{$app->renderer->paths}, '/home/sri/themes/blue/templates';
299 # Add another class with templates in DATA section
301 push @{$app->renderer->classes}, 'Mojolicious::Plugin::Fun';
302 routes
304 my $routes = $app->routes;
305 $app = $app->routes(Mojolicious::Routes->new);
306 The router, defaults to a Mojolicious::Routes object. You use this in
308 your startup method to define the url endpoints for your application.
309 # Add routes
311 my $r = $app->routes;
312 $r->get('/foo/bar')->to('test#foo', title => 'Hello Mojo!');
313 $r->post('/baz')->to('test#baz');
314 # Add another namespace to load controllers from
316 push @{$app->routes->namespaces}, 'MyApp::MyController';
317 secrets
319 my $secrets = $app->secrets;
320 $app = $app->secrets([$bytes]);
321 Secret passphrases used for signed cookies and the like, defaults to
323 the "moniker" of this application, which is not very secure, so you
324 should change it!!! As long as you are using the insecure default there
325 will be debug messages in the log file reminding you to change your
326 passphrase. Only the first passphrase is used to create new signatures,
327 but all of them for verification. So you can increase security without
328 invalidating all your existing signed cookies by rotating passphrases,
329 just add new ones to the front and remove old ones from the back.
330 # Rotate passphrases
332 $app->secrets(['new_passw0rd', 'old_passw0rd', 'very_old_passw0rd']);
333 sessions
335 my $sessions = $app->sessions;
336 $app = $app->sessions(Mojolicious::Sessions->new);
337 Signed cookie based session manager, defaults to a
339 Mojolicious::Sessions object. You can usually leave this alone, see
340 "session" in Mojolicious::Controller for more information about working
341 with session data.
342 # Change name of cookie used for all sessions
344 $app->sessions->cookie_name('mysession');
345 # Disable SameSite feature
347 $app->sessions->samesite(undef);
348 static
350 my $static = $app->static;
351 $app = $app->static(Mojolicious::Static->new);
352 For serving static files from your "public" directories, defaults to a
354 Mojolicious::Static object.
355 # Add another "public" directory
357 push @{$app->static->paths}, '/home/sri/public';
358 # Add another "public" directory with higher precedence
360 unshift @{$app->static->paths}, '/home/sri/themes/blue/public';
361 # Add another class with static files in DATA section
363 push @{$app->static->classes}, 'Mojolicious::Plugin::Fun';
364 # Remove built-in favicon
366 delete $app->static->extra->{'favicon.ico'};
367 types
369 my $types = $app->types;
370 $app = $app->types(Mojolicious::Types->new);
371 Responsible for connecting file extensions with MIME types, defaults to
373 a Mojolicious::Types object.
374 # Add custom MIME type
376 $app->types->type(twt => 'text/tweet');
377 ua
379 my $ua = $app->ua;
380 $app = $app->ua(Mojo::UserAgent->new);
381 A full featured HTTP user agent for use in your applications, defaults
383 to a Mojo::UserAgent object.
384 # Perform blocking request
386 say $app->ua->get('example.com')->result->body;
387 validator
389 my $validator = $app->validator;
390 $app = $app->validator(Mojolicious::Validator->new);
391 Validate values, defaults to a Mojolicious::Validator object.
393 # Add validation check
395 $app->validator->add_check(foo => sub {
396 my ($v, $name, $value) = @_;
397 return $value ne 'foo';
398 });
399 # Add validation filter
401 $app->validator->add_filter(quotemeta => sub {
402 my ($v, $name, $value) = @_;
403 return quotemeta $value;
404 });
405
407 Mojolicious inherits all methods from Mojo::Base and implements the
408 following new ones.
409 build_controller
411 my $c = $app->build_controller;
412 my $c = $app->build_controller(Mojo::Transaction::HTTP->new);
413 my $c = $app->build_controller(Mojolicious::Controller->new);
414 Build default controller object with "controller_class".
416 # Render template from application
418 my $foo = $app->build_controller->render_to_string(template => 'foo');
419 build_tx
421 my $tx = $app->build_tx;
422 Build Mojo::Transaction::HTTP object and emit "after_build_tx" hook.
424 config
426 my $hash = $app->config;
427 my $foo = $app->config('foo');
428 $app = $app->config({foo => 'bar', baz => 23});
429 $app = $app->config(foo => 'bar', baz => 23);
430 Application configuration.
432 # Remove value
434 my $foo = delete $app->config->{foo};
435 # Assign multiple values at once
437 $app->config(foo => 'test', bar => 23);
438 defaults
440 my $hash = $app->defaults;
441 my $foo = $app->defaults('foo');
442 $app = $app->defaults({foo => 'bar', baz => 23});
443 $app = $app->defaults(foo => 'bar', baz => 23);
444 Default values for "stash" in Mojolicious::Controller, assigned for
446 every new request.
447 # Remove value
449 my $foo = delete $app->defaults->{foo};
450 # Assign multiple values at once
452 $app->defaults(foo => 'test', bar => 23);
453 dispatch
455 $app->dispatch(Mojolicious::Controller->new);
456 The heart of every Mojolicious application, calls the "static" and
458 "routes" dispatchers for every request and passes them a
459 Mojolicious::Controller object.
460 handler
462 $app->handler(Mojo::Transaction::HTTP->new);
463 $app->handler(Mojolicious::Controller->new);
464 Sets up the default controller and emits the "around_dispatch" hook for
466 every request.
467 helper
469 $app->helper(foo => sub {...});
470 Add or replace a helper that will be available as a method of the
472 controller object and the application object, as well as a function in
473 "ep" templates. For a full list of helpers that are available by
474 default see Mojolicious::Plugin::DefaultHelpers and
475 Mojolicious::Plugin::TagHelpers.
476 # Helper
478 $app->helper(cache => sub { state $cache = {} });
479 # Application
481 $app->cache->{foo} = 'bar';
482 my $result = $app->cache->{foo};
483 # Controller
485 $c->cache->{foo} = 'bar';
486 my $result = $c->cache->{foo};
487 # Template
489 % cache->{foo} = 'bar';
490 %= cache->{foo}
491 hook
493 $app->hook(after_dispatch => sub {...});
494 Extend Mojolicious with hooks, which allow code to be shared with all
496 requests indiscriminately, for a full list of available hooks see
497 "HOOKS".
498 # Dispatchers will not run if there's already a response code defined
500 $app->hook(before_dispatch => sub {
501 my $c = shift;
502 $c->render(text => 'Skipped static file server and router!')
503 if $c->req->url->path->to_route =~ /do_not_dispatch/;
504 });
505 new
507 my $app = Mojolicious->new;
508 my $app = Mojolicious->new(moniker => 'foo_bar');
509 my $app = Mojolicious->new({moniker => 'foo_bar'});
510 Construct a new Mojolicious application and call "startup". Will
512 automatically detect your home directory. Also sets up the renderer,
513 static file server, a default set of plugins and an "around_dispatch"
514 hook with the default exception handling.
515 plugin
517 $app->plugin('some_thing');
518 $app->plugin('some_thing', foo => 23);
519 $app->plugin('some_thing', {foo => 23});
520 $app->plugin('SomeThing');
521 $app->plugin('SomeThing', foo => 23);
522 $app->plugin('SomeThing', {foo => 23});
523 $app->plugin('MyApp::Plugin::SomeThing');
524 $app->plugin('MyApp::Plugin::SomeThing', foo => 23);
525 $app->plugin('MyApp::Plugin::SomeThing', {foo => 23});
526 Load a plugin, for a full list of example plugins included in the
528 Mojolicious distribution see "PLUGINS" in Mojolicious::Plugins.
529 server
531 $app->server(Mojo::Server->new);
532 Emits the "before_server_start" hook.
534 start
536 $app->start;
537 $app->start(@ARGV);
538 Start the command line interface for your application. For a full list
540 of commands that are available by default see "COMMANDS" in
541 Mojolicious::Commands. Note that the options "-h"/"--help", "--home"
542 and "-m"/"--mode", which are shared by all commands, will be parsed
543 from @ARGV during compile time.
544 # Always start daemon
546 $app->start('daemon', '-l', 'http://*:8080');
547 startup
549 $app->startup;
550 This is your main hook into the application, it will be called at
552 application startup. Meant to be overloaded in a subclass.
553 sub startup {
555 my $self = shift;
556 ...
557 }
558
560 In addition to the "ATTRIBUTES" and "METHODS" above you can also call
561 helpers on Mojolicious objects. This includes all helpers from
562 Mojolicious::Plugin::DefaultHelpers and
563 Mojolicious::Plugin::TagHelpers. Note that application helpers are
564 always called with a new default controller object, so they can't
565 depend on or change controller state, which includes request, response
566 and stash.
567 # Call helper
569 say $app->dumper({foo => 'bar'});
570 # Longer version
572 say $app->build_controller->helpers->dumper({foo => 'bar'});
573
575 The Mojolicious distribution includes a few files with different
576 licenses that have been bundled for internal use.
577 Mojolicious Artwork
579 Copyright (C) 2010-2020, Sebastian Riedel.
580 Licensed under the CC-SA License, Version 4.0
582 <http://creativecommons.org/licenses/by-sa/4.0>.
583 jQuery
585 Copyright (C) jQuery Foundation.
586 Licensed under the MIT License,
588 <http://creativecommons.org/licenses/MIT>.
589 prettify.js
591 Copyright (C) 2006, 2013 Google Inc..
592 Licensed under the Apache License, Version 2.0
594 <http://www.apache.org/licenses/LICENSE-2.0>.
595
597 Every major release of Mojolicious has a code name, these are the ones
598 that have been used in the past.
599 8.0, "Supervillain" (U+1F9B9)
601 7.0, "Doughnut" (U+1F369)
603 6.0, "Clinking Beer Mugs" (U+1F37B)
605 5.0, "Tiger Face" (U+1F42F)
607 4.0, "Top Hat" (U+1F3A9)
609 3.0, "Rainbow" (U+1F308)
611 2.0, "Leaf Fluttering In Wind" (U+1F343)
613 1.0, "Snowflake" (U+2744)
615
617 · Stix <https://stix.no> sponsored the creation of the Mojolicious logo
618 (designed by Nicolai Graesdal) and transferred its copyright to
619 Sebastian Riedel.
620 · Some of the work on this distribution has been sponsored by The Perl
622 Foundation <http://www.perlfoundation.org>.
623
625 Sebastian Riedel, "kraih@mojolicious.org"
626
628 Current voting members of the core team in alphabetical order:
629 CandyAngel, "candyangel@mojolicious.org"
631 Christopher Rasch-Olsen Raa, "christopher@mojolicious.org"
633 Dan Book, "grinnz@mojolicious.org"
635 Jan Henning Thorsen, "batman@mojolicious.org"
637 Joel Berger, "jberger@mojolicious.org"
639 Marcus Ramberg, "marcus@mojolicious.org"
641 The following members of the core team are currently on hiatus:
643 Abhijit Menon-Sen, "ams@cpan.org"
645 Glen Hinkle, "tempire@cpan.org"
647
649 In alphabetical order:
650 Adam Kennedy
652 Adriano Ferreira
654 Al Newkirk
656 Alex Efros
658 Alex Salimon
660 Alexander Karelas
662 Alexey Likhatskiy
664 Anatoly Sharifulin
666 Andre Parker
668 Andre Vieth
670 Andreas Guldstrand
672 Andreas Jaekel
674 Andreas Koenig
676 Andrew Fresh
678 Andrew Nugged
680 Andrey Khozov
682 Andrey Kuzmin
684 Andy Grundman
686 Aristotle Pagaltzis
688 Ashley Dev
690 Ask Bjoern Hansen
692 Audrey Tang
694 Ben Tyler
696 Ben van Staveren
698 Benjamin Erhart
700 Bernhard Graf
702 Breno G. de Oliveira
704 Brian Duggan
706 Brian Medley
708 Burak Gursoy
710 Ch Lamprecht
712 Charlie Brady
714 Chas. J. Owens IV
716 Chase Whitener
718 Christian Hansen
720 chromatic
722 Curt Tilmes
724 Daniel Kimsey
726 Daniel Mantovani
728 Danijel Tasov
730 Dagfinn Ilmari Mannsåker
732 Danny Thomas
734 David Davis
736 David Webb
738 Diego Kuperman
740 Dmitriy Shalashov
742 Dmitry Konstantinov
744 Dominik Jarmulowicz
746 Dominique Dumont
748 Dotan Dimet
750 Douglas Christopher Wilson
752 Ettore Di Giacinto
754 Eugen Konkov
756 Eugene Toropov
758 Flavio Poletti
760 Gisle Aas
762 Graham Barr
764 Graham Knop
766 Henry Tang
768 Hideki Yamamura
770 Hiroki Toyokawa
772 Ian Goodacre
774 Ilya Chesnokov
776 Ilya Rassadin
778 James Duncan
780 Jan Jona Javorsek
782 Jan Schmidt
784 Jaroslav Muhin
786 Jesse Vincent
788 Johannes Plunien
790 John Kingsley
792 Jonathan Yu
794 Josh Leder
796 Kamen Naydenov
798 Karen Etheridge
800 Kazuhiro Shibuya
802 Kevin Old
804 Kitamura Akatsuki
806 Klaus S. Madsen
808 Knut Arne Bjorndal
810 Lars Balker Rasmussen
812 Lee Johnson
814 Leon Brocard
816 Magnus Holm
818 Maik Fischer
820 Mark Fowler
822 Mark Grimes
824 Mark Stosberg
826 Marty Tennison
828 Matt S Trout
830 Matthew Lineen
832 Maksym Komar
834 Maxim Vuets
836 Michael Gregorowicz
838 Michael Harris
840 Michael Jemmeson
842 Mike Magowan
844 Mirko Westermeier
846 Mons Anderson
848 Moritz Lenz
850 Neil Watkiss
852 Nic Sandfield
854 Nils Diewald
856 Oleg Zhelo
858 Olivier Mengue
860 Pascal Gaudette
862 Paul Evans
864 Paul Robins
866 Paul Tomlin
868 Pavel Shaydo
870 Pedro Melo
872 Peter Edwards
874 Pierre-Yves Ritschard
876 Piotr Roszatycki
878 Quentin Carbonneaux
880 Rafal Pocztarski
882 Randal Schwartz
884 Richard Elberger
886 Rick Delaney
888 Robert Hicks
890 Robin Lee
892 Roland Lammel
894 Roy Storey
896 Ryan Jendoubi
898 Salvador Fandino
900 Santiago Zarate
902 Sascha Kiefer
904 Scott Wiersdorf
906 Sergey Zasenko
908 Simon Bertrang
910 Simone Tampieri
912 Shoichi Kaji
914 Shu Cho
916 Skye Shaw
918 Stanis Trendelenburg
920 Stefan Adams
922 Steffen Ullrich
924 Stephan Kulow
926 Stephane Este-Gracias
928 Stevan Little
930 Steve Atkins
932 Tatsuhiko Miyagawa
934 Terrence Brannon
936 Tianon Gravi
938 Tomas Znamenacek
940 Tudor Constantin
942 Ulrich Habel
944 Ulrich Kautz
946 Uwe Voelker
948 Viacheslav Tykhanovskyi
950 Victor Engmark
952 Viliam Pucik
954 Wes Cravens
956 William Lindley
958 Yaroslav Korshak
960 Yuki Kimoto
962 Zak B. Elep
964 Zoffix Znet
966
968 Copyright (C) 2008-2020, Sebastian Riedel and others.
969 This program is free software, you can redistribute it and/or modify it
971 under the terms of the Artistic License version 2.0.
972
974 <https://github.com/mojolicious/mojo>, Mojolicious::Guides,
975 <https://mojolicious.org>.
976perl v5.30.1 2020-01-30 Mojolicious(3)