HTTP::Request::Common - Construct common HTTP::Request objects


  use HTTP::Request::Common;
  $ua = LWP::UserAgent->new;
  $ua->request(GET '');
  $ua->request(POST 'http://somewhere/foo', [foo => bar, bar => foo]);


This module provide functions that return newly created HTTP::Request objects. These functions are usually more convenient than the standard HTTP::Request constructor for these common requests. The following functions are provided.

GET $url, [Header => Value,...]

The GET() function returns a HTTP::Request object initialized with the GET method and the specified URL. Without additional arguments it is exactly equivalent to the following call

  HTTP::Request->new(GET => $url)

but is less clutter. It also reads better when used together with the LWP::UserAgent->request() method:

  my $ua = new LWP::UserAgent;
  my $res = $ua->request(GET '')
  if ($res->is_success) { ...

You can also initialize the header values in the request by specifying some key/value pairs as optional arguments. For instance:

  $ua->request(GET '',
                   If_Match => 'foo',
                   From     => '',

A header key called 'Content' is special and when seen the value will initialize the content part of the request instead of setting a header.

HEAD $url, [Header => Value,...]

Like GET() but the method in the request is HEAD.

PUT $url, [Header => Value,...]

Like GET() but the method in the request is PUT.

POST $url, [$form_ref], [Header => Value,...]

This works mostly like GET() with POST as method, but this function also takes a second optional array reference parameter ($form_ref). This argument can be used to pass key/value pairs for the form content. By default we will initialize a request using the application/x-www-form-urlencoded content type. This means that you can emulate a HTML <form> POSTing like this:

  POST '',
       [ name  => 'Gisle',
         email => '',
         gender => 'm',
         born   => '1964',
         trust  => '3%',

This will create a HTTP::Request object that looks like this:

  Content-Length: 61
  Content-Type: application/x-www-form-urlencoded


The POST method also supports the multipart/form-data content used for Form-based File Upload as specified in RFC 1867. You trigger this content format by specifying a content type of 'form-data'. If one of the values in the $form_ref is an array reference, then it is treated as a file part specification with the following values:

  [ $file, $filename, Header => Value... ]

The first value in the array ($file) is the name of a file to open. This file will be read an its content placed in the request. The routine will croak if the file can't be opened. Use an undef as $file value if you want to specify the content directly. The $filename is the filename to report in the request. If this value is undefined, then the basename of the $file will be used. You can specify an empty string as $filename if you don't want any filename in the request.

Sending my ~/.profile to the survey used as example above can be achieved by this:

  POST '',
       Content_Type => 'form-data',
       Content      => [ name  => 'Gisle Aas',
                         email => '',
                         gender => 'm',
                         born   => '1964',
                         init   => ["$ENV{HOME}/.profile"],

This will create a HTTP::Request object that almost looks this (the boundary and the content of your ~/.profile is likely to be different):

  Content-Length: 388
  Content-Type: multipart/form-data; boundary="6G+f"

  Content-Disposition: form-data; name="name"
  Gisle Aas
  Content-Disposition: form-data; name="email"
  Content-Disposition: form-data; name="gender"
  Content-Disposition: form-data; name="born"
  Content-Disposition: form-data; name="init"; filename=".profile"
  Content-Type: text/plain
  export PATH



HTTP::Request, LWP::UserAgent


Copyright 1997, Gisle Aas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.