Protocol::HTTP::Request - HTTP request class
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'], }, });
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).
new
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.
allow_compression
Accept-Encoding
When a new request is ready it can be serialized via to_string method into byte octets.
to_string
All methods of Protocol::HTTP::Message also apply.
Constructs new request from hashref of properties, i.e. method, uri, allow_compression, headers, body, http_version, chunked, compress, form.
method
uri
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.
multipart/form-data
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.
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.
GET
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.
Get/set HTTP request method, e.g. GET, POST etc. in the first line of the request
Possible values:
The special value to distinguish the case, when client developer did not specify the desired 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
Set/get uri as URI::XS. $uri argument can be anything that one-argument constructor of URI::XS supports (for example, string).
$uri
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.
Set/get single cookie.
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.
Returns the bit mask of desirable compression methods (i.e. specified at Accept-Encoding header).
if ($request->allowed_compression & Protocol::HTTP::Compression::gzip) { ...; }
Serializes a request into string for sending via network. If the compression was requested (see Protocol::HTTP::Message), then it will be applied here.
Returns stringified HTTP request method, e.g. "GET", "POST" etc.
"GET"
"POST"
Returns corresponding string for a constant METHOD_*, i.e. "GET", "POST" etc.
METHOD_*
Protocol::HTTP
Protocol::HTTP::Message
Protocol::HTTP::Compression
Protocol::HTTP::CookieJar
URI::XS
To install Protocol::HTTP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Protocol::HTTP
CPAN shell
perl -MCPAN -e shell install Protocol::HTTP
For more information on module installation, please visit the detailed CPAN module installation guide.