=encoding utf8

=head1 NAME

Mojolicious::Guides - The Mojolicious Guide to the Galaxy

=head1 DON'T PANIC!

The L<Mojolicious|https://mojolicious.org> documentation is structured into three parts. The L</"TUTORIAL"> everyone
starts with, the L</"GUIDES"> that explain all major features in detail, and the L</"API"> reference listing all
available classes.

Some parts of the documentation only use the L<Mojolicious::Lite> micro web framework for examples, but that's merely a
convenience for the reader. Almost all features are exactly the same for full L<Mojolicious> applications.

=head1 BASICS

=head2 Learning Perl

If you are new to Perl, we recommend L<Learn Perl in 2 hours 30 minutes|https://qntm.org/perl_en> for a quick
introduction, or the L<Modern Perl book|https://pragprog.com/book/swperl/modern-perl-fourth-edition>, freely available
in many formats. Both are excellent introductions to the language. For more books and documentation, check out
L<learn.perl.org|https://learn.perl.org/>.

=head2 Learning Web Technologies

All web development starts with HTML, CSS and JavaScript, to learn the basics we recommend the L<Mozilla Developer
Network|https://developer.mozilla.org/en-US/docs/Web>. And if you want to know more about how browsers and web servers
actually communicate, there's also a very nice introduction to
L<HTTP|https://developer.mozilla.org/en-US/docs/Web/HTTP>.

=head1 CONVENTIONS

=head2 Modern Perl

L<Mojolicious> uses a modern subset of Perl exclusively, and therefore all documentation assumes that L<strict>,
L<warnings>, L<utf8> and Perl 5.16 L<features|feature> are enabled, even if examples don't specifically mention it.

  use strict;
  use warnings;
  use utf8;
  use feature ':5.16';

Some modules, like L<Mojo::Base> and L<Mojolicious::Lite>, will enable them for you automatically, whenever they are
used.

=head2 Signatures

On Perl 5.20+ you can also use the C<-signatures> flag with L<Mojo::Base> to enable support for
L<subroutine signatures|perlsub/"Signatures">. Signatures are used in all examples for clarity, even when C<-signatures>
is omitted for brevity.

=head2 Variable names

For brevity and clarity, example variables will reflect the type of data the API uses. For instance, C<$bytes> or
C<$chars> to distinguish whether it is encoded bytes or decoded characters in a Perl L<string|perlunifaq>, C<$bool> if
the value just indicates true or false, C<$c> to denote a L<Mojolicious::Controller> object, or C<$app> to denote the
L<application|Mojolicious> object.

=head1 TUTORIAL

=over 2

=item L<Mojolicious::Guides::Tutorial>

A fast and fun way to get started developing web applications with L<Mojolicious>. The tutorial introduces the
L<Mojolicious::Lite> micro web framework, which is only a thin wrapper around the full web framework. The simplified
notation introduced in the tutorial is commonly used throughout the guides and is therefore considered a prerequisite,
you should definitely take a look!

=back

=head1 GUIDES

=over 2

=item L<Mojolicious::Guides::Growing>

Starting a L<Mojolicious::Lite> prototype from scratch and growing it into a well-structured L<Mojolicious>
application.

=item L<Mojolicious::Guides::Routing>

Simple and fun introduction to the L<Mojolicious> router.

=item L<Mojolicious::Guides::Rendering>

Generating content with the L<Mojolicious> renderer.

=item L<Mojolicious::Guides::Testing>

Powerful yet elegant testing techniques and tools for L<Mojolicious> and other web applications.

=item L<Mojolicious::Guides::Cookbook>

Cooking with L<Mojolicious>, recipes for every taste.

=item L<Mojolicious::Guides::Contributing>

Become a part of the ongoing L<Mojolicious> development.

=item L<Mojolicious::Guides::FAQ>

Answers to the most frequently asked questions.

=back

=head1 HIGHLIGHTS

L<Mojolicious> and L<Mojolicious::Lite> are the sum of many parts, built on top of the L<Mojo> web development toolkit.
Small building blocks that can be used independently for all kinds of applications, these are the most prominent ones.

=over 2

=item L<Mojo::UserAgent>

Full featured non-blocking I/O HTTP and WebSocket user agent.

=item L<Mojo::DOM>

Very fun and minimalistic HTML/XML DOM parser with CSS selector support.

=item L<Mojo::JSON>

Minimalistic JSON implementation that just works.

=item L<Mojo::Server::Daemon>

Full featured, highly portable non-blocking I/O HTTP and WebSocket server, with self-restart support through
L<Mojo::Server::Morbo>, perfect for development and testing.

=item L<Mojo::Server::Prefork>

Full featured, UNIX optimized, preforking non-blocking I/O HTTP and WebSocket server with support for zero downtime
software upgrades (hot deployment) through L<Mojo::Server::Hypnotoad>.

=item L<Mojo::Server::CGI>, L<Mojo::Server::PSGI>

Transparent CGI and L<PSGI> support out of the box.

=item L<Mojo::IOLoop>

A minimalistic event loop with support for multiple reactor backends.

=item L<Mojo::Template>

Very Perl-ish and minimalistic template system.

=item L<Test::Mojo>

Testing toolkit for web applications.

=item L<ojo>

Fun one-liners using everything above.

=back

=head1 FULL-STACK

These modules are not part of the L<Mojolicious> distribution, but have been designed to be used with it and are being
developed under the same umbrella.

=over 2

=item L<Mojo::Pg>

A tiny wrapper around L<DBD::Pg> that makes L<PostgreSQL|https://www.postgresql.org> a lot of fun to use with
L<Mojolicious>. Perform queries blocking and non-blocking, use all L<SQL
features|https://www.postgresql.org/docs/current/static/sql.html> PostgreSQL has to offer, generate CRUD queries from
data structures, manage your database schema with migrations and build scalable real-time web applications with the
publish/subscribe pattern.

B<Examples:> The minimal L<chat|https://github.com/mojolicious/mojo-pg/tree/main/examples/chat.pl> application will
show you how to scale WebSockets to multiple servers, and the well-structured
L<blog|https://github.com/mojolicious/mojo-pg/tree/main/examples/blog>  application how to apply the MVC design pattern
in practice.

=item L<Minion>

A full featured job queue for L<Mojolicious> with support for multiple backends (such as
L<PostgreSQL|https://www.postgresql.org>). Job queues allow you to process time and/or computationally intensive tasks
in background processes, outside of the request/response lifecycle. Among those tasks you'll commonly find image
resizing, spam filtering, HTTP downloads, building tarballs, warming caches and basically everything else you can
imagine that's not super fast.

B<Examples:> The L<link checker|https://github.com/mojolicious/minion/tree/main/examples/linkcheck> will show you how to
integrate background jobs into well-structured L<Mojolicious> applications.

=back

=head1 API

This is the class hierarchy of the L<Mojolicious> distribution.

=over 2

=item * L<Mojo>

=item * L<Mojo::Base>

=over 2

=item * L<Mojolicious>

=over 2

=item * L<Mojo::HelloWorld>

=item * L<Mojolicious::Lite>

=back

=item * L<Mojo::Cache>

=item * L<Mojo::Cookie>

=over 2

=item * L<Mojo::Cookie::Request>

=item * L<Mojo::Cookie::Response>

=back

=item * L<Mojo::DOM::CSS>

=item * L<Mojo::DOM::HTML>

=item * L<Mojo::Date>

=item * L<Mojo::EventEmitter>

=over 2

=item * L<Mojo::Asset>

=over 2

=item * L<Mojo::Asset::File>

=item * L<Mojo::Asset::Memory>

=back

=item * L<Mojo::Content>

=over 2

=item * L<Mojo::Content::MultiPart>

=item * L<Mojo::Content::Single>

=back

=item * L<Mojo::IOLoop>

=item * L<Mojo::IOLoop::Client>

=item * L<Mojo::IOLoop::Server>

=item * L<Mojo::IOLoop::Stream>

=item * L<Mojo::IOLoop::Subprocess>

=item * L<Mojo::IOLoop::TLS>

=item * L<Mojo::Log>

=item * L<Mojo::Message>

=over 2

=item * L<Mojo::Message::Request>

=item * L<Mojo::Message::Response>

=back

=item * L<Mojo::Reactor>

=over 2

=item * L<Mojo::Reactor::Poll>

=over 2

=item * L<Mojo::Reactor::EV>

=back

=back

=item * L<Mojo::Server>

=over 2

=item * L<Mojo::Server::CGI>

=item * L<Mojo::Server::Daemon>

=over 2

=item * L<Mojo::Server::Prefork>

=back

=item * L<Mojo::Server::PSGI>

=back

=item * L<Mojo::Transaction>

=over 2

=item * L<Mojo::Transaction::HTTP>

=item * L<Mojo::Transaction::WebSocket>

=back

=item * L<Mojo::UserAgent>

=item * L<Mojolicious::Plugins>

=back

=item * L<Mojo::Exception>

=item * L<Mojo::Headers>

=item * L<Mojo::JSON::Pointer>

=item * L<Mojo::Parameters>

=item * L<Mojo::Path>

=item * L<Mojo::Promise>

=item * L<Mojo::Server::Hypnotoad>

=item * L<Mojo::Server::Morbo>

=item * L<Mojo::Server::Morbo::Backend>

=over 2

=item * L<Mojo::Server::Morbo::Backend::Poll>

=back

=item * L<Mojo::Template>

=item * L<Mojo::URL>

=item * L<Mojo::Upload>

=item * L<Mojo::UserAgent::CookieJar>

=item * L<Mojo::UserAgent::Proxy>

=item * L<Mojo::UserAgent::Server>

=item * L<Mojo::UserAgent::Transactor>

=item * L<Mojolicious::Command>

=over 2

=item * L<Mojolicious::Command::cgi>

=item * L<Mojolicious::Command::daemon>

=item * L<Mojolicious::Command::eval>

=item * L<Mojolicious::Command::get>

=item * L<Mojolicious::Command::prefork>

=item * L<Mojolicious::Command::psgi>

=item * L<Mojolicious::Command::routes>

=item * L<Mojolicious::Command::version>

=item * L<Mojolicious::Command::Author::cpanify>

=item * L<Mojolicious::Command::Author::generate::app>

=item * L<Mojolicious::Command::Author::generate::dockerfile>

=item * L<Mojolicious::Command::Author::generate::lite_app>

=item * L<Mojolicious::Command::Author::generate::makefile>

=item * L<Mojolicious::Command::Author::generate::plugin>

=item * L<Mojolicious::Command::Author::inflate>

=item * L<Mojolicious::Commands>

=over 2

=item * L<Mojolicious::Command::Author::generate>

=back

=back

=item * L<Mojolicious::Controller>

=item * L<Mojolicious::Plugin>

=over 2

=item * L<Mojolicious::Plugin::Config>

=over 2

=item * L<Mojolicious::Plugin::JSONConfig>

=over 2

=item * L<Mojolicious::Plugin::NotYAMLConfig>

=back

=back

=item * L<Mojolicious::Plugin::DefaultHelpers>

=item * L<Mojolicious::Plugin::EPLRenderer>

=over 2

=item * L<Mojolicious::Plugin::EPRenderer>

=back

=item * L<Mojolicious::Plugin::HeaderCondition>

=item * L<Mojolicious::Plugin::Mount>

=item * L<Mojolicious::Plugin::TagHelpers>

=back

=item * L<Mojolicious::Renderer>

=item * L<Mojolicious::Routes::Match>

=item * L<Mojolicious::Routes::Pattern>

=item * L<Mojolicious::Routes::Route>

=over 2

=item * L<Mojolicious::Routes>

=back

=item * L<Mojolicious::Sessions>

=item * L<Mojolicious::Static>

=item * L<Mojolicious::Types>

=item * L<Mojolicious::Validator>

=item * L<Mojolicious::Validator::Validation>

=item * L<Test::Mojo>

=back

=item * L<Mojo::ByteStream>

=item * L<Mojo::Collection>

=item * L<Mojo::DynamicMethods>

=item * L<Mojo::DOM>

=item * L<Mojo::File>

=over 2

=item * L<Mojo::Home>

=back

=item * L<Mojo::JSON>

=item * L<Mojo::Loader>

=item * L<Mojo::Util>

=item * L<Mojo::WebSocket>

=item * L<ojo>

=back

=head1 MORE

A lot more documentation and examples by many different authors can be found in the L<Mojolicious
wiki|https://github.com/mojolicious/mojo/wiki>.

=head1 SUPPORT

If you have any questions the documentation might not yet answer, don't hesitate to ask in the
L<Forum|https://forum.mojolicious.org>, on L<Matrix|https://matrix.to/#/#mojo:matrix.org>, or
L<IRC|https://web.libera.chat/#mojo>.


=cut