/ 
Mojolicious-3.17
River stage four • 995 direct dependents • 1115 total dependents
/ Mojo::Message

NAME

Mojo::Message - HTTP message base class

SYNOPSIS

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

DESCRIPTION

Mojo::Message is an abstract base class for HTTP 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);

Message content, 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.

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.

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. Note that this method caches all data, so it should not be called before the entire message body has been received.

# Get POST parameter value
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.

my $cookie  = $message->cookie('foo');
my @cookies = $message->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 $message->cookie('foo')->value;

cookies

my $cookies = $message->cookies;

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

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 Mojo::Collection object. Note that this method caches all data, so it should not be called before the entire message body has been received.

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

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

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 $hash  = $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. Note that this method caches all data, so it should not be called before the entire message body has been received.

# Extract JSON values
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. Note that this method caches all data, so it should not be called before the entire message body has been received.

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 and stop after headers.

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. 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 $message->upload('foo')->asset->slurp;

uploads

my $uploads = $message->uploads;

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

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.