Mojo::Message(3p)

NAME
Mojo::Message - HTTP 1.1 message base class

SYNOPSIS
  use Mojo::Base 'Mojo::Message';

DESCRIPTION
Mojo::Message is an abstract base class for HTTP 1.1 messages as described in RFC 2616 and RFC 2388.

EVENTS
Mojo::Message can emit the following events.

  "finish"
  $message->on(finish => sub {
    my $message = shift;
    ...
  });

Emitted after message building or parsing is finished.

  my $before = time;
  $message->on(finish => sub {
    my $message = shift;
    $message->headers->header('X-Parser-Time' => time - $before);
  });

  "progress"
  $message->on(progress => sub {
    my $message = shift;
    ...
  });

Emitted when message building or parsing makes progress.

  # Building
  $message->on(progress => sub {
    my ($message, $state, $offset) = @_;
    say qq/Building "$state" at offset $offset/;
  });

  # Parsing
  $message->on(progress => sub {
    my $message = shift;
    return unless my $len = $message->headers->content_length;
    my $size = $message->content->progress;
    say 'Progress: ', $size == $len ? 100 : int($size / ($len / 100)), '%';
  });

ATTRIBUTES
Mojo::Message implements the following attributes.

  "content"
  my $message = $message->content;
  $message    = $message->content(Mojo::Content::Single->new);

Content container, defaults to a Mojo::Content::Single object.

  "default_charset"
  my $charset = $message->default_charset;
  $message    = $message->default_charset('UTF-8');

Default charset used for form data parsing, defaults to "UTF-8".

  "dom_class"
  my $class = $message->dom_class;
  $message  = $message->dom_class('Mojo::DOM');

Class to be used for DOM manipulation with the "dom" method, defaults to Mojo::DOM.

  "json_class"
  my $class = $message->json_class;
  $message  = $message->json_class('Mojo::JSON');

Class to be used for JSON deserialization with the "json" method, defaults to Mojo::JSON.

  "max_message_size"
  my $size = $message->max_message_size;
  $message = $message->max_message_size(1024);

Maximum message size in bytes, defaults to the value of the "MOJO_MAX_MESSAGE_SIZE" environment variable or 5242880. Note that increasing this value can also drastically increase memory usage, should you for example attempt to parse an excessively large message body with the "body_params", "dom" or "json" methods.

  "version"
  my $version = $message->version;
  $message    = $message->version('1.1');

HTTP version of message.

METHODS
Mojo::Message inherits all methods from Mojo::EventEmitter and implements the following new ones.

  "at_least_version"
  my $success = $message->at_least_version('1.1');

Check if message is at least a specific version.

  "body"
  my $string = $message->body;
  $message   = $message->body('Hello!');
  my $cb     = $message->body(sub {...});

Access "content" data or replace all subscribers of the "read" event.

  $message->body(sub {
    my ($message, $chunk) = @_;
    say "Streaming: $chunk";
  });

  "body_params"
  my $p = $message->body_params;

"POST" parameters extracted from "x-application-urlencoded", "application/x-www-form-urlencoded" or "multipart/form-data" message body, usually a Mojo::Parameters object.

  say $message->body_params->param('foo');

  "body_size"
  my $size = $message->body_size;

Alias for "body_size" in Mojo::Content.

  "build_body"
  my $string = $message->build_body;

Render whole body.

  "build_headers"
  my $string = $message->build_headers;

Render all headers.

  "build_start_line"
  my $string = $message->build_start_line;

Render start line.

  "cookie"
  my $cookie  = $message->cookie('foo');
  my @cookies = $message->cookie('foo');

Access message cookies, usually Mojo::Cookie::Request or Mojo::Cookie::Response objects.

  say $message->cookie('foo')->value;

  "dom"
  my $dom        = $message->dom;
  my $collection = $message->dom('a[href]');

Turns message body into a Mojo::DOM object and takes an optional selector to perform a "find" on it right away, which returns a collection.

  # Perform "find" right away
  $message->dom('h1, h2, h3')->each(sub { say $_->text });

  # Use everything else Mojo::DOM has to offer
  say $message->dom->at('title')->text;
  $message->dom->html->body->children->each(sub { say $_->type });

  "error"
  my $message          = $message->error;
  my ($message, $code) = $message->error;
  $message             = $message->error('Parser error.');
  $message             = $message->error('Parser error.', 500);

Parser errors and codes.

  "fix_headers"
  $message = $message->fix_headers;

Make sure message has all required headers for the current HTTP version.

  "get_body_chunk"
  my $string = $message->get_body_chunk($offset);

Get a chunk of body data starting from a specific position.

  "get_header_chunk"
  my $string = $message->get_header_chunk($offset);

Get a chunk of header data, starting from a specific position.

  "get_start_line_chunk"
  my $string = $message->get_start_line_chunk($offset);

Get a chunk of start line data starting from a specific position.

  "has_leftovers"
  my $success = $message->has_leftovers;

Alias for "has_leftovers" in Mojo::Content.

  "header_size"
  my $size = $message->header_size;

Size of headers in bytes.

  "headers"
  my $headers = $message->headers;

Alias for "headers" in Mojo::Content.

  say $message->headers->content_type;

  "is_chunked"
  my $success = $message->is_chunked;

Alias for "is_chunked" in Mojo::Content.

  "is_dynamic"
  my $success = $message->is_dynamic;

Alias for "is_dynamic" in Mojo::Content.

  "is_finished"
  my $success = $message->is_finished;

Check if parser is finished.

  "is_limit_exceeded"
  my $success = $message->is_limit_exceeded;

Check if message has exceeded "max_line_size" or "max_message_size".

  "is_multipart"
  my $success = $message->is_multipart;

Alias for "is_multipart" in Mojo::Content.

  "json"
  my $object = $message->json;
  my $array  = $message->json;
  my $value  = $message->json('/foo/bar');

Decode JSON message body directly using Mojo::JSON if possible, returns "undef" otherwise. An optional JSON Pointer can be used to extract a specific value with Mojo::JSON::Pointer.

  say $message->json->{foo}->{bar}->[23];
  say $message->json('/foo/bar/23');

  "leftovers"
  my $bytes = $message->leftovers;

Alias for "leftovers" in Mojo::Content.

  "max_line_size"
  $message->max_line_size(1024);

Alias for "max_line_size" in Mojo::Headers.

  "param"
  my @names = $message->param;
  my $foo   = $message->param('foo');
  my @foo   = $message->param('foo');

Access "POST" parameters.

  "parse"
  $message = $message->parse('HTTP/1.1 200 OK...');

Parse message chunk.

  "parse_until_body"
  $message = $message->parse_until_body('HTTP/1.1 200 OK...');

Parse message chunk until the body is reached.

  "start_line_size"
  my $size = $message->start_line_size;

Size of the start line in bytes.

  "to_string"
  my $string = $message->to_string;

Render whole message.

  "upload"
  my $upload  = $message->upload('foo');
  my @uploads = $message->upload('foo');

Access "multipart/form-data" file uploads, usually Mojo::Upload objects.

  say $message->upload('foo')->asset->slurp;

  "uploads"
  my $uploads = $message->uploads;

All "multipart/form-data" file uploads, usually Mojo::Upload objects.

  say $message->uploads->[2]->filename;

  "write"
  $message->write('Hello!');
  $message->write('Hello!', sub {...});

Alias for "write" in Mojo::Content.

  "write_chunk"
  $message->write_chunk('Hello!');
  $message->write_chunk('Hello!', sub {...});

Alias for "write_headers" in Mojo::Content.

SEE ALSO
Mojolicious, Mojolicious::Guides, <http://mojolicio.us>.