1Mojolicious::Guides::CoUoskebrooCko(n3t)ributed Perl DocMuomjeonltiactiioouns::Guides::Cookbook(3)
2
6 Mojolicious::Guides::Cookbook - Cooking with Mojolicious
7
9 This document contains many fun recipes for cooking with Mojolicious.
10
12 Essentials every Mojolicious developer should know.
13 Blocking and non-blocking operations
15 A blocking operation is a subroutine that blocks the execution of the
16 calling subroutine until the subroutine is finished.
17 sub foo {
19 my $result = blocking_subroutine();
20 ...
21 }
22 A non-blocking operation on the other hand lets the calling subroutine
24 continue execution even though the subroutine is not yet finished.
25 Instead of waiting, the calling subroutine passes along a callback to
26 be executed once the subroutine is finished, this is called
27 continuation-passing style.
28 sub foo {
30 non_blocking_subroutine(sub {
31 my $result = shift;
32 ...
33 });
34 ...
35 }
36 While Mojolicious has been designed from the ground up for non-blocking
38 I/O and event loops, it is not possible to magically make Perl code
39 non-blocking. You have to use specialized non-blocking code available
40 through modules like Mojo::IOLoop and Mojo::UserAgent, or third-party
41 event loops. You can wrap your blocking code in subprocesses though to
42 prevent it from interfering with your non-blocking code.
43 Event loops
45 An event loop is basically a loop that continually tests for external
46 events and executes the appropriate callbacks to handle them, it is
47 often the main loop in a program. Non-blocking tests for
48 readability/writability of file descriptors and timers are commonly
49 used events for highly scalable network servers, because they allow a
50 single process to handle thousands of client connections concurrently.
51 while (1) {
53 my @readable = test_fds_for_readability();
54 handle_readable_fds(@readable);
55 my @writable = test_fds_for_writability();
57 handle_writable_fds(@writable);
58 my @expired = test_timers();
60 handle_timers(@expired);
61 }
62 In Mojolicious this event loop is Mojo::IOLoop.
64 Reverse proxy
66 A reverse proxy architecture is a deployment technique used in many
67 production environments, where a reverse proxy server is put in front
68 of your application to act as the endpoint accessible by external
69 clients. It can provide a lot of benefits, like terminating SSL
70 connections from the outside, limiting the number of concurrent open
71 sockets towards the Mojolicious application (or even using Unix
72 sockets), balancing load across multiple instances, or supporting
73 several applications through the same IP/port.
74 ..........................................
76 : :
77 +--------+ : +-----------+ +---------------+ :
78 | |-------->| | | | :
79 | client | : | reverse |----->| Mojolicious | :
80 | |<--------| proxy | | application | :
81 +--------+ : | |<-----| | :
82 : +-----------+ +---------------+ :
83 : :
84 .. system boundary (e.g. same host) ......
85 This setup introduces some problems, though: the application will
87 receive requests from the reverse proxy instead of the original client;
88 the address/hostname where your application lives internally will be
89 different from the one visible from the outside; and if terminating
90 SSL, the reverse proxy exposes services via HTTPS while using HTTP
91 towards the Mojolicious application.
92 As an example, compare a sample request from the client and what the
94 Mojolicious application receives:
95 client reverse proxy Mojolicious app
97 __|__ _______________|______________ ____|____
98 / \ / \ / \
99 1.2.3.4 --HTTPS--> api.example.com 10.20.30.39 --HTTP--> 10.20.30.40
100 GET /foo/1 HTTP/1.1 | GET /foo/1 HTTP/1.1
102 Host: api.example.com | Host: 10.20.30.40
103 User-Agent: Firefox | User-Agent: ShinyProxy/1.2
104 ... | ...
105 However, now the client address is no longer available (which might be
107 useful for analytics, or Geo-IP) and URLs generated via "url_for" in
108 Mojolicious::Controller will look like this:
109 http://10.20.30.40/bar/2
111 instead of something meaningful for the client, like this:
113 https://api.example.com/bar/2
115 To solve these problems, you can configure your reverse proxy to send
117 the missing data (see "Nginx" and "Apache/mod_proxy") and tell your
118 application about it by setting the environment variable
119 "MOJO_REVERSE_PROXY". For finer control, "Rewriting" includes examples
120 of how the changes could be implemented manually.
121
123 Getting Mojolicious and Mojolicious::Lite applications running on
124 different platforms. Note that many real-time web features are based on
125 the Mojo::IOLoop event loop, and therefore require one of the built-in
126 web servers to be able to use them to their full potential.
127 Built-in web server
129 Mojolicious contains a very portable non-blocking I/O HTTP and
130 WebSocket server with Mojo::Server::Daemon. It is usually used during
131 development and in the construction of more advanced web servers, but
132 is solid and fast enough for small to mid sized applications.
133 $ ./script/my_app daemon
135 Server available at http://127.0.0.1:3000
136 It is available to every application through the command
138 Mojolicious::Command::daemon, which has many configuration options and
139 is known to work on every platform Perl works on with its single-
140 process architecture.
141 $ ./script/my_app daemon -h
143 ...List of available options...
144 Another huge advantage is that it supports TLS and WebSockets out of
146 the box, a development certificate for testing purposes is built right
147 in, so it just works, but you can specify all listen locations
148 supported by "listen" in Mojo::Server::Daemon.
149 $ ./script/my_app daemon -l https://[::]:3000
151 Server available at https://[::]:3000
152 To manage the web server with systemd, you can use a unit configuration
154 file like this.
155 [Unit]
157 Description=My Mojolicious application
158 After=network.target
159 [Service]
161 Type=simple
162 ExecStart=/home/sri/myapp/script/my_app daemon -m production -l http://*:8080
163 [Install]
165 WantedBy=multi-user.target
166 Pre-forking
168 On UNIX platforms you can also add pre-forking to the built-in web
169 server and switch to a multi-process architecture with
170 Mojolicious::Command::prefork, to take advantage of multiple CPU cores
171 and copy-on-write memory management.
172 $ ./script/my_app prefork
174 Server available at http://127.0.0.1:3000
175 Since all built-in web servers are based on the Mojo::IOLoop event
177 loop, they scale best with non-blocking operations. But if your
178 application for some reason needs to perform many blocking operations,
179 you can improve performance by increasing the number of worker
180 processes and decreasing the number of concurrent connections each
181 worker is allowed to handle (often as low as 1).
182 $ ./script/my_app prefork -m production -w 10 -c 1
184 Server available at http://127.0.0.1:3000
185 During startup your application is preloaded in the manager process,
187 which does not run an event loop, so you can use "next_tick" in
188 Mojo::IOLoop to run code whenever a new worker process has been forked
189 and its event loop gets started.
190 use Mojolicious::Lite;
192 Mojo::IOLoop->next_tick(sub {
194 app->log->info("Worker $$ star...ALL GLORY TO THE HYPNOTOAD!");
195 });
196 get '/' => {text => 'Hello Wor...ALL GLORY TO THE HYPNOTOAD!'};
198 app->start;
200 And to manage the pre-forking web server with systemd, you can use a
202 unit configuration file like this.
203 [Unit]
205 Description=My Mojolicious application
206 After=network.target
207 [Service]
209 Type=simple
210 ExecStart=/home/sri/myapp/script/my_app prefork -m production -l http://*:8080
211 [Install]
213 WantedBy=multi-user.target
214 Morbo
216 After reading the Mojolicious::Guides::Tutorial, you should already be
217 familiar with Mojo::Server::Morbo.
218 Mojo::Server::Morbo
220 +- Mojo::Server::Daemon
221 It is basically a restarter that forks a new Mojo::Server::Daemon web
223 server whenever a file in your project changes, and should therefore
224 only be used during development. To start applications with it you can
225 use the morbo script.
226 $ morbo ./script/my_app
228 Server available at http://127.0.0.1:3000
229 Hypnotoad
231 For bigger applications Mojolicious contains the UNIX optimized pre-
232 forking web server Hypnotoad, which can take advantage of multiple CPU
233 cores and copy-on-write memory management to scale up to thousands of
234 concurrent client connections.
235 Mojo::Server::Hypnotoad
237 |- Mojo::Server::Daemon [1]
238 |- Mojo::Server::Daemon [2]
239 |- Mojo::Server::Daemon [3]
240 +- Mojo::Server::Daemon [4]
241 It is based on the Mojo::Server::Prefork web server, which adds pre-
243 forking to Mojo::Server::Daemon, but optimized specifically for
244 production environments out of the box. To start applications with it
245 you can use the hypnotoad script, which listens on port 8080,
246 automatically daemonizes the server process and defaults to
247 "production" mode for Mojolicious and Mojolicious::Lite applications.
248 $ hypnotoad ./script/my_app
250 Many configuration settings can be tweaked right from within your
252 application with "config" in Mojolicious, for a full list see
253 "SETTINGS" in Mojo::Server::Hypnotoad.
254 use Mojolicious::Lite;
256 app->config(hypnotoad => {listen => ['http://*:80']});
258 get '/' => {text => 'Hello Wor...ALL GLORY TO THE HYPNOTOAD!'};
260 app->start;
262 Or just add a "hypnotoad" section to your Mojolicious::Plugin::Config
264 or Mojolicious::Plugin::JSONConfig configuration file.
265 # myapp.conf
267 {
268 hypnotoad => {
269 listen => ['https://*:443?cert=/etc/server.crt&key=/etc/server.key'],
270 workers => 10
271 }
272 };
273 But one of its biggest advantages is the support for effortless zero
275 downtime software upgrades (hot deployment). That means you can upgrade
276 Mojolicious, Perl or even system libraries at runtime without ever
277 stopping the server or losing a single incoming connection, just by
278 running the command above again.
279 $ hypnotoad ./script/my_app
281 Starting hot deployment for Hypnotoad server 31841.
282 You might also want to enable proxy support if you're using Hypnotoad
284 behind a reverse proxy. This allows Mojolicious to automatically pick
285 up the "X-Forwarded-For" and "X-Forwarded-Proto" headers.
286 # myapp.conf
288 {hypnotoad => {proxy => 1}};
289 To manage Hypnotoad with systemd, you can use a unit configuration file
291 like this.
292 [Unit]
294 Description=My Mojolicious application
295 After=network.target
296 [Service]
298 Type=forking
299 PIDFile=/home/sri/myapp/script/hypnotoad.pid
300 ExecStart=/path/to/hypnotoad /home/sri/myapp/script/my_app
301 ExecReload=/path/to/hypnotoad /home/sri/myapp/script/my_app
302 KillMode=process
303 [Install]
305 WantedBy=multi-user.target
306 Zero downtime software upgrades
308 Hypnotoad makes zero downtime software upgrades (hot deployment) very
309 simple, as you can see above, but on modern operating systems that
310 support the "SO_REUSEPORT" socket option, there is also another method
311 available that works with all built-in web servers.
312 $ ./script/my_app prefork -P /tmp/first.pid -l http://*:8080?reuse=1
314 Server available at http://127.0.0.1:8080
315 All you have to do, is to start a second web server listening to the
317 same port, and stop the first web server gracefully afterwards.
318 $ ./script/my_app prefork -P /tmp/second.pid -l http://*:8080?reuse=1
320 Server available at http://127.0.0.1:8080
321 $ kill -s TERM `cat /tmp/first.pid`
322 Just remember that both web servers need to be started with the "reuse"
324 parameter.
325 Nginx
327 One of the most popular setups these days is Hypnotoad behind an Nginx
328 <http://nginx.org> reverse proxy, which even supports WebSockets in
329 newer versions.
330 upstream myapp {
332 server 127.0.0.1:8080;
333 }
334 server {
335 listen 80;
336 server_name localhost;
337 location / {
338 proxy_pass http://myapp;
339 proxy_http_version 1.1;
340 proxy_set_header Upgrade $http_upgrade;
341 proxy_set_header Connection "upgrade";
342 proxy_set_header Host $host;
343 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
344 proxy_set_header X-Forwarded-Proto $scheme;
345 }
346 }
347 Apache/mod_proxy
349 Another good reverse proxy is Apache <http://httpd.apache.org> with
350 "mod_proxy", the configuration looks quite similar to the Nginx one
351 above. And if you need WebSocket support, newer versions come with
352 "mod_proxy_wstunnel".
353 <VirtualHost *:80>
355 ServerName localhost
356 <Proxy *>
357 Require all granted
358 </Proxy>
359 ProxyRequests Off
360 ProxyPreserveHost On
361 ProxyPass /echo ws://localhost:8080/echo
362 ProxyPass / http://localhost:8080/ keepalive=On
363 ProxyPassReverse / http://localhost:8080/
364 RequestHeader set X-Forwarded-Proto "http"
365 </VirtualHost>
366 Apache/CGI
368 "CGI" is supported out of the box and your Mojolicious application will
369 automatically detect that it is executed as a "CGI" script. Its use in
370 production environments is discouraged though, because as a result of
371 how "CGI" works, it is very slow and many web servers are making it
372 exceptionally hard to configure properly. Additionally, many real-time
373 web features, such as WebSockets, are not available.
374 ScriptAlias / /home/sri/my_app/script/my_app/
376 PSGI/Plack
378 PSGI is an interface between Perl web frameworks and web servers, and
379 Plack is a Perl module and toolkit that contains PSGI middleware,
380 helpers and adapters to web servers. PSGI and Plack are inspired by
381 Python's WSGI and Ruby's Rack. Mojolicious applications are
382 ridiculously simple to deploy with Plack, but be aware that many real-
383 time web features, such as WebSockets, are not available.
384 $ plackup ./script/my_app
386 Plack provides many server and protocol adapters for you to choose
388 from, such as "FCGI", "uWSGI" and "mod_perl".
389 $ plackup ./script/my_app -s FCGI -l /tmp/myapp.sock
391 The "MOJO_REVERSE_PROXY" environment variable can be used to enable
393 proxy support, this allows Mojolicious to automatically pick up the
394 "X-Forwarded-For" and "X-Forwarded-Proto" headers.
395 $ MOJO_REVERSE_PROXY=1 plackup ./script/my_app
397 If an older server adapter is unable to correctly detect the
399 application home directory, you can simply use the "MOJO_HOME"
400 environment variable.
401 $ MOJO_HOME=/home/sri/my_app plackup ./script/my_app
403 There is no need for a ".psgi" file, just point the server adapter at
405 your application script, it will automatically act like one if it
406 detects the presence of a "PLACK_ENV" environment variable.
407 Plack middleware
409 Wrapper scripts like "myapp.fcgi" are a great way to separate
410 deployment and application logic.
411 #!/usr/bin/env plackup -s FCGI
413 use Plack::Builder;
414 builder {
416 enable 'Deflater';
417 require './script/my_app';
418 };
419 Mojo::Server::PSGI can be used directly to load and customize
421 applications in the wrapper script.
422 #!/usr/bin/env plackup -s FCGI
424 use Mojo::Server::PSGI;
425 use Plack::Builder;
426 builder {
428 enable 'Deflater';
429 my $server = Mojo::Server::PSGI->new;
430 $server->load_app('./script/my_app');
431 $server->app->config(foo => 'bar');
432 $server->to_psgi_app;
433 };
434 But you could even use middleware right in your application.
436 use Mojolicious::Lite;
438 use Plack::Builder;
439 get '/welcome' => sub {
441 my $c = shift;
442 $c->render(text => 'Hello Mojo!');
443 };
444 builder {
446 enable 'Deflater';
447 app->start;
448 };
449 Rewriting
451 Sometimes you might have to deploy your application in a blackbox
452 environment where you can't just change the server configuration or
453 behind a reverse proxy that passes along additional information with
454 "X-Forwarded-*" headers. In such cases you can use the hook
455 "before_dispatch" in Mojolicious to rewrite incoming requests.
456 # Change scheme if "X-Forwarded-HTTPS" header is set
458 $app->hook(before_dispatch => sub {
459 my $c = shift;
460 $c->req->url->base->scheme('https')
461 if $c->req->headers->header('X-Forwarded-HTTPS');
462 });
463 Since reverse proxies generally don't pass along information about path
465 prefixes your application might be deployed under, rewriting the base
466 path of incoming requests is also quite common. This allows "url_for"
467 in Mojolicious::Controller for example, to generate portable URLs based
468 on the current environment.
469 # Move first part and slash from path to base path in production mode
471 $app->hook(before_dispatch => sub {
472 my $c = shift;
473 push @{$c->req->url->base->path->trailing_slash(1)},
474 shift @{$c->req->url->path->leading_slash(0)};
475 }) if $app->mode eq 'production';
476 Mojo::URL objects are very easy to manipulate, just make sure that the
478 URL ("foo/bar?baz=yada"), which represents the routing destination, is
479 always relative to the base URL ("http://example.com/myapp/"), which
480 represents the deployment location of your application.
481 Application embedding
483 From time to time you might want to reuse parts of Mojolicious
484 applications like configuration files, database connection or helpers
485 for other scripts, with this little Mojo::Server based mock server you
486 can just embed them.
487 use Mojo::Server;
489 # Load application with mock server
491 my $server = Mojo::Server->new;
492 my $app = $server->load_app('./myapp.pl');
493 # Access fully initialized application
495 say for @{$app->static->paths};
496 say $app->config->{secret_identity};
497 say $app->dumper({just => 'a helper test'});
498 say $app->build_controller->render_to_string(template => 'foo');
499 The plugin Mojolicious::Plugin::Mount uses this functionality to allow
501 you to combine multiple applications into one and deploy them together.
502 use Mojolicious::Lite;
504 app->config(hypnotoad => {listen => ['http://*:80']});
506 plugin Mount => {'test1.example.com' => '/home/sri/myapp1.pl'};
508 plugin Mount => {'test2.example.com' => '/home/sri/myapp2.pl'};
509 app->start;
511 Web server embedding
513 You can also use "one_tick" in Mojo::IOLoop to embed the built-in web
514 server Mojo::Server::Daemon into alien environments like foreign event
515 loops that for some reason can't just be integrated with a new reactor
516 backend.
517 use Mojolicious::Lite;
519 use Mojo::IOLoop;
520 use Mojo::Server::Daemon;
521 # Normal action
523 get '/' => {text => 'Hello World!'};
524 # Connect application with web server and start accepting connections
526 my $daemon
527 = Mojo::Server::Daemon->new(app => app, listen => ['http://*:8080']);
528 $daemon->start;
529 # Call "one_tick" repeatedly from the alien environment
531 Mojo::IOLoop->one_tick while 1;
532
534 The real-time web is a collection of technologies that include Comet
535 (long polling), EventSource and WebSockets, which allow content to be
536 pushed to consumers with long-lived connections as soon as it is
537 generated, instead of relying on the more traditional pull model. All
538 built-in web servers use non-blocking I/O and are based on the
539 Mojo::IOLoop event loop, which provides many very powerful features
540 that allow real-time web applications to scale up to thousands of
541 concurrent client connections.
542 Backend web services
544 Since Mojo::UserAgent is also based on the Mojo::IOLoop event loop, it
545 won't block the built-in web servers when used non-blocking, even for
546 high latency backend web services.
547 use Mojolicious::Lite;
549 # Search MetaCPAN for "mojolicious"
551 get '/' => sub {
552 my $c = shift;
553 $c->ua->get('fastapi.metacpan.org/v1/module/_search?q=mojolicious' => sub {
554 my ($ua, $tx) = @_;
555 $c->render('metacpan', hits => $tx->result->json->{hits}{hits});
556 });
557 };
558 app->start;
560 __DATA__
561 @@ metacpan.html.ep
563 <!DOCTYPE html>
564 <html>
565 <head><title>MetaCPAN results for "mojolicious"</title></head>
566 <body>
567 % for my $hit (@$hits) {
568 <p><%= $hit->{_source}{release} %></p>
569 % }
570 </body>
571 </html>
572 The callback passed to "get" in Mojo::UserAgent will be executed once
574 the request to the backend web service has been finished, this is
575 called continuation-passing style.
576 Synchronizing non-blocking operations
578 Multiple non-blocking operations, such as concurrent requests, can be
579 easily synchronized with promises and "all" in Mojo::Promise. You
580 create Mojo::Promise objects manually or use methods like "get_p" in
581 Mojo::UserAgent that create them for you.
582 use Mojolicious::Lite;
584 use Mojo::Promise;
585 use Mojo::URL;
586 # Search MetaCPAN for "mojo" and "minion"
588 get '/' => sub {
589 my $c = shift;
590 # Create two promises
592 my $url = Mojo::URL->new('fastapi.metacpan.org/v1/module/_search');
593 my $mojo = $c->ua->get_p($url->clone->query({q => 'mojo'}));
594 my $minion = $c->ua->get_p($url->clone->query({q => 'minion'}));
595 # Render a response once both promises have been resolved
597 Mojo::Promise->all($mojo, $minion)->then(sub {
598 my ($mojo, $minion) = @_;
599 $c->render(json => {
600 mojo => $mojo->[0]->result->json('/hits/hits/0/_source/release'),
601 minion => $minion->[0]->result->json('/hits/hits/0/_source/release')
602 });
603 })->catch(sub {
604 my $err = shift;
605 $c->reply->exception($err);
606 })->wait;
607 };
608 app->start;
610 To create promises manually you just wrap your continuation-passing
612 style APIs in functions that return promises. Here's an example for how
613 "get_p" in Mojo::UserAgent works internally.
614 use Mojo::UserAgent;
616 use Mojo::Promise;
617 # Wrap a user agent method with a promise
619 my $ua = Mojo::UserAgent->new;
620 sub get_p {
621 my $promise = Mojo::Promise->new;
622 $ua->get(@_ => sub {
623 my ($ua, $tx) = @_;
624 my $err = $tx->error;
625 $promise->resolve($tx) if !$err || $err->{code};
626 $promise->reject($err->{message});
627 });
628 return $promise;
629 }
630 # Use our new promise generating function
632 get_p('https://mojolicious.org')->then(sub {
633 my $tx = shift;
634 say $tx->result->dom->at('title')->text;
635 })->wait;
636 Promises have three states, they start out as "pending" and you call
638 "resolve" in Mojo::Promise to transition them to "fulfilled", or
639 "reject" in Mojo::Promise to transition them to "rejected".
640 Timers
642 Timers, another primary feature of the event loop, are created with
643 "timer" in Mojo::IOLoop and can, for example, be used to delay
644 rendering of a response, and unlike "sleep", won't block any other
645 requests that might be processed concurrently.
646 use Mojolicious::Lite;
648 use Mojo::IOLoop;
649 # Wait 3 seconds before rendering a response
651 get '/' => sub {
652 my $c = shift;
653 Mojo::IOLoop->timer(3 => sub {
654 $c->render(text => 'Delayed by 3 seconds!');
655 });
656 };
657 app->start;
659 Recurring timers created with "recurring" in Mojo::IOLoop are slightly
661 more powerful, but need to be stopped manually, or they would just keep
662 getting emitted.
663 use Mojolicious::Lite;
665 use Mojo::IOLoop;
666 # Count to 5 in 1 second steps
668 get '/' => sub {
669 my $c = shift;
670 # Start recurring timer
672 my $i = 1;
673 my $id = Mojo::IOLoop->recurring(1 => sub {
674 $c->write_chunk($i);
675 $c->finish if $i++ == 5;
676 });
677 # Stop recurring timer
679 $c->on(finish => sub { Mojo::IOLoop->remove($id) });
680 };
681 app->start;
683 Timers are not tied to a specific request or connection, and can even
685 be created at startup time.
686 use Mojolicious::Lite;
688 use Mojo::IOLoop;
689 # Check title in the background every 10 seconds
691 my $title = 'Got no title yet.';
692 Mojo::IOLoop->recurring(10 => sub {
693 app->ua->get('https://mojolicious.org' => sub {
694 my ($ua, $tx) = @_;
695 $title = $tx->result->dom->at('title')->text;
696 });
697 });
698 # Show current title
700 get '/' => sub {
701 my $c = shift;
702 $c->render(json => {title => $title});
703 };
704 app->start;
706 Just remember that all these non-blocking operations are processed
708 cooperatively, so your callbacks shouldn't block for too long.
709 Subprocesses
711 You can also use subprocesses, created with "subprocess" in
712 Mojo::IOLoop, to perform computationally expensive operations without
713 blocking the event loop.
714 use Mojolicious::Lite;
716 use Mojo::IOLoop;
717 # Operation that would block the event loop for 5 seconds
719 get '/' => sub {
720 my $c = shift;
721 Mojo::IOLoop->subprocess(
722 sub {
723 my $subprocess = shift;
724 sleep 5;
725 return '♥', 'Mojolicious';
726 },
727 sub {
728 my ($subprocess, $err, @results) = @_;
729 $c->reply->exception($err) and return if $err;
730 $c->render(text => "I $results[0] $results[1]!");
731 }
732 );
733 };
734 app->start;
736 The first callback will be executed in a child process, without
738 blocking the event loop of the parent process. The results of the first
739 callback will then be shared between both processes, and the second
740 callback executed in the parent process.
741 Exceptions in non-blocking operations
743 Since timers and other non-blocking operations are running solely in
744 the event loop, outside of the application, exceptions that get thrown
745 in callbacks can't get caught and handled automatically. But you can
746 handle them manually by subscribing to the event "error" in
747 Mojo::Reactor or catching them inside the callback.
748 use Mojolicious::Lite;
750 use Mojo::IOLoop;
751 # Forward error messages to the application log
753 Mojo::IOLoop->singleton->reactor->on(error => sub {
754 my ($reactor, $err) = @_;
755 app->log->error($err);
756 });
757 # Exception only gets logged (and connection times out)
759 get '/connection_times_out' => sub {
760 my $c = shift;
761 Mojo::IOLoop->timer(2 => sub {
762 die 'This request will not be getting a response';
763 });
764 };
765 # Exception gets caught and handled
767 get '/catch_exception' => sub {
768 my $c = shift;
769 Mojo::IOLoop->timer(2 => sub {
770 eval { die 'This request will be getting a response' };
771 $c->reply->exception($@) if $@;
772 });
773 };
774 app->start;
776 A default subscriber that turns all errors into warnings will usually
778 be added by Mojo::IOLoop as a fallback.
779 Mojo::IOLoop->singleton->reactor->unsubscribe('error');
781 During development or for applications where crashing is simply
783 preferable, you can also make every exception that gets thrown in a
784 callback fatal by removing all of its subscribers.
785 WebSocket web service
787 The WebSocket protocol offers full bi-directional low-latency
788 communication channels between clients and servers. Receive messages
789 just by subscribing to events such as "message" in
790 Mojo::Transaction::WebSocket with "on" in Mojolicious::Controller and
791 return them with "send" in Mojolicious::Controller.
792 use Mojolicious::Lite;
794 # Template with browser-side code
796 get '/' => 'index';
797 # WebSocket echo service
799 websocket '/echo' => sub {
800 my $c = shift;
801 # Opened
803 $c->app->log->debug('WebSocket opened');
804 # Increase inactivity timeout for connection a bit
806 $c->inactivity_timeout(300);
807 # Incoming message
809 $c->on(message => sub {
810 my ($c, $msg) = @_;
811 $c->send("echo: $msg");
812 });
813 # Closed
815 $c->on(finish => sub {
816 my ($c, $code, $reason) = @_;
817 $c->app->log->debug("WebSocket closed with status $code");
818 });
819 };
820 app->start;
822 __DATA__
823 @@ index.html.ep
825 <!DOCTYPE html>
826 <html>
827 <head><title>Echo</title></head>
828 <body>
829 <script>
830 var ws = new WebSocket('<%= url_for('echo')->to_abs %>');
831 // Incoming messages
833 ws.onmessage = function (event) {
834 document.body.innerHTML += event.data + '<br/>';
835 };
836 // Outgoing messages
838 ws.onopen = function (event) {
839 window.setInterval(function () { ws.send('Hello Mojo!') }, 1000);
840 };
841 </script>
842 </body>
843 </html>
844 The event "finish" in Mojo::Transaction::WebSocket will be emitted
846 right after the WebSocket connection has been closed.
847 $c->tx->with_compression;
849 You can activate "permessage-deflate" compression with
851 "with_compression" in Mojo::Transaction::WebSocket, this can result in
852 much better performance, but also increases memory usage by up to
853 300KiB per connection.
854 my $proto = $c->tx->with_protocols('v2.proto', 'v1.proto');
856 You can also use "with_protocols" in Mojo::Transaction::WebSocket to
858 negotiate a subprotocol.
859 EventSource web service
861 EventSource is a special form of long polling where you can use "write"
862 in Mojolicious::Controller to directly send DOM events from servers to
863 clients. It is uni-directional, that means you will have to use Ajax
864 requests for sending data from clients to servers, the advantage
865 however is low infrastructure requirements, since it reuses the HTTP
866 protocol for transport.
867 use Mojolicious::Lite;
869 # Template with browser-side code
871 get '/' => 'index';
872 # EventSource for log messages
874 get '/events' => sub {
875 my $c = shift;
876 # Increase inactivity timeout for connection a bit
878 $c->inactivity_timeout(300);
879 # Change content type and finalize response headers
881 $c->res->headers->content_type('text/event-stream');
882 $c->write;
883 # Subscribe to "message" event and forward "log" events to browser
885 my $cb = $c->app->log->on(message => sub {
886 my ($log, $level, @lines) = @_;
887 $c->write("event:log\ndata: [$level] @lines\n\n");
888 });
889 # Unsubscribe from "message" event again once we are done
891 $c->on(finish => sub {
892 my $c = shift;
893 $c->app->log->unsubscribe(message => $cb);
894 });
895 };
896 app->start;
898 __DATA__
899 @@ index.html.ep
901 <!DOCTYPE html>
902 <html>
903 <head><title>LiveLog</title></head>
904 <body>
905 <script>
906 var events = new EventSource('<%= url_for 'events' %>');
907 // Subscribe to "log" event
909 events.addEventListener('log', function (event) {
910 document.body.innerHTML += event.data + '<br/>';
911 }, false);
912 </script>
913 </body>
914 </html>
915 The event "message" in Mojo::Log will be emitted for every new log
917 message and the event "finish" in Mojo::Transaction right after the
918 transaction has been finished.
919 Streaming multipart uploads
921 Mojolicious contains a very sophisticated event system based on
922 Mojo::EventEmitter, with ready-to-use events on almost all layers, and
923 which can be combined to solve some of the hardest problems in web
924 development.
925 use Mojolicious::Lite;
927 use Scalar::Util 'weaken';
928 # Intercept multipart uploads and log each chunk received
930 hook after_build_tx => sub {
931 my $tx = shift;
932 # Subscribe to "upgrade" event to identify multipart uploads
934 weaken $tx;
935 $tx->req->content->on(upgrade => sub {
936 my ($single, $multi) = @_;
937 return unless $tx->req->url->path->contains('/upload');
938 # Subscribe to "part" event to find the right one
940 $multi->on(part => sub {
941 my ($multi, $single) = @_;
942 # Subscribe to "body" event of part to make sure we have all headers
944 $single->on(body => sub {
945 my $single = shift;
946 # Make sure we have the right part and replace "read" event
948 return unless $single->headers->content_disposition =~ /example/;
949 $single->unsubscribe('read')->on(read => sub {
950 my ($single, $bytes) = @_;
951 # Log size of every chunk we receive
953 app->log->debug(length($bytes) . ' bytes uploaded');
954 });
955 });
956 });
957 });
958 };
959 # Upload form in DATA section
961 get '/' => 'index';
962 # Streaming multipart upload
964 post '/upload' => {text => 'Upload was successful.'};
965 app->start;
967 __DATA__
968 @@ index.html.ep
970 <!DOCTYPE html>
971 <html>
972 <head><title>Streaming multipart upload</title></head>
973 <body>
974 %= form_for upload => (enctype => 'multipart/form-data') => begin
975 %= file_field 'example'
976 %= submit_button 'Upload'
977 % end
978 </body>
979 </html>
980 More event loops
982 Internally, the Mojo::IOLoop event loop can use multiple reactor
983 backends, EV for example, will be automatically used if possible. Which
984 in turn allows other event loops like AnyEvent to just work.
985 use Mojolicious::Lite;
987 use EV;
988 use AnyEvent;
989 # Wait 3 seconds before rendering a response
991 get '/' => sub {
992 my $c = shift;
993 my $w;
994 $w = AE::timer 3, 0, sub {
995 $c->render(text => 'Delayed by 3 seconds!');
996 undef $w;
997 };
998 };
999 app->start;
1001 Who actually controls the event loop backend is not important.
1003 use Mojo::UserAgent;
1005 use EV;
1006 use AnyEvent;
1007 # Search MetaCPAN for "mojolicious"
1009 my $cv = AE::cv;
1010 my $ua = Mojo::UserAgent->new;
1011 $ua->get('fastapi.metacpan.org/v1/module/_search?q=mojolicious' => sub {
1012 my ($ua, $tx) = @_;
1013 $cv->send($tx->result->json('/hits/hits/0/_source/release'));
1014 });
1015 say $cv->recv;
1016 You could, for example, just embed the built-in web server into an
1018 AnyEvent application.
1019 use Mojolicious::Lite;
1021 use Mojo::Server::Daemon;
1022 use EV;
1023 use AnyEvent;
1024 # Normal action
1026 get '/' => {text => 'Hello World!'};
1027 # Connect application with web server and start accepting connections
1029 my $daemon
1030 = Mojo::Server::Daemon->new(app => app, listen => ['http://*:8080']);
1031 $daemon->start;
1032 # Let AnyEvent take control
1034 AE::cv->recv;
1035
1037 When we say Mojolicious is a web framework we actually mean it, with
1038 Mojo::UserAgent there's a full featured HTTP and WebSocket user agent
1039 built right in.
1040 REST web services
1042 Requests can be performed very comfortably with methods like "get" in
1043 Mojo::UserAgent, and always result in a Mojo::Transaction::HTTP object,
1044 which has many useful attributes and methods. You can check for
1045 connection errors with "result" in Mojo::Transaction, or access HTTP
1046 request and response information directly through "req" in
1047 Mojo::Transaction and "res" in Mojo::Transaction.
1048 use Mojo::UserAgent;
1050 # Request a resource and make sure there were no connection errors
1052 my $ua = Mojo::UserAgent->new;
1053 my $tx = $ua->get('mojolicious.org/perldoc/Mojo' => {Accept => 'text/plain'});
1054 my $res = $tx->result;
1055 # Decide what to do with its representation
1057 if ($res->is_success) { say $res->body }
1058 elsif ($res->is_error) { say $res->message }
1059 elsif ($res->code == 301) { say $res->headers->location }
1060 else { say 'Whatever...' }
1061 While methods like "is_success" in Mojo::Message::Response and
1063 "is_error" in Mojo::Message::Response serve as building blocks for more
1064 sophisticated REST clients.
1065 Web scraping
1067 Scraping information from websites has never been this much fun before.
1068 The built-in HTML/XML parser Mojo::DOM is accessible through "dom" in
1069 Mojo::Message and supports all CSS selectors that make sense for a
1070 standalone parser, it can be a very powerful tool especially for
1071 testing web application.
1072 use Mojo::UserAgent;
1074 # Fetch website
1076 my $ua = Mojo::UserAgent->new;
1077 my $res = $ua->get('mojolicious.org/perldoc')->result;
1078 # Extract title
1080 say 'Title: ', $res->dom->at('head > title')->text;
1081 # Extract headings
1083 $res->dom('h1, h2, h3')->each(sub { say 'Heading: ', shift->all_text });
1084 # Visit all nodes recursively to extract more than just text
1086 for my $n ($res->dom->descendant_nodes->each) {
1087 # Text or CDATA node
1089 print $n->content if $n->type eq 'text' || $n->type eq 'cdata';
1090 # Also include alternate text for images
1092 print $n->{alt} if $n->type eq 'tag' && $n->tag eq 'img';
1093 }
1094 For a full list of available CSS selectors see "SELECTORS" in
1096 Mojo::DOM::CSS.
1097 JSON web services
1099 Most web services these days are based on the JSON data-interchange
1100 format. That's why Mojolicious comes with the possibly fastest pure-
1101 Perl implementation Mojo::JSON built right in, which is accessible
1102 through "json" in Mojo::Message.
1103 use Mojo::UserAgent;
1105 use Mojo::URL;
1106 # Fresh user agent
1108 my $ua = Mojo::UserAgent->new;
1109 # Search MetaCPAN for "mojolicious" and list latest releases
1111 my $url = Mojo::URL->new('http://fastapi.metacpan.org/v1/release/_search');
1112 $url->query({q => 'mojolicious', sort => 'date:desc'});
1113 for my $hit (@{$ua->get($url)->result->json->{hits}{hits}}) {
1114 say "$hit->{_source}{name} ($hit->{_source}{author})";
1115 }
1116 Basic authentication
1118 You can just add username and password to the URL, an "Authorization"
1119 header will be automatically generated.
1120 use Mojo::UserAgent;
1122 my $ua = Mojo::UserAgent->new;
1124 say $ua->get('https://sri:secret@example.com/hideout')->result->body;
1125 Decorating follow-up requests
1127 Mojo::UserAgent can automatically follow redirects, the event "start"
1128 in Mojo::UserAgent allows you direct access to each transaction right
1129 after they have been initialized and before a connection gets
1130 associated with them.
1131 use Mojo::UserAgent;
1133 # User agent following up to 10 redirects
1135 my $ua = Mojo::UserAgent->new(max_redirects => 10);
1136 # Add a witty header to every request
1138 $ua->on(start => sub {
1139 my ($ua, $tx) = @_;
1140 $tx->req->headers->header('X-Bender' => 'Bite my shiny metal ass!');
1141 say 'Request: ', $tx->req->url->clone->to_abs;
1142 });
1143 # Request that will most likely get redirected
1145 say 'Title: ', $ua->get('google.com')->result->dom->at('head > title')->text;
1146 This even works for proxy "CONNECT" requests.
1148 Content generators
1150 Content generators can be registered with "add_generator" in
1151 Mojo::UserAgent::Transactor to generate the same type of content
1152 repeatedly for multiple requests.
1153 use Mojo::UserAgent;
1155 use Mojo::Asset::File;
1156 # Add "stream" generator
1158 my $ua = Mojo::UserAgent->new;
1159 $ua->transactor->add_generator(stream => sub {
1160 my ($transactor, $tx, $path) = @_;
1161 $tx->req->content->asset(Mojo::Asset::File->new(path => $path));
1162 });
1163 # Send multiple files streaming via PUT and POST
1165 $ua->put('http://example.com/upload' => stream => '/home/sri/mojo.png');
1166 $ua->post('http://example.com/upload' => stream => '/home/sri/minion.png');
1167 The "json", "form" and "multipart" content generators are always
1169 available.
1170 use Mojo::UserAgent;
1172 # Send "application/json" content via PATCH
1174 my $ua = Mojo::UserAgent->new;
1175 my $tx = $ua->patch('http://api.example.com' => json => {foo => 'bar'});
1176 # Send query parameters via GET
1178 my $tx2 = $ua->get('search.example.com' => form => {q => 'test'});
1179 # Send "application/x-www-form-urlencoded" content via POST
1181 my $tx3 = $ua->post('http://search.example.com' => form => {q => 'test'});
1182 # Send "multipart/form-data" content via PUT
1184 my $tx4 = $ua->put(
1185 'upload.example.com' => form => {test => {content => 'Hello World!'}});
1186 # Send custom multipart content via PUT
1188 my $tx5 = $ua->put('api.example.com' => multipart => ['Hello', 'World!']);
1189 For more information about available content generators see also "tx"
1191 in Mojo::UserAgent::Transactor.
1192 Large file downloads
1194 When downloading large files with Mojo::UserAgent you don't have to
1195 worry about memory usage at all, because it will automatically stream
1196 everything above 250KiB into a temporary file, which can then be moved
1197 into a permanent file with "save_to" in Mojo::Message.
1198 use Mojo::UserAgent;
1200 # Fetch the latest Mojolicious tarball
1202 my $ua = Mojo::UserAgent->new(max_redirects => 5);
1203 my $tx = $ua->get('https://www.github.com/mojolicious/mojo/tarball/master');
1204 $tx->result->save_to('mojo.tar.gz');
1205 To protect you from excessively large files there is also a limit of
1207 2GiB by default, which you can tweak with the attribute
1208 "max_response_size" in Mojo::UserAgent.
1209 # Increase limit to 10GiB
1211 $ua->max_response_size(10737418240);
1212 Large file upload
1214 Uploading a large file is even easier.
1215 use Mojo::UserAgent;
1217 # Upload file via POST and "multipart/form-data"
1219 my $ua = Mojo::UserAgent->new;
1220 $ua->post('example.com/upload' =>
1221 form => {image => {file => '/home/sri/hello.png'}});
1222 And once again you don't have to worry about memory usage, all data
1224 will be streamed directly from the file.
1225 Streaming response
1227 Receiving a streaming response can be really tricky in most HTTP
1228 clients, but Mojo::UserAgent makes it actually easy.
1229 use Mojo::UserAgent;
1231 # Accept responses of indefinite size
1233 my $ua = Mojo::UserAgent->new(max_response_size => 0);
1234 # Build a normal transaction
1236 my $tx = $ua->build_tx(GET => 'http://example.com');
1237 # Replace "read" events to disable default content parser
1239 $tx->res->content->unsubscribe('read')->on(read => sub {
1240 my ($content, $bytes) = @_;
1241 say "Streaming: $bytes";
1242 });
1243 # Process transaction
1245 $tx = $ua->start($tx);
1246 The event "read" in Mojo::Content will be emitted for every chunk of
1248 data that is received, even chunked transfer encoding and gzip content
1249 encoding will be handled transparently if necessary.
1250 Streaming request
1252 Sending a streaming request is almost just as easy.
1253 use Mojo::UserAgent;
1255 # Build a normal transaction
1257 my $ua = Mojo::UserAgent->new;
1258 my $tx = $ua->build_tx(GET => 'http://example.com');
1259 # Prepare body
1261 my $body = 'Hello World!';
1262 $tx->req->headers->content_length(length $body);
1263 # Start writing directly with a drain callback
1265 my $drain;
1266 $drain = sub {
1267 my $content = shift;
1268 my $chunk = substr $body, 0, 1, '';
1269 $drain = undef unless length $body;
1270 $content->write($chunk, $drain);
1271 };
1272 $tx->req->content->$drain;
1273 # Process transaction
1275 $tx = $ua->start($tx);
1276 The drain callback passed to "write" in Mojo::Content will be executed
1278 whenever the entire previous chunk of data has actually been written.
1279 Non-blocking
1281 Mojo::UserAgent has been designed from the ground up to be non-
1282 blocking, the whole blocking API is just a simple convenience wrapper.
1283 Especially for high latency tasks like web crawling this can be
1284 extremely useful, because you can keep many concurrent connections
1285 active at the same time.
1286 use Mojo::UserAgent;
1288 use Mojo::IOLoop;
1289 # Concurrent non-blocking requests
1291 my $ua = Mojo::UserAgent->new;
1292 $ua->get('https://metacpan.org/search?q=mojo' => sub {
1293 my ($ua, $mojo) = @_;
1294 say $mojo->result->dom->at('title')->text;
1295 });
1296 $ua->get('https://metacpan.org/search?q=minion' => sub {
1297 my ($ua, $minion) = @_;
1298 say $minion->result->dom->at('title')->text;
1299 });
1300 # Start event loop if necessary
1302 Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
1303 But don't try to open too many connections to one server at the same
1305 time, it might get overwhelmed. Better use a queue to process requests
1306 in smaller batches.
1307 use Mojo::UserAgent;
1309 use Mojo::IOLoop;
1310 my @urls = (
1312 'mojolicious.org/perldoc/Mojo/DOM', 'mojolicious.org/perldoc/Mojo',
1313 'mojolicious.org/perldoc/Mojo/File', 'mojolicious.org/perldoc/Mojo/URL'
1314 );
1315 # User agent with a custom name, following up to 5 redirects
1317 my $ua = Mojo::UserAgent->new(max_redirects => 5);
1318 $ua->transactor->name('MyParallelCrawler 1.0');
1319 # Use a delay to keep the event loop running until we are done
1321 my $delay = Mojo::IOLoop->delay;
1322 my $fetch;
1323 $fetch = sub {
1324 # Stop if there are no more URLs
1326 return unless my $url = shift @urls;
1327 # Fetch the next title
1329 my $end = $delay->begin;
1330 $ua->get($url => sub {
1331 my ($ua, $tx) = @_;
1332 say "$url: ", $tx->result->dom->at('title')->text;
1333 # Next request
1335 $fetch->();
1336 $end->();
1337 });
1338 };
1339 # Process two requests at a time
1341 $fetch->() for 1 .. 2;
1342 $delay->wait;
1343 It is also strongly recommended to respect every sites "robots.txt"
1345 file as well as terms of service, and to wait a little before reopening
1346 connections to the same host, or the operators might be forced to block
1347 your access.
1348 Concurrent blocking requests
1350 You might have seen "wait" in Mojo::Promise already in some examples
1351 above. It is used to make non-blocking operations portable, allowing
1352 them to work inside an already running event loop or start one on
1353 demand.
1354 use Mojo::UserAgent;
1356 use Mojo::Promise;
1357 # Synchronize non-blocking requests with promises
1359 my $ua = Mojo::UserAgent->new;
1360 my $mojo = $ua->get_p('https://metacpan.org/search?q=mojo');
1361 my $minion = $ua->get_p('https://metacpan.org/search?q=minion');
1362 Mojo::Promise->all($mojo, $minion)->then(sub {
1363 my ($mojo, $minion) = @_;
1364 say $mojo->[0]->result->dom->at('title')->text;
1365 say $minion->[0]->result->dom->at('title')->text;
1366 })->wait;
1367 WebSockets
1369 WebSockets are not just for the server-side, you can use "websocket_p"
1370 in Mojo::UserAgent to open new connections, which are always non-
1371 blocking. The WebSocket handshake uses HTTP, and is a normal "GET"
1372 request with a few additional headers. It can even contain cookies, and
1373 is followed by a 101 response from the server, notifying our user agent
1374 that the connection has been established and it can start using the bi-
1375 directional WebSocket protocol.
1376 use Mojo::UserAgent;
1378 use Mojo::Promise;
1379 # Open WebSocket to echo service
1381 my $ua = Mojo::UserAgent->new;
1382 $ua->websocket_p('ws://echo.websocket.org')->then(sub {
1383 my $tx = shift;
1384 # Prepare a followup promise so we can wait for messages
1386 my $promise = Mojo::Promise->new;
1387 # Wait for WebSocket to be closed
1389 $tx->on(finish => sub {
1390 my ($tx, $code, $reason) = @_;
1391 say "WebSocket closed with status $code.";
1392 $promise->resolve;
1393 });
1394 # Close WebSocket after receiving one message
1396 $tx->on(message => sub {
1397 my ($tx, $msg) = @_;
1398 say "WebSocket message: $msg";
1399 $tx->finish;
1400 });
1401 # Send a message to the server
1403 $tx->send('Hi!');
1404 # Insert a new promise into the promise chain
1406 return $promise;
1407 })->catch(sub {
1408 my $err = shift;
1409 # Handle failed WebSocket handshakes and other exceptions
1411 warn "WebSocket error: $err";
1412 })->wait;
1413 UNIX domain sockets
1415 Not just TCP/IP sockets are supported, but also UNIX domain sockets,
1416 which can have significant security and performance benefits when used
1417 for inter-process communication. Instead of "http://" and "ws://" you
1418 can use the "http+unix://" and "ws+unix://" schemes, and pass along a
1419 percent encoded path ("/" becomes %2F) instead of a hostname.
1420 use Mojo::UserAgent;
1422 use Mojo::Promise;
1423 # GET request via UNIX domain socket "/tmp/foo.sock"
1425 my $ua = Mojo::UserAgent->new;
1426 say $ua->get('http+unix://%2Ftmp%2Ffoo.sock/index.html')->result->body;
1427 # GET request with HOST header via UNIX domain socket "/tmp/bar.sock"
1429 my $tx = $ua->get('http+unix://%2Ftmp%2Fbar.sock' => {Host => 'example.com'});
1430 say $tx->result->body;
1431 # WebSocket connection via UNIX domain socket "/tmp/baz.sock"
1433 $ua->websocket_p('ws+unix://%2Ftmp%2Fbaz.sock/echo')->then(sub {
1434 my $tx = shift;
1435 my $promise = Mojo::Promise->new;
1437 $tx->on(finish => sub { $promise->resolve });
1438 $tx->on(message => sub {
1440 my ($tx, $msg) = @_;
1441 say "WebSocket message: $msg";
1442 $tx->finish;
1443 });
1444 $tx->send('Hi!');
1445 return $promise;
1447 })->catch(sub {
1448 my $err = shift;
1449 warn "WebSocket error: $err";
1450 })->wait;
1451 You can set the "Host" header manually to pass along a hostname.
1453 Command line
1455 Don't you hate checking huge HTML files from the command line? Thanks
1456 to the command Mojolicious::Command::get that is about to change. You
1457 can just pick the parts that actually matter with the CSS selectors
1458 from Mojo::DOM and JSON Pointers from Mojo::JSON::Pointer.
1459 $ mojo get https://mojolicious.org 'head > title'
1461 How about a list of all id attributes?
1463 $ mojo get https://mojolicious.org '*' attr id
1465 Or the text content of all heading tags?
1467 $ mojo get https://mojolicious.org 'h1, h2, h3' text
1469 Maybe just the text of the third heading?
1471 $ mojo get https://mojolicious.org 'h1, h2, h3' 3 text
1473 You can also extract all text from nested child elements.
1475 $ mojo get https://mojolicious.org '#mojobar' all
1477 The request can be customized as well.
1479 $ mojo get -M POST -H 'X-Bender: Bite my shiny metal ass!' http://google.com
1481 Store response data by redirecting "STDOUT".
1483 $ mojo get mojolicious.org > example.html
1485 Pass request data by redirecting "STDIN".
1487 $ mojo get -M PUT mojolicious.org < example.html
1489 Or use the output of another program.
1491 $ echo 'Hello World' | mojo get -M PUT https://mojolicious.org
1493 Submit forms as "application/x-www-form-urlencoded" content.
1495 $ mojo get -M POST -f 'q=Mojo' -f 'size=5' https://metacpan.org/search
1497 And upload files as "multipart/form-data" content.
1499 $ mojo get -M POST -f 'upload=@example.html' mojolicious.org
1501 You can follow redirects and view the headers for all messages.
1503 $ mojo get -r -v http://google.com 'head > title'
1505 Extract just the information you really need from JSON data structures.
1507 $ mojo get https://fastapi.metacpan.org/v1/author/SRI /name
1509 This can be an invaluable tool for testing your applications.
1511 $ ./myapp.pl get /welcome 'head > title'
1513 One-liners
1515 For quick hacks and especially testing, ojo one-liners are also a great
1516 choice.
1517 $ perl -Mojo -E 'say g("mojolicious.org")->dom->at("title")->text'
1519
1521 Fun Mojolicious application hacks for all occasions.
1522 Basic authentication
1524 Basic authentication data will be automatically extracted from the
1525 "Authorization" header.
1526 use Mojolicious::Lite;
1528 use Mojo::Util 'secure_compare';
1529 get '/' => sub {
1531 my $c = shift;
1532 # Check for username "Bender" and password "rocks"
1534 return $c->render(text => 'Hello Bender!')
1535 if secure_compare $c->req->url->to_abs->userinfo, 'Bender:rocks';
1536 # Require authentication
1538 $c->res->headers->www_authenticate('Basic');
1539 $c->render(text => 'Authentication required!', status => 401);
1540 };
1541 app->start;
1543 This can be combined with TLS for a secure authentication mechanism.
1545 $ ./myapp.pl daemon -l 'https://*:3000?cert=./server.crt&key=./server.key'
1547 Adding a configuration file
1549 Adding a configuration file to your application is as easy as adding a
1550 file to its home directory and loading the plugin
1551 Mojolicious::Plugin::Config. The default name is based on the value of
1552 "moniker" in Mojolicious ("myapp"), appended with a ".conf" extension
1553 ("myapp.conf").
1554 $ mkdir myapp
1556 $ cd myapp
1557 $ touch myapp.pl
1558 $ chmod 744 myapp.pl
1559 $ echo '{name => "my Mojolicious application"};' > myapp.conf
1560 Configuration files themselves are just Perl scripts that return a hash
1562 reference with configuration settings of your choice. All those
1563 settings are then available through the method "config" in Mojolicious
1564 and the helper "config" in Mojolicious::Plugin::DefaultHelpers.
1565 use Mojolicious::Lite;
1567 plugin 'Config';
1569 my $name = app->config('name');
1571 app->log->debug("Welcome to $name");
1572 get '/' => 'with_config';
1574 app->start;
1576 __DATA__
1577 @@ with_config.html.ep
1578 <!DOCTYPE html>
1579 <html>
1580 <head><title><%= config 'name' %></title></head>
1581 <body>Welcome to <%= config 'name' %></body>
1582 </html>
1583 Alternatively you can also use configuration files in the JSON format
1585 with Mojolicious::Plugin::JSONConfig.
1586 Adding a plugin to your application
1588 To organize your code better and to prevent helpers from cluttering
1589 your application, you can use application specific plugins.
1590 $ mkdir -p lib/MyApp/Plugin
1592 $ touch lib/MyApp/Plugin/MyHelpers.pm
1593 They work just like normal plugins and are also subclasses of
1595 Mojolicious::Plugin. Nested helpers with a prefix based on the plugin
1596 name are an easy way to avoid conflicts.
1597 package MyApp::Plugin::MyHelpers;
1599 use Mojo::Base 'Mojolicious::Plugin';
1600 sub register {
1602 my ($self, $app) = @_;
1603 $app->helper('my_helpers.render_with_header' => sub {
1604 my ($c, @args) = @_;
1605 $c->res->headers->header('X-Mojo' => 'I <3 Mojolicious!');
1606 $c->render(@args);
1607 });
1608 }
1609 1;
1611 You can have as many application specific plugins as you like, the only
1613 difference to normal plugins is that you load them using their full
1614 class name.
1615 use Mojolicious::Lite;
1617 use lib 'lib';
1619 plugin 'MyApp::Plugin::MyHelpers';
1621 get '/' => sub {
1623 my $c = shift;
1624 $c->my_helpers->render_with_header(text => 'I ♥ Mojolicious!');
1625 };
1626 app->start;
1628 Of course these plugins can contain more than just helpers, take a look
1630 at "PLUGINS" in Mojolicious::Plugins for a few ideas.
1631 Adding commands to Mojolicious
1633 By now you've probably used many of the built-in commands described in
1634 Mojolicious::Commands, but did you know that you can just add new ones
1635 and that they will be picked up automatically by the command line
1636 interface if they are placed in a directory from @INC?
1637 package Mojolicious::Command::spy;
1639 use Mojo::Base 'Mojolicious::Command';
1640 has description => 'Spy on application';
1642 has usage => "Usage: APPLICATION spy [TARGET]\n";
1643 sub run {
1645 my ($self, @args) = @_;
1646 # Leak secret passphrases
1648 if ($args[0] eq 'secrets') { say for @{$self->app->secrets} }
1649 # Leak mode
1651 elsif ($args[0] eq 'mode') { say $self->app->mode }
1652 }
1653 1;
1655 Command line arguments are passed right through and there are many
1657 useful attributes and methods in Mojolicious::Command that you can use
1658 or overload.
1659 $ mojo spy secrets
1661 HelloWorld
1662 $ ./script/myapp spy secrets
1664 secr3t
1665 And to make your commands application specific, just add a custom
1667 namespace to "namespaces" in Mojolicious::Commands and use a class name
1668 like "MyApp::Command::spy" instead of "Mojolicious::Command::spy".
1669 # Application
1671 package MyApp;
1672 use Mojo::Base 'Mojolicious';
1673 sub startup {
1675 my $self = shift;
1676 # Add another namespace to load commands from
1678 push @{$self->commands->namespaces}, 'MyApp::Command';
1679 }
1680 1;
1682 The options "-h"/"--help", "--home" and "-m"/"--mode" are handled
1684 automatically by Mojolicious::Commands and are shared by all commands.
1685 $ ./script/myapp spy -m production mode
1687 production
1688 For a full list of shared options see "SYNOPSIS" in
1690 Mojolicious::Commands.
1691 Running code against your application
1693 Ever thought about running a quick one-liner against your Mojolicious
1694 application to test something? Thanks to the command
1695 Mojolicious::Command::eval you can do just that, the application object
1696 itself can be accessed via "app".
1697 $ mojo generate lite_app myapp.pl
1699 $ ./myapp.pl eval 'say for @{app->static->paths}'
1700 $ ./myapp.pl eval 'say for sort keys %{app->renderer->helpers}'
1701 The "verbose" options will automatically print the return value or
1703 returned data structure to "STDOUT".
1704 $ ./myapp.pl eval -v 'app->static->paths->[0]'
1706 $ ./myapp.pl eval -V 'app->static->paths'
1707 Making your application installable
1709 Ever thought about releasing your Mojolicious application to CPAN? It's
1710 actually much easier than you might think.
1711 $ mojo generate app MyApp
1713 $ cd my_app
1714 $ mv public lib/MyApp/
1715 $ mv templates lib/MyApp/
1716 The trick is to move the "public" and "templates" directories so they
1718 can get automatically installed with the modules. Additionally author
1719 commands from the "Mojolicious::Command::Author" namespace are not
1720 usually wanted by an installed application so they can be excluded.
1721 # Application
1723 package MyApp;
1724 use Mojo::Base 'Mojolicious';
1725 use Mojo::File 'path';
1727 use Mojo::Home;
1728 # Every CPAN module needs a version
1730 our $VERSION = '1.0';
1731 sub startup {
1733 my $self = shift;
1734 # Switch to installable home directory
1736 $self->home(Mojo::Home->new(path(__FILE__)->sibling('MyApp')));
1737 # Switch to installable "public" directory
1739 $self->static->paths->[0] = $self->home->child('public');
1740 # Switch to installable "templates" directory
1742 $self->renderer->paths->[0] = $self->home->child('templates');
1743 # Exclude author commands
1745 $self->commands->namespaces(['Mojolicious::Commands']);
1746 my $r = $self->routes;
1748 $r->get('/welcome')->to('example#welcome');
1749 }
1750 1;
1752 Finally there is just one small change to be made to the application
1754 script. The shebang line becomes the recommended "#!perl", which the
1755 toolchain can rewrite to the proper shebang during installation.
1756 #!perl
1758 use strict;
1760 use warnings;
1761 use FindBin;
1763 BEGIN { unshift @INC, "$FindBin::Bin/../lib" }
1764 use Mojolicious::Commands;
1765 # Start command line interface for application
1767 Mojolicious::Commands->start_app('MyApp');
1768 That's really everything, now you can package your application like any
1770 other CPAN module.
1771 $ ./script/my_app generate makefile
1773 $ perl Makefile.PL
1774 $ make test
1775 $ make manifest
1776 $ make dist
1777 And if you have a PAUSE account (which can be requested at
1779 <http://pause.perl.org>) even upload it.
1780 $ mojo cpanify -u USER -p PASS MyApp-0.01.tar.gz
1782 Hello World
1784 If every byte matters this is the smallest "Hello World" application
1785 you can write with Mojolicious::Lite.
1786 use Mojolicious::Lite;
1788 any {text => 'Hello World!'};
1789 app->start;
1790 It works because all routes without a pattern default to "/" and
1792 automatic rendering kicks in even if no actual code gets executed by
1793 the router. The renderer just picks up the "text" value from the stash
1794 and generates a response.
1795 Hello World one-liners
1797 The "Hello World" example above can get even a little bit shorter in an
1798 ojo one-liner.
1799 $ perl -Mojo -E 'a({text => "Hello World!"})->start' daemon
1801 And you can use all the commands from Mojolicious::Commands.
1803 $ perl -Mojo -E 'a({text => "Hello World!"})->start' get -v /
1805
1807 You can continue with Mojolicious::Guides now or take a look at the
1808 Mojolicious wiki <http://github.com/mojolicious/mojo/wiki>, which
1809 contains a lot more documentation and examples by many different
1810 authors.
1811
1813 If you have any questions the documentation might not yet answer, don't
1814 hesitate to ask on the mailing list
1815 <http://groups.google.com/group/mojolicious> or the official IRC
1816 channel "#mojo" on "irc.freenode.net" (chat now!
1817 <https://kiwiirc.com/nextclient/#irc://irc.freenode.net/mojo?nick=guest-?>).
1818perl v5.28.0 2018-11-01 Mojolicious::Guides::Cookbook(3)