The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mojolicious-4.77
River stage four • 943 direct dependents • 1041 total dependents
495 ++
/ Mojo::Message

NAME

Mojo::Message - HTTP message base class

SYNOPSIS

  package Mojo::Message::MyMessage;
  use Mojo::Base 'Mojo::Message';

  sub cookies              {...}
  sub extract_start_line   {...}
  sub get_start_line_chunk {...}

DESCRIPTION

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

EVENTS

Mojo::Message inherits all events from Mojo::EventEmitter and can emit the following new ones.

finish

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

Emitted after message building or parsing is finished.

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

progress

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

Emitted when message building or parsing makes progress.

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

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

ATTRIBUTES

Mojo::Message implements the following attributes.

content

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

Message content, defaults to a Mojo::Content::Single object.

default_charset

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

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

max_line_size

  my $size = $msg->max_line_size;
  $msg     = $msg->max_line_size(1024);

Maximum start line size in bytes, defaults to the value of the MOJO_MAX_LINE_SIZE environment variable or 10240.

max_message_size

  my $size = $msg->max_message_size;
  $msg     = $msg->max_message_size(1024);

Maximum message size in bytes, defaults to the value of the MOJO_MAX_MESSAGE_SIZE environment variable or 10485760. Setting the value to 0 will allow messages of indefinite size. 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 = $msg->version;
  $msg        = $msg->version('1.1');

HTTP version of message, defaults to 1.1.

METHODS

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

body

  my $bytes = $msg->body;
  $msg      = $msg->body('Hello!');

Slurp or replace "content", Mojo::Content::MultiPart will be automatically downgraded to Mojo::Content::Single.

body_params

  my $params = $msg->body_params;

POST parameters extracted from application/x-www-form-urlencoded or multipart/form-data message body, usually a Mojo::Parameters object. Note that this method caches all data, so it should not be called before the entire message body has been received. Parts of the message body need to be loaded into memory to parse POST parameters, so you have to make sure it is not excessively large.

  # Get POST parameter value
  say $msg->body_params->param('foo');

body_size

  my $size = $msg->body_size;

Content size in bytes.

build_body

  my $bytes = $msg->build_body;

Render whole body.

build_headers

  my $bytes = $msg->build_headers;

Render all headers.

build_start_line

  my $bytes = $msg->build_start_line;

Render start line.

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

Access message cookies, usually Mojo::Cookie::Request or Mojo::Cookie::Response objects. Note that this method caches all data, so it should not be called before all headers have been received.

  # Get cookie value
  say $msg->cookie('foo')->value;

cookies

  my $cookies = $msg->cookies;

Access message cookies. Meant to be overloaded in a subclass.

dom

  my $dom        = $msg->dom;
  my $collection = $msg->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 Mojo::Collection object. Note that this method caches all data, so it should not be called before the entire message body has been received. The whole message body needs to be loaded into memory to parse it, so you have to make sure it is not excessively large.

  # Perform "find" right away
  say $msg->dom('h1, h2, h3')->text;

  # Use everything else Mojo::DOM has to offer
  say $msg->dom->at('title')->text;
  say $msg->dom->html->body->children->type->uniq;

error

  my $err          = $msg->error;
  my ($err, $code) = $msg->error;
  $msg             = $msg->error('Parser error');
  $msg             = $msg->error('Parser error', 500);

Error and code.

extract_start_line

  my $bool = $msg->extract_start_line(\$str);

Extract start line from string. Meant to be overloaded in a subclass.

finish

  $msg = $msg->finish;

Finish message parser/generator.

fix_headers

  $msg = $msg->fix_headers;

Make sure message has all required headers.

get_body_chunk

  my $bytes = $msg->get_body_chunk($offset);

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

get_header_chunk

  my $bytes = $msg->get_header_chunk($offset);

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

get_start_line_chunk

  my $bytes = $msg->get_start_line_chunk($offset);

Get a chunk of start line data starting from a specific position. Meant to be overloaded in a subclass.

header_size

  my $size = $msg->header_size;

Size of headers in bytes.

headers

  my $headers = $msg->headers;

Message headers, usually a Mojo::Headers object.

is_finished

  my $bool = $msg->is_finished;

Check if message parser/generator is finished.

is_limit_exceeded

  my $bool = $msg->is_limit_exceeded;

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

json

  my $hash  = $msg->json;
  my $array = $msg->json;
  my $value = $msg->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. Note that this method caches all data, so it should not be called before the entire message body has been received. The whole message body needs to be loaded into memory to parse it, so you have to make sure it is not excessively large.

  # Extract JSON values
  say $msg->json->{foo}{bar}[23];
  say $msg->json('/foo/bar/23');

param

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

Access POST parameters. Note that this method caches all data, so it should not be called before the entire message body has been received. Parts of the message body need to be loaded into memory to parse POST parameters, so you have to make sure it is not excessively large.

parse

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

Parse message chunk.

start_line_size

  my $size = $msg->start_line_size;

Size of the start line in bytes.

text

  my $str = $msg->text;

Retrieve "body" and try to decode it if a charset could be extracted with "charset" in Mojo::Content.

to_string

  my $str = $msg->to_string;

Render whole message.

upload

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

Access multipart/form-data file uploads, usually Mojo::Upload objects. Note that this method caches all data, so it should not be called before the entire message body has been received.

  # Get content of uploaded file
  say $msg->upload('foo')->asset->slurp;

uploads

  my $uploads = $msg->uploads;

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

SEE ALSO

Mojolicious, Mojolicious::Guides, http://mojolicio.us.