The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
Protocol-HTTP-1.1.6
River stage one • 5 direct dependents • 5 total dependents
/ Protocol::HTTP::Request

NAME

Protocol::HTTP::Request - HTTP request class

SYNOPSIS


            

              
              
use Protocol::HTTP::Request;
# construction of new request
my $req = Protocol::HTTP::Request->new({
    method       => METHOD_POST,
    uri          => "http://crazypanda.ru/hello/world",
    http_version => 10,
    headers      => {MyHeader => "my value"},
    cookies      => {Lorem => 'ipsum'},
});
$req->method();             # => METHOD_POST
$req->uri();                # => isa 'URI::XS'
$req->uri->to_string;       # => 'http://crazypanda.ru/hello/world'
$req->uri('/something');
$req->uri->to_string;       # => '/something'
# we accept GZIP-compressed replies
$req->allow_compression(Protocol::HTTP::Compression::gzip);
$req->cookie('Location', 'Earth');
$req->cookie('Location');           # => 'Earth'
$req->cookies;                      # => is_deeply {Location => 'Earth', 'Lorem' => 'ipsum'}
# main serialization method
$req->to_string;        # like qr/GET.*HTTP/1.0.*MyHeader.*my body/sm
# we are crazy enough to send compressed request
$req->compress(Protocol::HTTP::Compression::gzip, Protocol::HTTP::Compression::LEVEL_OPTIMAL);
# now $req->to_string would return a little bit different result
# uploading as multipart/form-data
my $req = Protocol::HTTP::Request->new({
    form => [field1 => 'value1', field2 => ['filename.pdf' => $pdf_content, 'application/pdf']],
});
my $req = Protocol::HTTP::Request->new({
    form => {
        enc_type => ENCODING_MULTIPART,
        fields   => [field1 => 'value1', field2 => 'value2'],
    },
});
# populate form from URI
my $req = Protocol::HTTP::Request->new({
    uri  => '/path?login=user&pass=secret',
    form => ENCODING_MULTIPART
});
# populate URI from form
my $req = Protocol::HTTP::Request->new({
    uri  => '/path',
    form => {
        enc_type => ENCODING_MULTIPART,
        fields   => [login => 'user', pass => 'secret'],
    },
});

DESCRIPTION

This class represents client HTTP request, which is specialization of Protocol::HTTP::Message. An instance of the class can be constructed either direcly via new method to send a new request (clients), or via parsing incoming request with Protocol::HTTP::RequestParser (servers).

If it is acceptable to have a server reply with compressed payload, then allow_compression method should be invoked. It will setup Accept-Encoding header in a request.

When a new request is ready it can be serialized via to_string method into byte octets.

METHODS

All methods of Protocol::HTTP::Message also apply.

new([\%params])

Constructs new request from hashref of properties, i.e. method, uri, allow_compression, headers, body, http_version, chunked, compress, form.

See corresponding methods documentation below and in Protocol::HTTP::Message to find out what these parameters support.

allow_compression should be an array ref if multiple values are passed.

Parameter form allows to post request data as multipart/form-data (default) or as application/x-www-form-urlencoded.

In the simplest form it is just an array of fields and values, i.e.


            

              
              
Protocol::HTTP::Request->new({
    form => [key1 => 'value1', key2 => 'value2'],
});

A form field value can be also be specified as array; this might be needed for file posting to specify filename and content type additionally, i.e.


            

              
              
Protocol::HTTP::Request->new({
    fields   => [photo => ['sample.jpg' => $jpeg_content, 'image/jpeg']],
});

It is possible, however, to explicitly specify the type of encoding.

ENCODING_MULTIPART
ENCODING_URL

For example:


            

              
              
Protocol::HTTP::Request->new({
    form => {
        enc_type => ENCODING_MULTIPART,
        fields   => [key1 => 'value1', key2 => 'value2'],
    }
});

When it is encoded as multipart/form-data, the request will use the right method, e.g. if it is set to GET it will be switched to POST.

Sometimes it can be handy to use pseudo-URI to populate form (posted as multipart/form-data) from uri params, or populate URI from form.


            

              
              
# GET /path?login=user&pass=secret
my $req = Protocol::HTTP::Request->new({
    uri    => '/path',
    method => METHOD_GET,
    form   => {
        enc_type => ENCODING_URL,
        fields   => [login => 'user', pass => 'secret'],
    },
});
# POST with multipart/form-data via '/path' URI
my $req = Protocol::HTTP::Request->new({
    uri  => '/path?login=user&pass=secret',
    form => ENCODING_MULTIPART,
});

To let the URI population work form should be empty, as in the example above.

method_raw([$method])

Get/set HTTP request method, e.g. GET, POST etc. in the first line of the request

Possible values:

METHOD_GET
METHOD_POST
METHOD_PUT
METHOD_DELETE
METHOD_OPTIONS
METHOD_HEAD
METHOD_TRACE
METHOD_CONNECT
METHOD_UNSPECIFIED

The special value to distinguish the case, when client developer did not specify the desired method

method([$method])

Deduces the used method, i.e. when it is unspecified it will be GET or POST (for multipart/form_data).

The setter-variant works as method_raw setter

uri([$uri])

Set/get uri as URI::XS. $uri argument can be anything that one-argument constructor of URI::XS supports (for example, string).

cookies([\%cookies])

Set/get all cookies at once as a hashref.


            

              
              
$req->cookies({coo1 => "val1", coo2 => "val2", ... });

Please note, this is request cookies, i.e. set by client-side, and they have different API than response cookies.

cookie($name, [$value])

Set/get single cookie.

allow_compression($compression1, [$compression2, ...])

Sets acceptable compression methods in the responce of the request, i.e. Accept-Encoding header. Order of compression methods might be important.


            

              
              
$request->allow_compression(Protocol::HTTP::Compression::gzip);

See Protocol::HTTP::Compression for the list of available compressions.

allowed_compression()

Returns the bit mask of desirable compression methods (i.e. specified at Accept-Encoding header).


            

              
              
if ($request->allowed_compression & Protocol::HTTP::Compression::gzip) {
    ...;
}

See Protocol::HTTP::Compression for the list of available compressions.

to_string()

Serializes a request into string for sending via network. If the compression was requested (see Protocol::HTTP::Message), then it will be applied here.

method_str()

Returns stringified HTTP request method, e.g. "GET", "POST" etc.

FUNCTIONS

method_str($method)

Returns corresponding string for a constant METHOD_*, i.e. "GET", "POST" etc.

SEE ALSO

Protocol::HTTP

Protocol::HTTP::Message

Protocol::HTTP::Compression

Protocol::HTTP::CookieJar

URI::XS