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', -signatures;
12 # Route
14 sub startup ($self) {
15 $self->routes->get('/hello')->to('foo#hello');
16 }
17 # Controller
19 package MyApp::Controller::Foo;
20 use Mojo::Base 'Mojolicious::Controller', -signatures;
21 # Action
23 sub hello ($self) {
24 $self->render(text => 'Hello World!');
25 }
26
28 An amazing real-time web framework built on top of the powerful Mojo
29 web development toolkit. With support for RESTful routes, plugins,
30 commands, Perl-ish templates, content negotiation, session management,
31 form validation, testing framework, static file server, "CGI"/"PSGI"
32 detection, first class Unicode support and much more for you to
33 discover.
34 Take a look at our excellent documentation in Mojolicious::Guides!
36
38 Mojolicious will emit the following hooks in the listed order.
39 before_command
41 Emitted right before the application runs a command through the command
42 line interface.
43 $app->hook(before_command => sub ($command, $args) {...});
45 Useful for reconfiguring the application before running a command or to
47 modify the behavior of a command. (Passed the command object and the
48 command arguments)
49 before_server_start
51 Emitted right before the application server is started, for web servers
52 that support it, which includes all the built-in ones (except for
53 Mojo::Server::CGI).
54 $app->hook(before_server_start => sub ($server, $app) {...});
56 Useful for reconfiguring application servers dynamically or collecting
58 server diagnostics information. (Passed the server and application
59 objects)
60 after_build_tx
62 Emitted right after the transaction is built and before the HTTP
63 request gets parsed.
64 $app->hook(after_build_tx => sub ($tx, $app) {...});
66 This is a very powerful hook and should not be used lightly, it makes
68 some rather advanced features such as upload progress bars possible.
69 Note that this hook will not work for embedded applications, because
70 only the host application gets to build transactions. (Passed the
71 transaction and application objects)
72 around_dispatch
74 Emitted right after a new request has been received and wraps around
75 the whole dispatch process, so you have to manually forward to the next
76 hook if you want to continue the chain. Default exception handling with
77 "reply->exception" in Mojolicious::Plugin::DefaultHelpers is the first
78 hook in the chain and a call to "dispatch" the last, yours will be in
79 between.
80 $app->hook(around_dispatch => sub ($next, $c) {
82 ...
83 $next->();
84 ...
85 });
86 This is a very powerful hook and should not be used lightly, it allows
88 you to, for example, customize application-wide exception handling,
89 consider it the sledgehammer in your toolbox. (Passed a callback
90 leading to the next hook and the default controller object)
91 before_dispatch
93 Emitted right before the static file server and router start their
94 work.
95 $app->hook(before_dispatch => sub ($c) {...});
97 Very useful for rewriting incoming requests and other preprocessing
99 tasks. (Passed the default controller object)
100 after_static
102 Emitted after a static file response has been generated by the static
103 file server.
104 $app->hook(after_static => sub ($c) {...});
106 Mostly used for post-processing static file responses. (Passed the
108 default controller object)
109 before_routes
111 Emitted after the static file server determined if a static file should
112 be served and before the router starts its work.
113 $app->hook(before_routes => sub ($c) {...});
115 Mostly used for custom dispatchers and collecting metrics. (Passed the
117 default controller object)
118 around_action
120 Emitted right before an action gets executed and wraps around it, so
121 you have to manually forward to the next hook if you want to continue
122 the chain. Default action dispatching is the last hook in the chain,
123 yours will run before it.
124 $app->hook(around_action => sub ($next, $c, $action, $last) {
126 ...
127 return $next->();
128 });
129 This is a very powerful hook and should not be used lightly, it allows
131 you for example to pass additional arguments to actions or handle
132 return values differently. Note that this hook can trigger more than
133 once for the same request if there are nested routes. (Passed a
134 callback leading to the next hook, the current controller object, the
135 action callback and a flag indicating if this action is an endpoint)
136 before_render
138 Emitted before content is generated by the renderer. Note that this
139 hook can trigger out of order due to its dynamic nature, and with
140 embedded applications will only work for the application that is
141 rendering.
142 $app->hook(before_render => sub ($c, $args) {...});
144 Mostly used for pre-processing arguments passed to the renderer.
146 (Passed the current controller object and the render arguments)
147 after_render
149 Emitted after content has been generated by the renderer that will be
150 assigned to the response. Note that this hook can trigger out of order
151 due to its dynamic nature, and with embedded applications will only
152 work for the application that is rendering.
153 $app->hook(after_render => sub ($c, $output, $format) {...});
155 Mostly used for post-processing dynamically generated content. (Passed
157 the current controller object, a reference to the content and the
158 format)
159 after_dispatch
161 Emitted in reverse order after a response has been generated. Note that
162 this 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 generating the response.
165 $app->hook(after_dispatch => sub ($c) {...});
167 Useful for rewriting outgoing responses and other post-processing
169 tasks. (Passed the current controller object)
170
172 Mojolicious implements the following attributes.
173 commands
175 my $commands = $app->commands;
176 $app = $app->commands(Mojolicious::Commands->new);
177 Command line interface for your application, defaults to a
179 Mojolicious::Commands object.
180 # Add another namespace to load commands from
182 push @{$app->commands->namespaces}, 'MyApp::Command';
183 controller_class
185 my $class = $app->controller_class;
186 $app = $app->controller_class('Mojolicious::Controller');
187 Class to be used for the default controller, defaults to
189 Mojolicious::Controller. Note that this class needs to have already
190 been loaded before the first request arrives.
191 home
193 my $home = $app->home;
194 $app = $app->home(Mojo::Home->new);
195 The home directory of your application, defaults to a Mojo::Home object
197 which stringifies to the actual path.
198 # Portably generate path relative to home directory
200 my $path = $app->home->child('data', 'important.txt');
201 log
203 my $log = $app->log;
204 $app = $app->log(Mojo::Log->new);
205 The logging layer of your application, defaults to a Mojo::Log object.
207 The level will default to either the "MOJO_LOG_LEVEL" environment
208 variable, "debug" if the "mode" is "development", or "info" otherwise.
209 All messages will be written to "STDERR" by default.
210 # Log debug message
212 $app->log->debug('It works');
213 max_request_size
215 my $max = $app->max_request_size;
216 $app = $app->max_request_size(16777216);
217 Maximum request size in bytes, defaults to the value of
219 "max_message_size" in Mojo::Message. Setting the value to 0 will allow
220 requests of indefinite size. Note that increasing this value can also
221 drastically increase memory usage, should you for example attempt to
222 parse an excessively large request body with the methods "dom" in
223 Mojo::Message or "json" in Mojo::Message.
224 mode
226 my $mode = $app->mode;
227 $app = $app->mode('production');
228 The operating mode for your application, defaults to a value from the
230 "MOJO_MODE" and "PLACK_ENV" environment variables or "development".
231 moniker
233 my $moniker = $app->moniker;
234 $app = $app->moniker('foo_bar');
235 Moniker of this application, often used as default filename for
237 configuration files and the like, defaults to decamelizing the
238 application class with "decamelize" in Mojo::Util.
239 plugins
241 my $plugins = $app->plugins;
242 $app = $app->plugins(Mojolicious::Plugins->new);
243 The plugin manager, defaults to a Mojolicious::Plugins object. See the
245 "plugin" method below if you want to load a plugin.
246 # Add another namespace to load plugins from
248 push @{$app->plugins->namespaces}, 'MyApp::Plugin';
249 preload_namespaces
251 my $namespaces = $app->preload_namespaces;
252 $app = $app->preload_namespaces(['MyApp:Controller']);
253 Namespaces to preload classes from during application startup.
255 renderer
257 my $renderer = $app->renderer;
258 $app = $app->renderer(Mojolicious::Renderer->new);
259 Used to render content, defaults to a Mojolicious::Renderer object. For
261 more information about how to generate content see
262 Mojolicious::Guides::Rendering.
263 # Enable compression
265 $app->renderer->compress(1);
266 # Add another "templates" directory
268 push @{$app->renderer->paths}, '/home/sri/templates';
269 # Add another "templates" directory with higher precedence
271 unshift @{$app->renderer->paths}, '/home/sri/themes/blue/templates';
272 # Add another class with templates in DATA section
274 push @{$app->renderer->classes}, 'Mojolicious::Plugin::Fun';
275 routes
277 my $routes = $app->routes;
278 $app = $app->routes(Mojolicious::Routes->new);
279 The router, defaults to a Mojolicious::Routes object. You use this in
281 your startup method to define the url endpoints for your application.
282 # Add routes
284 my $r = $app->routes;
285 $r->get('/foo/bar')->to('test#foo', title => 'Hello Mojo!');
286 $r->post('/baz')->to('test#baz');
287 # Add another namespace to load controllers from
289 push @{$app->routes->namespaces}, 'MyApp::MyController';
290 secrets
292 my $secrets = $app->secrets;
293 $app = $app->secrets([$bytes]);
294 Secret passphrases used for signed cookies and the like, defaults to
296 the "moniker" of this application, which is not very secure, so you
297 should change it!!! As long as you are using the insecure default there
298 will be debug messages in the log file reminding you to change your
299 passphrase. Only the first passphrase is used to create new signatures,
300 but all of them for verification. So you can increase security without
301 invalidating all your existing signed cookies by rotating passphrases,
302 just add new ones to the front and remove old ones from the back.
303 # Rotate passphrases
305 $app->secrets(['new_passw0rd', 'old_passw0rd', 'very_old_passw0rd']);
306 sessions
308 my $sessions = $app->sessions;
309 $app = $app->sessions(Mojolicious::Sessions->new);
310 Signed cookie based session manager, defaults to a
312 Mojolicious::Sessions object. You can usually leave this alone, see
313 "session" in Mojolicious::Controller for more information about working
314 with session data.
315 # Change name of cookie used for all sessions
317 $app->sessions->cookie_name('mysession');
318 # Disable SameSite feature
320 $app->sessions->samesite(undef);
321 static
323 my $static = $app->static;
324 $app = $app->static(Mojolicious::Static->new);
325 For serving static files from your "public" directories, defaults to a
327 Mojolicious::Static object.
328 # Add another "public" directory
330 push @{$app->static->paths}, '/home/sri/public';
331 # Add another "public" directory with higher precedence
333 unshift @{$app->static->paths}, '/home/sri/themes/blue/public';
334 # Add another class with static files in DATA section
336 push @{$app->static->classes}, 'Mojolicious::Plugin::Fun';
337 # Remove built-in favicon
339 delete $app->static->extra->{'favicon.ico'};
340 types
342 my $types = $app->types;
343 $app = $app->types(Mojolicious::Types->new);
344 Responsible for connecting file extensions with MIME types, defaults to
346 a Mojolicious::Types object.
347 # Add custom MIME type
349 $app->types->type(twt => 'text/tweet');
350 ua
352 my $ua = $app->ua;
353 $app = $app->ua(Mojo::UserAgent->new);
354 A full featured HTTP user agent for use in your applications, defaults
356 to a Mojo::UserAgent object.
357 # Perform blocking request
359 say $app->ua->get('example.com')->result->body;
360 validator
362 my $validator = $app->validator;
363 $app = $app->validator(Mojolicious::Validator->new);
364 Validate values, defaults to a Mojolicious::Validator object.
366 # Add validation check
368 $app->validator->add_check(foo => sub ($v, $name, $value) {
369 return $value ne 'foo';
370 });
371 # Add validation filter
373 $app->validator->add_filter(quotemeta => sub ($v, $name, $value) {
374 return quotemeta $value;
375 });
376
378 Mojolicious inherits all methods from Mojo::Base and implements the
379 following new ones.
380 build_controller
382 my $c = $app->build_controller;
383 my $c = $app->build_controller(Mojo::Transaction::HTTP->new);
384 my $c = $app->build_controller(Mojolicious::Controller->new);
385 Build default controller object with "controller_class".
387 # Render template from application
389 my $foo = $app->build_controller->render_to_string(template => 'foo');
390 build_tx
392 my $tx = $app->build_tx;
393 Build Mojo::Transaction::HTTP object and emit "after_build_tx" hook.
395 config
397 my $hash = $app->config;
398 my $foo = $app->config('foo');
399 $app = $app->config({foo => 'bar', baz => 23});
400 $app = $app->config(foo => 'bar', baz => 23);
401 Application configuration.
403 # Remove value
405 my $foo = delete $app->config->{foo};
406 # Assign multiple values at once
408 $app->config(foo => 'test', bar => 23);
409 defaults
411 my $hash = $app->defaults;
412 my $foo = $app->defaults('foo');
413 $app = $app->defaults({foo => 'bar', baz => 23});
414 $app = $app->defaults(foo => 'bar', baz => 23);
415 Default values for "stash" in Mojolicious::Controller, assigned for
417 every new request.
418 # Remove value
420 my $foo = delete $app->defaults->{foo};
421 # Assign multiple values at once
423 $app->defaults(foo => 'test', bar => 23);
424 dispatch
426 $app->dispatch(Mojolicious::Controller->new);
427 The heart of every Mojolicious application, calls the "static" and
429 "routes" dispatchers for every request and passes them a
430 Mojolicious::Controller object.
431 handler
433 $app->handler(Mojo::Transaction::HTTP->new);
434 $app->handler(Mojolicious::Controller->new);
435 Sets up the default controller and emits the "around_dispatch" hook for
437 every request.
438 helper
440 $app->helper(foo => sub {...});
441 Add or replace a helper that will be available as a method of the
443 controller object and the application object, as well as a function in
444 "ep" templates. For a full list of helpers that are available by
445 default see Mojolicious::Plugin::DefaultHelpers and
446 Mojolicious::Plugin::TagHelpers.
447 # Helper
449 $app->helper(cache => sub { state $cache = {} });
450 # Application
452 $app->cache->{foo} = 'bar';
453 my $result = $app->cache->{foo};
454 # Controller
456 $c->cache->{foo} = 'bar';
457 my $result = $c->cache->{foo};
458 # Template
460 % cache->{foo} = 'bar';
461 %= cache->{foo}
462 hook
464 $app->hook(after_dispatch => sub {...});
465 Extend Mojolicious with hooks, which allow code to be shared with all
467 requests indiscriminately, for a full list of available hooks see
468 "HOOKS".
469 # Dispatchers will not run if there's already a response code defined
471 $app->hook(before_dispatch => sub ($c) {
472 $c->render(text => 'Skipped static file server and router!')
473 if $c->req->url->path->to_route =~ /do_not_dispatch/;
474 });
475 new
477 my $app = Mojolicious->new;
478 my $app = Mojolicious->new(moniker => 'foo_bar');
479 my $app = Mojolicious->new({moniker => 'foo_bar'});
480 Construct a new Mojolicious application and call "startup". Will
482 automatically detect your home directory. Also sets up the renderer,
483 static file server, a default set of plugins and an "around_dispatch"
484 hook with the default exception handling.
485 plugin
487 $app->plugin('some_thing');
488 $app->plugin('some_thing', foo => 23);
489 $app->plugin('some_thing', {foo => 23});
490 $app->plugin('SomeThing');
491 $app->plugin('SomeThing', foo => 23);
492 $app->plugin('SomeThing', {foo => 23});
493 $app->plugin('MyApp::Plugin::SomeThing');
494 $app->plugin('MyApp::Plugin::SomeThing', foo => 23);
495 $app->plugin('MyApp::Plugin::SomeThing', {foo => 23});
496 Load a plugin, for a full list of example plugins included in the
498 Mojolicious distribution see "PLUGINS" in Mojolicious::Plugins.
499 server
501 $app->server(Mojo::Server->new);
502 Emits the "before_server_start" hook.
504 start
506 $app->start;
507 $app->start(@ARGV);
508 Start the command line interface for your application. For a full list
510 of commands that are available by default see "COMMANDS" in
511 Mojolicious::Commands. Note that the options "-h"/"--help", "--home"
512 and "-m"/"--mode", which are shared by all commands, will be parsed
513 from @ARGV during compile time.
514 # Always start daemon
516 $app->start('daemon', '-l', 'http://*:8080');
517 startup
519 $app->startup;
520 This is your main hook into the application, it will be called at
522 application startup. Meant to be overloaded in a subclass.
523 sub startup ($self) {...}
525 warmup
527 $app->warmup;
528 Preload classes from "preload_namespaces" for future use.
530
532 In addition to the "ATTRIBUTES" and "METHODS" above you can also call
533 helpers on Mojolicious objects. This includes all helpers from
534 Mojolicious::Plugin::DefaultHelpers and
535 Mojolicious::Plugin::TagHelpers. Note that application helpers are
536 always called with a new default controller object, so they can't
537 depend on or change controller state, which includes request, response
538 and stash.
539 # Call helper
541 say $app->dumper({foo => 'bar'});
542 # Longer version
544 say $app->build_controller->helpers->dumper({foo => 'bar'});
545
547 The Mojolicious distribution includes a few files with different
548 licenses that have been bundled for internal use.
549 Mojolicious Artwork
551 Copyright (C) 2010-2021, Sebastian Riedel.
552 Licensed under the CC-SA License, Version 4.0
554 <http://creativecommons.org/licenses/by-sa/4.0>.
555 jQuery
557 Copyright (C) jQuery Foundation.
558 Licensed under the MIT License,
560 <http://creativecommons.org/licenses/MIT>.
561 highlight.js
563 Copyright (C) 2006, Ivan Sagalaev.
564 Licensed under the BSD License,
566 <https://github.com/highlightjs/highlight.js/blob/master/LICENSE>.
567 Bootstrap
569 Copyright 2011-2020 The Bootstrap Authors.
570 Copyright 2011-2020 Twitter, Inc.
571 Licensed under the MIT License,
573 <http://creativecommons.org/licenses/MIT>.
574 Font Awesome
576 Licensed under the CC-BY License, Version 4.0
577 <https://creativecommons.org/licenses/by/4.0/> and SIL OFL, Version 1.1
578 <https://opensource.org/licenses/OFL-1.1>.
579
581 Every major release of Mojolicious has a code name, these are the ones
582 that have been used in the past.
583 8.0, "Supervillain" (U+1F9B9)
585 7.0, "Doughnut" (U+1F369)
587 6.0, "Clinking Beer Mugs" (U+1F37B)
589 5.0, "Tiger Face" (U+1F42F)
591 4.0, "Top Hat" (U+1F3A9)
593 3.0, "Rainbow" (U+1F308)
595 2.0, "Leaf Fluttering In Wind" (U+1F343)
597 1.0, "Snowflake" (U+2744)
599
601 • Stix <https://stix.no> sponsored the creation of the Mojolicious logo
602 (designed by Nicolai Graesdal) and transferred its copyright to
603 Sebastian Riedel.
604 • Some of the work on this distribution has been sponsored by The Perl
606 Foundation <https://www.perlfoundation.org>.
607
609 Mojolicious is an open source project that relies on the tireless
610 support of its contributors.
611 Project Founder
613 Sebastian Riedel, "kraih@mojolicious.org"
614 Core Developers
616 Current voting members of the core team in alphabetical order:
617 Christopher Rasch-Olsen Raa, "christopher@mojolicious.org"
619 Dan Book, "grinnz@mojolicious.org"
621 Jan Henning Thorsen, "batman@mojolicious.org"
623 Joel Berger, "jberger@mojolicious.org"
625 Marcus Ramberg, "marcus@mojolicious.org"
627 The following members of the core team are currently on hiatus:
629 Abhijit Menon-Sen, "ams@cpan.org"
631 CandyAngel, "candyangel@mojolicious.org"
633 Glen Hinkle, "tempire@cpan.org"
635 Contributors
637 In alphabetical order:
638 Adam Kennedy
640 Adriano Ferreira
642 Al Newkirk
644 Alex Efros
646 Alex Salimon
648 Alexander Karelas
650 Alexey Likhatskiy
652 Anatoly Sharifulin
654 Andre Parker
656 Andre Vieth
658 Andreas Guldstrand
660 Andreas Jaekel
662 Andreas Koenig
664 Andrew Fresh
666 Andrew Nugged
668 Andrey Khozov
670 Andrey Kuzmin
672 Andy Grundman
674 Aristotle Pagaltzis
676 Ashley Dev
678 Ask Bjoern Hansen
680 Audrey Tang
682 Ben Tyler
684 Ben van Staveren
686 Benjamin Erhart
688 Bernhard Graf
690 Breno G. de Oliveira
692 Brian Duggan
694 Brian Medley
696 Burak Gursoy
698 Ch Lamprecht
700 Charlie Brady
702 Chas. J. Owens IV
704 Chase Whitener
706 Chris Scheller
708 Christian Hansen
710 chromatic
712 Curt Tilmes
714 Daniel Kimsey
716 Daniel Mantovani
718 Danijel Tasov
720 Dagfinn Ilmari Manns�ker
722 Danny Thomas
724 David Davis
726 David Webb
728 Diego Kuperman
730 Dmitriy Shalashov
732 Dmitry Konstantinov
734 Dominik Jarmulowicz
736 Dominique Dumont
738 Dotan Dimet
740 Douglas Christopher Wilson
742 Elmar S. Heeb
744 Ettore Di Giacinto
746 Eugen Konkov
748 Eugene Toropov
750 Flavio Poletti
752 Gisle Aas
754 Graham Barr
756 Graham Knop
758 Henry Tang
760 Hideki Yamamura
762 Hiroki Toyokawa
764 Ian Goodacre
766 Ilya Chesnokov
768 Ilya Rassadin
770 James Duncan
772 Jan Jona Javorsek
774 Jan Schmidt
776 Jaroslav Muhin
778 Jesse Vincent
780 Johannes Plunien
782 John Kingsley
784 Jonathan Yu
786 Josh Leder
788 Kamen Naydenov
790 Karen Etheridge
792 Kazuhiro Shibuya
794 Kevin Old
796 Kitamura Akatsuki
798 Klaus S. Madsen
800 Knut Arne Bjorndal
802 Lars Balker Rasmussen
804 Lee Johnson
806 Leon Brocard
808 Magnus Holm
810 Maik Fischer
812 Mark Fowler
814 Mark Grimes
816 Mark Stosberg
818 Martin McGrath
820 Marty Tennison
822 Matt S Trout
824 Matthew Lineen
826 Maksym Komar
828 Maxim Vuets
830 Michael Gregorowicz
832 Michael Harris
834 Michael Jemmeson
836 Mike Magowan
838 Mirko Westermeier
840 Mons Anderson
842 Moritz Lenz
844 Neil Watkiss
846 Nic Sandfield
848 Nils Diewald
850 Oleg Zhelo
852 Olivier Mengue
854 Pascal Gaudette
856 Paul Evans
858 Paul Robins
860 Paul Tomlin
862 Pavel Shaydo
864 Pedro Melo
866 Peter Edwards
868 Pierre-Yves Ritschard
870 Piotr Roszatycki
872 Quentin Carbonneaux
874 Rafal Pocztarski
876 Randal Schwartz
878 Richard Elberger
880 Rick Delaney
882 Robert Hicks
884 Robert Rothenberg
886 Robin Lee
888 Roland Lammel
890 Roy Storey
892 Ryan Jendoubi
894 Salvador Fandino
896 Santiago Zarate
898 Sascha Kiefer
900 Scott Wiersdorf
902 Sebastian Paaske Torholm
904 Sergey Zasenko
906 Simon Bertrang
908 Simone Tampieri
910 Shoichi Kaji
912 Shu Cho
914 Skye Shaw
916 Stanis Trendelenburg
918 Stefan Adams
920 Steffen Ullrich
922 Stephan Kulow
924 Stephane Este-Gracias
926 Stevan Little
928 Steve Atkins
930 Tatsuhiko Miyagawa
932 Terrence Brannon
934 Tianon Gravi
936 Tomas Znamenacek
938 Tudor Constantin
940 Ulrich Habel
942 Ulrich Kautz
944 Uwe Voelker
946 Veesh Goldman
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-2021, 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.32.1 2021-02-07 Mojolicious(3)