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.
53 $app->hook(before_server_start => sub ($server, $app) {...});
55 Useful for reconfiguring application servers dynamically or collecting
57 server diagnostics information. (Passed the server and application
58 objects)
59 after_build_tx
61 Emitted right after the transaction is built and before the HTTP
62 request gets parsed.
63 $app->hook(after_build_tx => sub ($tx, $app) {...});
65 This is a very powerful hook and should not be used lightly, it makes
67 some rather advanced features such as upload progress bars possible.
68 Note that this hook will not work for embedded applications, because
69 only the host application gets to build transactions. (Passed the
70 transaction and application objects)
71 around_dispatch
73 Emitted right after a new request has been received and wraps around
74 the whole dispatch process, so you have to manually forward to the next
75 hook if you want to continue the chain. Default exception handling with
76 "reply->exception" in Mojolicious::Plugin::DefaultHelpers is the first
77 hook in the chain and a call to "dispatch" the last, yours will be in
78 between.
79 $app->hook(around_dispatch => sub ($next, $c) {
81 ...
82 $next->();
83 ...
84 });
85 This is a very powerful hook and should not be used lightly, it allows
87 you to, for example, customize application-wide exception handling,
88 consider it the sledgehammer in your toolbox. (Passed a callback
89 leading to the next hook and the default controller object)
90 before_dispatch
92 Emitted right before the static file server and router start their
93 work.
94 $app->hook(before_dispatch => sub ($c) {...});
96 Very useful for rewriting incoming requests and other preprocessing
98 tasks. (Passed the default controller object)
99 after_static
101 Emitted after a static file response has been generated by the static
102 file server.
103 $app->hook(after_static => sub ($c) {...});
105 Mostly used for post-processing static file responses. (Passed the
107 default controller object)
108 before_routes
110 Emitted after the static file server determined if a static file should
111 be served and before the router starts its work.
112 $app->hook(before_routes => sub ($c) {...});
114 Mostly used for custom dispatchers and collecting metrics. (Passed the
116 default controller object)
117 around_action
119 Emitted right before an action gets executed and wraps around it, so
120 you have to manually forward to the next hook if you want to continue
121 the chain. Default action dispatching is the last hook in the chain,
122 yours will run before it.
123 $app->hook(around_action => sub ($next, $c, $action, $last) {
125 ...
126 return $next->();
127 });
128 This is a very powerful hook and should not be used lightly, it allows
130 you for example to pass additional arguments to actions or handle
131 return values differently. Note that this hook can trigger more than
132 once for the same request if there are nested routes. (Passed a
133 callback leading to the next hook, the current controller object, the
134 action callback and a flag indicating if this action is an endpoint)
135 before_render
137 Emitted before content is generated by the renderer. Note that this
138 hook can trigger out of order due to its dynamic nature, and with
139 embedded applications will only work for the application that is
140 rendering.
141 $app->hook(before_render => sub ($c, $args) {...});
143 Mostly used for pre-processing arguments passed to the renderer.
145 (Passed the current controller object and the render arguments)
146 after_render
148 Emitted after content has been generated by the renderer that will be
149 assigned to the response. Note that this hook can trigger out of order
150 due to its dynamic nature, and with embedded applications will only
151 work for the application that is rendering.
152 $app->hook(after_render => sub ($c, $output, $format) {...});
154 Mostly used for post-processing dynamically generated content. (Passed
156 the current controller object, a reference to the content and the
157 format)
158 after_dispatch
160 Emitted in reverse order after a response has been generated. Note that
161 this hook can trigger out of order due to its dynamic nature, and with
162 embedded applications will only work for the application that is
163 generating the response.
164 $app->hook(after_dispatch => sub ($c) {...});
166 Useful for rewriting outgoing responses and other post-processing
168 tasks. (Passed the current controller object)
169
171 Mojolicious implements the following attributes.
172 commands
174 my $commands = $app->commands;
175 $app = $app->commands(Mojolicious::Commands->new);
176 Command line interface for your application, defaults to a
178 Mojolicious::Commands object.
179 # Add another namespace to load commands from
181 push @{$app->commands->namespaces}, 'MyApp::Command';
182 controller_class
184 my $class = $app->controller_class;
185 $app = $app->controller_class('Mojolicious::Controller');
186 Class to be used for the default controller, defaults to
188 Mojolicious::Controller. Note that this class needs to have already
189 been loaded before the first request arrives.
190 exception_format
192 my $format = $app->exception_format;
193 $app = $app->exception_format('txt');
194 Format for HTTP exceptions ("html", "json", or "txt"), defaults to
196 "html".
197 home
199 my $home = $app->home;
200 $app = $app->home(Mojo::Home->new);
201 The home directory of your application, defaults to a Mojo::Home object
203 which stringifies to the actual path.
204 # Portably generate path relative to home directory
206 my $path = $app->home->child('data', 'important.txt');
207 log
209 my $log = $app->log;
210 $app = $app->log(Mojo::Log->new);
211 The logging layer of your application, defaults to a Mojo::Log object.
213 The level will default to either the "MOJO_LOG_LEVEL" environment
214 variable, "trace" if the "mode" is "development", or "info" otherwise.
215 All messages will be written to "STDERR" by default.
216 # Log debug message
218 $app->log->debug('It works');
219 max_request_size
221 my $max = $app->max_request_size;
222 $app = $app->max_request_size(16777216);
223 Maximum request size in bytes, defaults to the value of
225 "max_message_size" in Mojo::Message. Setting the value to 0 will allow
226 requests of indefinite size. Note that increasing this value can also
227 drastically increase memory usage, should you for example attempt to
228 parse an excessively large request body with the methods "dom" in
229 Mojo::Message or "json" in Mojo::Message.
230 mode
232 my $mode = $app->mode;
233 $app = $app->mode('production');
234 The operating mode for your application, defaults to a value from the
236 "MOJO_MODE" and "PLACK_ENV" environment variables or "development".
237 moniker
239 my $moniker = $app->moniker;
240 $app = $app->moniker('foo_bar');
241 Moniker of this application, often used as default filename for
243 configuration files and the like, defaults to decamelizing the
244 application class with "decamelize" in Mojo::Util.
245 plugins
247 my $plugins = $app->plugins;
248 $app = $app->plugins(Mojolicious::Plugins->new);
249 The plugin manager, defaults to a Mojolicious::Plugins object. See the
251 "plugin" method below if you want to load a plugin.
252 # Add another namespace to load plugins from
254 push @{$app->plugins->namespaces}, 'MyApp::Plugin';
255 preload_namespaces
257 my $namespaces = $app->preload_namespaces;
258 $app = $app->preload_namespaces(['MyApp::Controller']);
259 Namespaces to preload classes from during application startup.
261 renderer
263 my $renderer = $app->renderer;
264 $app = $app->renderer(Mojolicious::Renderer->new);
265 Used to render content, defaults to a Mojolicious::Renderer object. For
267 more information about how to generate content see
268 Mojolicious::Guides::Rendering.
269 # Enable compression
271 $app->renderer->compress(1);
272 # Add another "templates" directory
274 push @{$app->renderer->paths}, '/home/sri/templates';
275 # Add another "templates" directory with higher precedence
277 unshift @{$app->renderer->paths}, '/home/sri/themes/blue/templates';
278 # Add another class with templates in DATA section
280 push @{$app->renderer->classes}, 'Mojolicious::Plugin::Fun';
281 routes
283 my $routes = $app->routes;
284 $app = $app->routes(Mojolicious::Routes->new);
285 The router, defaults to a Mojolicious::Routes object. You use this in
287 your startup method to define the url endpoints for your application.
288 # Add routes
290 my $r = $app->routes;
291 $r->get('/foo/bar')->to('test#foo', title => 'Hello Mojo!');
292 $r->post('/baz')->to('test#baz');
293 # Add another namespace to load controllers from
295 push @{$app->routes->namespaces}, 'MyApp::MyController';
296 secrets
298 my $secrets = $app->secrets;
299 $app = $app->secrets([$bytes]);
300 Secret passphrases used for signed cookies and the like, defaults to
302 the "moniker" of this application, which is not very secure, so you
303 should change it!!! As long as you are using the insecure default there
304 will be debug messages in the log file reminding you to change your
305 passphrase. Only the first passphrase is used to create new signatures,
306 but all of them for verification. So you can increase security without
307 invalidating all your existing signed cookies by rotating passphrases,
308 just add new ones to the front and remove old ones from the back.
309 # Rotate passphrases
311 $app->secrets(['new_passw0rd', 'old_passw0rd', 'very_old_passw0rd']);
312 sessions
314 my $sessions = $app->sessions;
315 $app = $app->sessions(Mojolicious::Sessions->new);
316 Signed cookie based session manager, defaults to a
318 Mojolicious::Sessions object. You can usually leave this alone, see
319 "session" in Mojolicious::Controller for more information about working
320 with session data.
321 # Change name of cookie used for all sessions
323 $app->sessions->cookie_name('mysession');
324 # Disable SameSite feature
326 $app->sessions->samesite(undef);
327 static
329 my $static = $app->static;
330 $app = $app->static(Mojolicious::Static->new);
331 For serving static files from your "public" directories, defaults to a
333 Mojolicious::Static object.
334 # Add another "public" directory
336 push @{$app->static->paths}, '/home/sri/public';
337 # Add another "public" directory with higher precedence
339 unshift @{$app->static->paths}, '/home/sri/themes/blue/public';
340 # Add another class with static files in DATA section
342 push @{$app->static->classes}, 'Mojolicious::Plugin::Fun';
343 # Remove built-in favicon
345 delete $app->static->extra->{'favicon.ico'};
346 types
348 my $types = $app->types;
349 $app = $app->types(Mojolicious::Types->new);
350 Responsible for connecting file extensions with MIME types, defaults to
352 a Mojolicious::Types object.
353 # Add custom MIME type
355 $app->types->type(twt => 'text/tweet');
356 ua
358 my $ua = $app->ua;
359 $app = $app->ua(Mojo::UserAgent->new);
360 A full featured HTTP user agent for use in your applications, defaults
362 to a Mojo::UserAgent object.
363 # Perform blocking request
365 say $app->ua->get('example.com')->result->body;
366 validator
368 my $validator = $app->validator;
369 $app = $app->validator(Mojolicious::Validator->new);
370 Validate values, defaults to a Mojolicious::Validator object.
372 # Add validation check
374 $app->validator->add_check(foo => sub ($v, $name, $value) {
375 return $value ne 'foo';
376 });
377 # Add validation filter
379 $app->validator->add_filter(quotemeta => sub ($v, $name, $value) {
380 return quotemeta $value;
381 });
382
384 Mojolicious inherits all methods from Mojo::Base and implements the
385 following new ones.
386 build_controller
388 my $c = $app->build_controller;
389 my $c = $app->build_controller(Mojo::Transaction::HTTP->new);
390 my $c = $app->build_controller(Mojolicious::Controller->new);
391 Build default controller object with "controller_class".
393 # Render template from application
395 my $foo = $app->build_controller->render_to_string(template => 'foo');
396 build_tx
398 my $tx = $app->build_tx;
399 Build Mojo::Transaction::HTTP object and emit "after_build_tx" hook.
401 config
403 my $hash = $app->config;
404 my $foo = $app->config('foo');
405 $app = $app->config({foo => 'bar', baz => 23});
406 $app = $app->config(foo => 'bar', baz => 23);
407 Application configuration.
409 # Remove value
411 my $foo = delete $app->config->{foo};
412 # Assign multiple values at once
414 $app->config(foo => 'test', bar => 23);
415 defaults
417 my $hash = $app->defaults;
418 my $foo = $app->defaults('foo');
419 $app = $app->defaults({foo => 'bar', baz => 23});
420 $app = $app->defaults(foo => 'bar', baz => 23);
421 Default values for "stash" in Mojolicious::Controller, assigned for
423 every new request.
424 # Remove value
426 my $foo = delete $app->defaults->{foo};
427 # Assign multiple values at once
429 $app->defaults(foo => 'test', bar => 23);
430 dispatch
432 $app->dispatch(Mojolicious::Controller->new);
433 The heart of every Mojolicious application, calls the "static" and
435 "routes" dispatchers for every request and passes them a
436 Mojolicious::Controller object.
437 handler
439 $app->handler(Mojo::Transaction::HTTP->new);
440 $app->handler(Mojolicious::Controller->new);
441 Sets up the default controller and emits the "around_dispatch" hook for
443 every request.
444 helper
446 $app->helper(foo => sub {...});
447 Add or replace a helper that will be available as a method of the
449 controller object and the application object, as well as a function in
450 "ep" templates. For a full list of helpers that are available by
451 default see Mojolicious::Plugin::DefaultHelpers and
452 Mojolicious::Plugin::TagHelpers.
453 # Helper
455 $app->helper(cache => sub { state $cache = {} });
456 # Application
458 $app->cache->{foo} = 'bar';
459 my $result = $app->cache->{foo};
460 # Controller
462 $c->cache->{foo} = 'bar';
463 my $result = $c->cache->{foo};
464 # Template
466 % cache->{foo} = 'bar';
467 %= cache->{foo}
468 hook
470 $app->hook(after_dispatch => sub {...});
471 Extend Mojolicious with hooks, which allow code to be shared with all
473 requests indiscriminately, for a full list of available hooks see
474 "HOOKS".
475 # Dispatchers will not run if there's already a response code defined
477 $app->hook(before_dispatch => sub ($c) {
478 $c->render(text => 'Skipped static file server and router!')
479 if $c->req->url->path->to_route =~ /do_not_dispatch/;
480 });
481 new
483 my $app = Mojolicious->new;
484 my $app = Mojolicious->new(moniker => 'foo_bar');
485 my $app = Mojolicious->new({moniker => 'foo_bar'});
486 Construct a new Mojolicious application and call "startup". Will
488 automatically detect your home directory. Also sets up the renderer,
489 static file server, a default set of plugins and an "around_dispatch"
490 hook with the default exception handling.
491 plugin
493 $app->plugin('some_thing');
494 $app->plugin('some_thing', foo => 23);
495 $app->plugin('some_thing', {foo => 23});
496 $app->plugin('SomeThing');
497 $app->plugin('SomeThing', foo => 23);
498 $app->plugin('SomeThing', {foo => 23});
499 $app->plugin('MyApp::Plugin::SomeThing');
500 $app->plugin('MyApp::Plugin::SomeThing', foo => 23);
501 $app->plugin('MyApp::Plugin::SomeThing', {foo => 23});
502 Load a plugin, for a full list of example plugins included in the
504 Mojolicious distribution see "PLUGINS" in Mojolicious::Plugins.
505 server
507 $app->server(Mojo::Server->new);
508 Emits the "before_server_start" hook.
510 start
512 $app->start;
513 $app->start(@ARGV);
514 Start the command line interface for your application. For a full list
516 of commands that are available by default see "COMMANDS" in
517 Mojolicious::Commands. Note that the options "-h"/"--help", "--home"
518 and "-m"/"--mode", which are shared by all commands, will be parsed
519 from @ARGV during compile time.
520 # Always start daemon
522 $app->start('daemon', '-l', 'http://*:8080');
523 startup
525 $app->startup;
526 This is your main hook into the application, it will be called at
528 application startup. Meant to be overloaded in a subclass.
529 sub startup ($self) {...}
531 warmup
533 $app->warmup;
534 Preload classes from "preload_namespaces" for future use.
536
538 In addition to the "ATTRIBUTES" and "METHODS" above you can also call
539 helpers on Mojolicious objects. This includes all helpers from
540 Mojolicious::Plugin::DefaultHelpers and
541 Mojolicious::Plugin::TagHelpers. Note that application helpers are
542 always called with a new default controller object, so they can't
543 depend on or change controller state, which includes request, response
544 and stash.
545 # Call helper
547 say $app->dumper({foo => 'bar'});
548 # Longer version
550 say $app->build_controller->helpers->dumper({foo => 'bar'});
551
553 The Mojolicious distribution includes a few files with different
554 licenses that have been bundled for internal use.
555 Mojolicious Artwork
557 Copyright (C) 2010-2022, Sebastian Riedel.
558 Licensed under the CC-SA License, Version 4.0
560 <http://creativecommons.org/licenses/by-sa/4.0>.
561 jQuery
563 Copyright (C) jQuery Foundation.
564 Licensed under the MIT License,
566 <http://creativecommons.org/licenses/MIT>.
567 highlight.js
569 Copyright (C) 2006, Ivan Sagalaev.
570 Licensed under the BSD License,
572 <https://github.com/highlightjs/highlight.js/blob/master/LICENSE>.
573 Bootstrap
575 Copyright 2011-2020 The Bootstrap Authors.
576 Copyright 2011-2020 Twitter, Inc.
577 Licensed under the MIT License,
579 <http://creativecommons.org/licenses/MIT>.
580
582 Every major release of Mojolicious has a code name, these are the ones
583 that have been used in the past.
584 9.0, "Waffle" (U+1F9C7)
586 8.0, "Supervillain" (U+1F9B9)
588 7.0, "Doughnut" (U+1F369)
590 6.0, "Clinking Beer Mugs" (U+1F37B)
592 5.0, "Tiger Face" (U+1F42F)
594 4.0, "Top Hat" (U+1F3A9)
596 3.0, "Rainbow" (U+1F308)
598 2.0, "Leaf Fluttering In Wind" (U+1F343)
600 1.0, "Snowflake" (U+2744)
602
604 • Stix <https://stix.no> sponsored the creation of the Mojolicious logo
605 (designed by Nicolai Graesdal) and transferred its copyright to
606 Sebastian Riedel.
607 • Some of the work on this distribution has been sponsored by The Perl
609 Foundation <https://www.perlfoundation.org>.
610
612 Mojolicious is an open source project that relies on the tireless
613 support of its contributors.
614 Project Founder
616 Sebastian Riedel, "kraih@mojolicious.org"
617 Core Developers
619 Current voting members of the core team in alphabetical order:
620 CandyAngel, "candyangel@mojolicious.org"
622 Christopher Rasch-Olsen Raa, "christopher@mojolicious.org"
624 Dan Book, "grinnz@mojolicious.org"
626 Jan Henning Thorsen, "batman@mojolicious.org"
628 Joel Berger, "jberger@mojolicious.org"
630 Marcus Ramberg, "marcus@mojolicious.org"
632 The following members of the core team are currently on hiatus:
634 Abhijit Menon-Sen, "ams@cpan.org"
636 Glen Hinkle, "tempire@cpan.org"
638 Contributors
640 In alphabetical order:
641 Adam Kennedy
643 Adriano Ferreira
645 Al Newkirk
647 Alex Efros
649 Alex Salimon
651 Alexander Karelas
653 Alexey Likhatskiy
655 Anatoly Sharifulin
657 Andre Parker
659 Andre Vieth
661 Andreas Guldstrand
663 Andreas Jaekel
665 Andreas Koenig
667 Andrew Fresh
669 Andrew Nugged
671 Andrey Khozov
673 Andrey Kuzmin
675 Andy Grundman
677 Andy Lester
679 Aristotle Pagaltzis
681 Ashley Dev
683 Ask Bjoern Hansen
685 Audrey Tang
687 Ben Tyler
689 Ben van Staveren
691 Benjamin Erhart
693 Bernhard Graf
695 Breno G. de Oliveira
697 Brian Duggan
699 Brian Medley
701 Burak Gursoy
703 Ch Lamprecht
705 Charlie Brady
707 Chas. J. Owens IV
709 Chase Whitener
711 Chris Scheller
713 Christian Hansen
715 chromatic
717 Curt Tilmes
719 Daniel Kimsey
721 Daniel Mantovani
723 Danijel Tasov
725 Dagfinn Ilmari Manns�ker
727 Danny Thomas
729 David Davis
731 David Webb
733 Diego Kuperman
735 Dmitriy Shalashov
737 Dmitry Konstantinov
739 Dominik Jarmulowicz
741 Dominique Dumont
743 Dotan Dimet
745 Douglas Christopher Wilson
747 Elmar S. Heeb
749 Ettore Di Giacinto
751 Eugen Konkov
753 Eugene Toropov
755 Flavio Poletti
757 Gisle Aas
759 Graham Barr
761 Graham Knop
763 Heiko Jansen
765 Henry Tang
767 Hideki Yamamura
769 Hiroki Toyokawa
771 Ian Goodacre
773 Ilya Chesnokov
775 Ilya Rassadin
777 James Duncan
779 Jan Jona Javorsek
781 Jan Schmidt
783 Jaroslav Muhin
785 Jesse Vincent
787 Johannes Plunien
789 John Kingsley
791 Jonathan Yu
793 Josh Leder
795 Kamen Naydenov
797 Karen Etheridge
799 Kazuhiro Shibuya
801 Kevin Old
803 Kitamura Akatsuki
805 Klaus S. Madsen
807 Knut Arne Bjorndal
809 Lars Balker Rasmussen
811 Lee Johnson
813 Leon Brocard
815 Magnus Holm
817 Maik Fischer
819 Mark Fowler
821 Mark Grimes
823 Mark Stosberg
825 Martin McGrath
827 Marty Tennison
829 Matt S Trout
831 Matthew Lineen
833 Maksym Komar
835 Maxim Vuets
837 Michael Gregorowicz
839 Michael Harris
841 Michael Jemmeson
843 Mike Magowan
845 Mirko Westermeier
847 Mons Anderson
849 Moritz Lenz
851 Neil Watkiss
853 Nic Sandfield
855 Nils Diewald
857 Oleg Zhelo
859 Olivier Mengue
861 Pascal Gaudette
863 Paul Evans
865 Paul Robins
867 Paul Tomlin
869 Pavel Shaydo
871 Pedro Melo
873 Peter Edwards
875 Pierre-Yves Ritschard
877 Piotr Roszatycki
879 Quentin Carbonneaux
881 Rafal Pocztarski
883 Randal Schwartz
885 Richard Elberger
887 Rick Delaney
889 Robert Hicks
891 Robert Rothenberg
893 Robin Lee
895 Roland Lammel
897 Roy Storey
899 Ryan Jendoubi
901 Salvador Fandino
903 Santiago Zarate
905 Sascha Kiefer
907 Scott Wiersdorf
909 Sebastian Paaske Torholm
911 Sergey Zasenko
913 Simon Bertrang
915 Simone Tampieri
917 Shoichi Kaji
919 Shu Cho
921 Skye Shaw
923 Stanis Trendelenburg
925 Stefan Adams
927 Steffen Ullrich
929 Stephan Kulow
931 Stephane Este-Gracias
933 Stevan Little
935 Steve Atkins
937 Tatsuhiko Miyagawa
939 Terrence Brannon
941 Tianon Gravi
943 Tomas Znamenacek
945 Tudor Constantin
947 Ulrich Habel
949 Ulrich Kautz
951 Uwe Voelker
953 Veesh Goldman
955 Viacheslav Tykhanovskyi
957 Victor Engmark
959 Viliam Pucik
961 Wes Cravens
963 William Lindley
965 Yaroslav Korshak
967 Yuki Kimoto
969 Zak B. Elep
971 Zoffix Znet
973
975 Copyright (C) 2008-2022, Sebastian Riedel and others.
976 This program is free software, you can redistribute it and/or modify it
978 under the terms of the Artistic License version 2.0.
979
981 <https://github.com/mojolicious/mojo>, Mojolicious::Guides,
982 <https://mojolicious.org>.
983perl v5.36.0 2023-01-20 Mojolicious(3)