/usr/share/perl5/Mojolicious/Guides/Growing.pod

=head1 NAME

Mojolicious::Guides::Growing - Growing

=head1 OVERVIEW

This document explains the process of starting a L<Mojolicious::Lite>
prototype from scratch and growing it into a well structured L<Mojolicious>
application.

=head1 CONCEPTS

Essentials every L<Mojolicious> developer should know.

=head2 Model View Controller

MVC is a software architectural pattern for graphical user interface
programming originating in Smalltalk-80, that separates application logic,
presentation and input.

           .------------.    .-------.    .------.
  Input -> | Controller | -> | Model | -> | View | -> Output
           '------------'    '-------'    '------'

A slightly modified version of the pattern moving some application logic into
the C<controller> is the foundation of pretty much every web framework these
days, including L<Mojolicious>.

              .----------------.     .-------.
  Request  -> |                | <-> | Model |
              |                |     '-------'
              |   Controller   |
              |                |     .-------.
  Response <- |                | <-> | View  |
              '----------------'     '-------'

The C<controller> receives a request from a user, passes incoming data to the
C<model> and retrieves data from it, which then gets turned into an actual
response by the C<view>.
But note that this pattern is just a guideline that most of the time results
in cleaner more maintainable code, not a rule that should be followed at all
costs.

=head2 REpresentational State Transfer

REST is a software architectural style for distributed hypermedia systems
such as the web.
While it can be applied to many protocols it is most commonly used with
C<HTTP> these days.
In REST terms, when you are opening a URL like C<http://mojolicio.us/foo>
with your browser, you are basically asking the web server for the HTML
C<representation> of the C<http://mojolicio.us/foo> C<resource>.

  .--------.                                .--------.
  |        | -> http://mojolicio.us/foo  -> |        |
  | Client |                                | Server |
  |        | <- <html>Mojo rocks!</html> <- |        |
  '--------'                                '--------'

The fundamental idea here is that all resources are uniquely addressable with
URLs and every resource can have different representations such as HTML, RSS
or JSON.
User interface concerns are separated from data storage concerns and all
session state is kept client-side.

  .---------.                        .------------.
  |         | ->    PUT /foo      -> |            |
  |         | ->    Hello world!  -> |            |
  |         |                        |            |
  |         | <-    201 CREATED   <- |            |
  |         |                        |            |
  |         | ->    GET /foo      -> |            |
  | Browser |                        | Web Server |
  |         | <-    200 OK        <- |            |
  |         | <-    Hello world!  <- |            |
  |         |                        |            |
  |         | ->    DELETE /foo   -> |            |
  |         |                        |            |
  |         | <-    200 OK        <- |            |
  '---------'                        '------------'

While HTTP methods such as C<PUT>, C<GET> and C<DELETE> are not directly part
of REST they go very well with it and are commonly used to manipulate
C<resources>.

=head2 Sessions

HTTP was designed as a stateless protocol, web servers don't know anything
about previous requests, which makes user friendly login systems very tricky.
Sessions solve this problem by allowing web applications to keep stateful
information across several HTTP requests.

  GET /login?user=sri&pass=s3cret HTTP/1.1
  Host: mojolicio.us

  HTTP/1.1 200 OK
  Set-Cookie: sessionid=987654321
  Content-Length: 10
  Hello sri.

  GET /protected HTTP/1.1
  Host: mojolicio.us
  Cookie: $Version=1; sessionid=987654321

  HTTP/1.1 200 OK
  Set-Cookie: sessionid=987654321
  Content-Length: 16
  Hello again sri.

Traditionally all session data was stored on the server-side and only session
ids were exchanged between browser and web server in the form of cookies.

  HTTP/1.1 200 OK
  Set-Cookie: session=base64(hmac-md5(json($session)))

In L<Mojolicious> however we are taking this concept one step further by
storing everything in C<HMAC-MD5> signed cookies, which is more compatible
with the REST philosophy and reduces infrastructure requirements.

=head2 Test Driven Development

TDD is a software development process where the developer starts writing
failing test cases that define the desired functionality and then moves on to
producing code that passes these tests.
There are many advantages such as always having good test coverage and code
being designed for testability, which will in turn often prevent future
changes from breaking old code.
Most of L<Mojolicious> was developed using TDD.

=head1 PROTOTYPE

One of the main differences between L<Mojolicious> and other web frameworks
is that it also includes L<Mojolicious::Lite>, a micro web framework
optimized for rapid prototyping.

=head2 Differences

You likely know the feeling, you've got a really cool idea and want to try it
as quickly as possible, that's exactly why L<Mojolicious::Lite> applications
don't need more than a single file.

  myapp.pl   # Templates and even static files can be inlined

Full L<Mojolicious> applications on the other hand are much closer to a well
organized CPAN distribution to maximize maintainability.

  myapp                      # Application directory
  |- script                  # Script directory
  |  `- myapp                # Application script
  |- lib                     # Library directory
  |  |- MyApp.pm             # Application class
  |  `- MyApp                # Application namespace
  |     `- Example.pm        # Controller class
  |- t                       # Test directory
  |  `- basic.t              # Random test
  |- log                     # Log directory
  |  `- development.log      # Development mode log file
  |- public                  # Static file directory (served automatically)
  |  `- index.html           # Static HTML file
  `- templates               # Template directory
     |- layouts              # Template directory for layouts
     |  `- default.html.ep   # Layout template
     `- example              # Template directory for "Example" controller
        `- welcome.html.ep   # Template for "welcome" action

Both application skeletons can be automatically generated.

  $ mojo generate lite_app
  $ mojo generate app

=head2 Foundation

We start our new application with a single executable Perl script.

  $ mkdir myapp
  $ cd myapp
  $ touch myapp.pl
  $ chmod 744 myapp.pl

This will be the foundation for our login manager example application.

  #!/usr/bin/env perl
  use Mojolicious::Lite;

  get '/' => sub {
    my $self = shift;
    $self->render(text => 'Hello world!');
  };

  app->start;

The built-in development web server makes working on your application a lot
of fun thanks to automatic reloading.

  $ morbo myapp.pl
  Server available at http://127.0.0.1:3000.

Just save your changes and they will be automatically in effect the next time
you refresh your browser.

=head2 Model

In L<Mojolicious> we consider web applications simple frontends for existing
business logic, that means L<Mojolicious> is by design entirely L<model>
layer agnostic and you just use whatever Perl modules you like most.

  $ mkdir lib
  $ touch lib/MyUsers.pm
  $ chmod 644 lib/MyUsers.pm

Our login manager will simply use a plain old Perl module abstracting away
all logic related to matching usernames and passwords.

  package MyUsers;

  use strict;
  use warnings;

  my $USERS = {
    sri    => 'secr3t',
    marcus => 'lulz',
    yko    => 'zeecaptain'
  };

  sub new { bless {}, shift }

  sub check {
    my ($self, $user, $pass) = @_;

    # Success
    return 1 if $USERS->{$user} && $USERS->{$user} eq $pass;

    # Fail
    return;
  }

  1;

A simple C<helper> function can be registered with the C<helper> method of
L<Mojolicious> to make our C<model> available to all actions and templates.

  #!/usr/bin/env perl
  use Mojolicious::Lite;

  use lib 'lib';
  use MyUsers;

  # Model instance
  my $users = MyUsers->new;

  # Helper function returning our model instance
  helper users => sub { return $users };

  # /?user=sri&pass=secr3t
  any '/' => sub {
    my $self = shift;

    # Query parameters
    my $user = $self->param('user') || '';
    my $pass = $self->param('pass') || '';

    # Check password
    return $self->render(text => "Welcome $user.")
      if $self->users->check($user, $pass);

    # Failed
    $self->render(text => 'Wrong username or password.');
  };

  app->start;

The C<param> method of our L<Mojolicious::Controller> instance is used to
access query parameters, POST parameters and route placeholders, all at once.

=head2 Testing

In L<Mojolicious> we take test driven development very serious and try to
promote it wherever we can.

  $ mkdir t
  $ touch t/login.t
  $ chmod 644 t/login.t

L<Test::Mojo> is a scriptable HTTP user agent designed specifically for
testing, with many fun state of the art features such as CSS3 selectors based
on L<Mojo::DOM>.

  use Test::More tests => 16;
  use Test::Mojo;

  # Include application
  use FindBin;
  require "$FindBin::Bin/../myapp.pl";

  # Allow 302 redirect responses
  my $t = Test::Mojo->new->max_redirects(1);

  # Test if the HTML login form exists
  $t->get_ok('/')->status_is(200)
    ->element_exists('form input[name="user"]')
    ->element_exists('form input[name="pass"]')
    ->element_exists('form input[type="submit"]');

  # Test login with valid credentials
  $t->post_form_ok('/' => {user => 'sri', pass => 'secr3t'})
    ->status_is(200)->text_like('html body' => qr/Welcome sri/);

  # Test accessing a protected page
  $t->get_ok('/protected')->status_is(200)->text_like('a' => qr/Logout/);

  # Test if HTML login form shows up again after logout
  $t->get_ok('/logout')->status_is(200)
    ->element_exists('form input[name="user"]')
    ->element_exists('form input[name="pass"]')
    ->element_exists('form input[type="submit"]');

From now on you can always check your progress by running these unit tests
against your application.

  $ ./myapp.pl test
  $ ./myapp.pl test t/login.t

To make the tests less noisy and limit log output to just C<error> messages
you can also add a line like this.

  $t->app->log->level('error');

Quick C<GET> requests can be performed right from the command line.

  $ ./myapp.pl get /
  Wrong username or password.

  $ ./myapp.pl get -v '/?user=sri&pass=secr3t'
  HTTP/1.1 200 OK
  Connection: Keep-Alive
  Date: Sun, 18 Jul 2010 13:09:58 GMT
  Server: Mojolicious (Perl)
  Content-Length: 12
  Content-Type: text/plain

  Welcome sri.

=head2 State keeping

Sessions in L<Mojolicious> pretty much just work out of the box and there is
no setup required, but we suggest using a more secure C<secret> passphrase.

  app->secret('Mojolicious rocks');

This passphrase is used by the C<HMAC-MD5> algorithm to make signed cookies
secure and can be changed at any time to invalidate all existing sessions.

  $self->session(user => 'sri');
  my $user = $self->session('user');

By default all sessions expire after one hour, for more control you can also
use the C<expires> session value to set the expiration date to a specific
time in epoch seconds.

  $self->session(expires => time + 3600);

And the whole session can be deleted by setting an expiration date in the
past.

  $self->session(expires => 1);

For data that should only be visible on the next request, like a confirmation
message after a 302 redirect, you can use the C<flash>.

  $self->flash(message => 'Everything is fine.');
  $self->redirect_to('goodbye');

Just remember that everything is stored in C<HMAC-MD5> signed cookies, so
there is usually a 4096 byte limit, depending on the browser.

=head2 Final prototype

A final C<myapp.pl> prototype passing all of the unit tests above could look
like this.

  #!/usr/bin/env perl
  use Mojolicious::Lite;

  use lib 'lib';
  use MyUsers;

  # Make signed cookies secure
  app->secret('Mojolicious rocks');

  my $users = MyUsers->new;
  helper users => sub { return $users };

  # Main login action
  any '/' => sub {
    my $self = shift;

    # Query or POST parameters
    my $user = $self->param('user') || '';
    my $pass = $self->param('pass') || '';

    # Check password and render "index.html.ep" if necessary
    return $self->render unless $self->users->check($user, $pass);

    # Store username in session
    $self->session(user => $user);

    # Store a friendly message for the next page in flash
    $self->flash(message => 'Thanks for logging in.');

    # Redirect to protected page with a 302 response
    $self->redirect_to('protected');
  } => 'index';

  # A protected page auto rendering "protected.html.ep"
  get '/protected' => sub {
    my $self = shift;

    # Redirect to main page with a 302 response if user is not logged in
    return $self->redirect_to('index') unless $self->session('user');
  };

  # Logout action
  get '/logout' => sub {
    my $self = shift;

    # Expire and in turn clear session automatically
    $self->session(expires => 1);

    # Redirect to main page with a 302 response
    $self->redirect_to('index');
  };

  app->start;
  __DATA__

  @@ index.html.ep
  % layout 'default';
  %= form_for index => begin
    % if (param 'user') {
      <b>Wrong name or password, please try again.</b><br>
    % }
    Name:<br>
    %= text_field 'user'
    <br>Password:<br>
    %= password_field 'pass'
    <br>
    %= submit_button 'Login'
  % end

  @@ protected.html.ep
  % layout 'default';
  % if (my $message = flash 'message') {
    <b><%= $message %></b><br>
  % }
  Welcome <%= session 'user' %>.<br>
  %= link_to Logout => 'logout'

  @@ layouts/default.html.ep
  <!doctype html><html>
    <head><title>Login Manager</title></head>
    <body><%= content %></body>
  </html>

A list of all built-in helpers can be found in
L<Mojolicious::Plugin::DefaultHelpers> and
L<Mojolicious::Plugin::TagHelpers>.

=head1 WELL STRUCTURED APPLICATION

Due to the flexibility of L<Mojolicious> there are many variations of the
actual growing process, but this should give you a good overview of the
possibilities.

=head2 Inflating templates

All templates and static files inlined in the C<DATA> section can be
automatically turned into separate files in the C<templates> and C<public>
directories.

  $ ./myapp.pl inflate

Those directories always get priority, so inflating can also be a great way
to allow your users to customize their applications.

=head2 Simplified application class

This is the heart of every full L<Mojolicious> application and always gets
instantiated during server startup.

  $ touch lib/MyApp.pm
  $ chmod 644 lib/MyApp.pm

We will start by extracting all actions from C<myapp.pl> and turn them into
simplified hybrid routes in the L<Mojolicious::Routes> router, none of the
actual action code needs to be changed.

  package MyApp;
  use Mojo::Base 'Mojolicious';

  use MyUsers;

  sub startup {
    my $self = shift;

    $self->secret('Mojolicious rocks');
    my $users = MyUsers->new;
    $self->helper(users => sub { return $users });

    # Router
    my $r = $self->routes;

    $r->any('/' => sub {
      my $self = shift;

      my $user = $self->param('user') || '';
      my $pass = $self->param('pass') || '';
      return $self->render unless $self->users->check($user, $pass);

      $self->session(user => $user);
      $self->flash(message => 'Thanks for logging in.');
      $self->redirect_to('protected');
    } => 'index');

    $r->get('/protected' => sub {
      my $self = shift;
      return $self->redirect_to('index') unless $self->session('user');
    });

    $r->get('/logout' => sub {
      my $self = shift;
      $self->session(expires => 1);
      $self->redirect_to('index');
    });
  }

  1;

The C<startup> method of L<Mojolicious> gets called right after instantiation
and is the place where the whole application gets set up.

=head2 Simplified application script

C<myapp.pl> itself can now be turned into a simplified application script to
allow running unit tests again.

  #!/usr/bin/env perl

  use strict;
  use warnings;

  use lib 'lib';
  use Mojolicious::Commands;

  # Application
  $ENV{MOJO_APP} = 'MyApp';

  # Start commands
  Mojolicious::Commands->start;

=head2 Controller class

Hybrid routes are a nice intermediate step, but to maximize maintainability
it makes sense to split our action code from its routing information.

  $ mkdir lib/MyApp
  $ touch lib/MyApp/Login.pm
  $ chmod 644 lib/MyApp/Login.pm

Once again the actual action code does not change at all.

  package MyApp::Login;
  use Mojo::Base 'Mojolicious::Controller';

  sub index {
    my $self = shift;

    my $user = $self->param('user') || '';
    my $pass = $self->param('pass') || '';
    return $self->render unless $self->users->check($user, $pass);

    $self->session(user => $user);
    $self->flash(message => 'Thanks for logging in.');
    $self->redirect_to('protected');
  }

  sub protected {
    my $self = shift;
    return $self->redirect_to('index') unless $self->session('user');
  }

  sub logout {
    my $self = shift;
    $self->session(expires => 1);
    $self->redirect_to('index');
  }

  1;

All L<Mojolicious::Controller> controllers are plain old Perl classes and get
instantiated on demand.

=head2 Application class

The application class C<lib/MyApp.pm> can now be reduced to model and routing
information.

  package MyApp;
  use Mojo::Base 'Mojolicious';

  use MyUsers;

  sub startup {
    my $self = shift;

    $self->secret('Mojolicious rocks');
    my $users = MyUsers->new;
    $self->helper(users => sub { return $users });

    my $r = $self->routes;
    $r->any('/')->to('login#index')->name('index');
    $r->get('/protected')->to('login#protected')->name('protected');
    $r->get('/logout')->to('login#logout')->name('logout');
  }

  1;

L<Mojolicious::Routes> allows many route variations, choose whatever you like
most.

=head2 Templates

Templates are usually bound to controllers, so they need to be moved into the
appropriate directories.

  $ mkdir templates/login
  $ mv templates/index.html.ep templates/login/index.html.ep
  $ mv templates/protected.html.ep templates/login/protected.html.ep

=head2 Script

Finally C<myapp.pl> can be replaced with a proper L<Mojolicious> script.

  $ rm myapp.pl
  $ mkdir script
  $ touch script/myapp
  $ chmod 744 script/myapp

The library detection code was specifically designed for tricky production
environments.

  #!/usr/bin/env perl

  use strict;
  use warnings;

  use File::Basename 'dirname';
  use File::Spec;

  use lib join '/', File::Spec->splitdir(dirname(__FILE__)), 'lib';
  use lib join '/', File::Spec->splitdir(dirname(__FILE__)), '..', 'lib';

  # Check if Mojolicious is installed
  die <<EOF unless eval 'use Mojolicious::Commands; 1';
  It looks like you don't have the Mojolicious framework installed.
  Please visit http://mojolicio.us for detailed installation instructions.

  EOF

  # Application
  $ENV{MOJO_APP} ||= 'MyApp';

  # Start commands
  Mojolicious::Commands->start;

=head2 Simplified tests

Normal L<Mojolicious> applications are a little easier to test and don't need
help with home directory detection, so C<t/login.t> can be simplified.

  use Test::More tests => 16;
  use Test::Mojo;

  # Load application class
  my $t = Test::Mojo->new('MyApp')->max_redirects(1);

  $t->get_ok('/')->status_is(200)
    ->element_exists('form input[name="user"]')
    ->element_exists('form input[name="pass"]')
    ->element_exists('form input[type="submit"]');

  $t->post_form_ok('/' => {user => 'sri', pass => 'secr3t'})
    ->status_is(200)->text_like('html body' => qr/Welcome sri/);

  $t->get_ok('/protected')->status_is(200)->text_like('a' => qr/Logout/);

  $t->get_ok('/logout')->status_is(200)
    ->element_exists('form input[name="user"]')
    ->element_exists('form input[name="pass"]')
    ->element_exists('form input[type="submit"]');

Test driven development takes a little getting used to, but is very well
worth it!

=head1 MORE

You can continue with L<Mojolicious::Guides> now or take a look at the
Mojolicious wiki L<http://github.com/kraih/mojo/wiki>, which contains a lot
more documentation and examples by many different authors.

=cut
libmojolicious-perl 2.23-1 / usr / share / perl5 / Mojolicious / Guides / Growing.pod
