Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Mojolicious - Perl real-time web framework

tag: v1.33

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.pod

Back in the early days of the web there was this wonderful Perl library called CGI, many people only learned Perl because of it. It was simple enough to get started without knowing much about the language and powerful enough to keep you going, learning by doing was much fun. While most of the techniques used are outdated now, the idea behind it is not. Mojolicious is a new attempt at implementing this idea using state of the art technology.

  • An amazing MVC web framework supporting a simplified single file mode through Mojolicious::Lite.

    Powerful out of the box with RESTful routes, plugins, Perl-ish templates, session management, signed cookies, testing framework, static file server, I18N, first class unicode support and much more for you to discover.

  • Very clean, portable and Object Oriented pure Perl API without any hidden magic and no requirements besides Perl 5.8.7 (although 5.10+ is recommended).
  • Full stack HTTP 1.1 and WebSocket client/server implementation with IPv6, TLS, Bonjour, IDNA, Comet (long polling), chunking and multipart support.
  • Builtin async IO web server supporting epoll, kqueue, UNIX domain sockets and hot deployment, perfect for embedding.
  • Automatic CGI, FastCGI and PSGI detection.
  • JSON and XML/HTML5 parser with CSS3 selector support.
  • Fresh code based upon years of experience developing Catalyst.

All you need is a oneliner.

  sudo sh -c "curl -L cpanmin.us | perl - Mojolicious"

Web development for humans, making hard things possible and everything fun.

  use Mojolicious::Lite;

  # Simple route with plain text response
  get '/hello' => sub { shift->render_text('Hello World!') };

  # Route to template in DATA section
  get '/time' => 'clock';

  # RESTful web service sending JSON responses
  get '/:offset' => sub {
    my $self   = shift;
    my $offset = $self->param('offset') || 23;
    $self->render_json({list => [0 .. $offset]});
  };

  # Scrape information from remote sites
  post '/title' => sub {
    my $self = shift;
    my $url  = $self->param('url') || 'http://mojolicio.us';
    $self->render_text(
      $self->ua->get($url)->res->dom->at('head > title')->text);
  };

  # WebSocket echo service
  websocket '/echo' => sub {
    my $self = shift;
    $self->on_message(sub {
      my ($self, $message) = @_;
      $self->send_message("echo: $message");
    });
  };

  app->start;
  __DATA__

  @@ clock.html.ep
  % my ($second, $minute, $hour) = (localtime(time))[0, 1, 2];
  <%= link_to clock => begin %>
    The time is <%= $hour %>:<%= $minute %>:<%= $second %>.
  <% end %>

To run this example with the built in development server just put the code into a file and execute it with perl.

  % perl example.pl daemon
  Server available at http://127.0.0.1:3000.

Single file prototypes like the one above can easily grow into well structured applications.

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

  # Runs once on application startup
  sub startup {
    my $self = shift;
    my $r    = $self->routes;

    # Route prefix for "MyApp::Example" controller
    my $example = $r->route('/example')->to('example#');

    # GET routes connecting the controller prefix with actions
    $example->get('/hello')->to('#hello');
    $example->get('/time')->to('#clock');
    $example->get('/:offset')->to('#restful');

    # All common verbs are supported
    $example->post('/title')->to('#title');

    # And much more
    $r->websocket('/echo')->to('realtime#echo');
  }

  1;

Bigger applications are a lot easier to maintain once routing information has been separated from action code, especially when working in teams.

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

  # Plain text response
  sub hello { shift->render_text('Hello World!') }

  # Render external template "templates/example/clock.html.ep"
  sub clock { shift->render }

  # RESTful web service sending JSON responses
  sub restful {
    my $self   = shift;
    my $offset = $self->param('offset') || 23;
    $self->render_json({list => [0 .. $offset]});
  }

  # Scrape information from remote sites
  sub title {
    my $self = shift;
    my $url  = $self->param('url') || 'http://mojolicio.us';
    $self->render_text(
      $self->ua->get($url)->res->dom->at('head > title')->text);
  }

  1;

While the application class is unique, you can have as many controllers as you like.

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

  # WebSocket echo service
  sub echo {
    my $self = shift;
    $self->on_message(sub {
      my ($self, $message) = @_;
      $self->send_message("echo: $message");
    });
  }

  1;

Action code and templates can stay almost exactly the same, everything was designed from the ground up for this very unique and fun workflow.

  % my ($second, $minute, $hour) = (localtime(time))[0, 1, 2];
  <%= link_to clock => begin %>
    The time is <%= $hour %>:<%= $minute %>:<%= $second %>.
  <% end %>

Take a look at our excellent documentation at http://mojolicio.us/perldoc!

Something went wrong with that request. Please try again.