NAME

HTTP::Client - Class for making HTTP requests

SYNOPSIS

  use HTTP::Client;
  
  my $client  = HTTP::Client->new();
  my $site    = $client->get("http://www.cpan.org");
  my @headers = $client->response_headers;
  my $agent   = $client->agent;
  print $agent . "\n";
  print $headers[$_] . "\n" foreach (0..$#headers);
  print $site;

DESCRIPTION

HTTP::Client is a class for creating clients, that does not require LWP. It is aimed at speed. It can send HTTP Request headers, get HTTP response headers and get documents.

METHODS

new

This is the constructor for HTTP::Client. It can be called like this:

   my $client = HTTP::Client->new;
   

or this:

   my $client = new HTTP::Client ();

it can take the useragent string as an argument like this:

   my $client = HTTP::Client->new("Bot/1.0");
   

If the useragent is supplied in the constructor, but then supplied in the "agent" method, the constructor will be authoritative. In other words, you can only override the already specified client name by using only "agent" methods, and not the constructor. (This is actually a bug.)

$client->get

get gets a page on the web. It can only do http pages for now. The URI (URL) to get is the only argument it takes. It returns the body of the site if successful (The HTTP status code is "200 OK", or the other HTTP status code if it is not equal to that. For example:

   my $site = $client->get("http://www.cpan.org");
   print $site . "\n"; 
   

prints the source of cpan.org or the status code if it could not find it. It will append a trailing slash to the URL if it doesn't end in one.

$client->response_headers

response_headers returns an array of all the response headers sent by the server. Currently, to loop through the array, you must use this construct:

 my $site = $client->get("http://www.cpan.org");
 my @headers = $client->response_headers;
 foreach (0..$#headers) {
    print $headers[$_] . "\n";
 }
 

this is a big bug.

$client->agent

agent sets th current User-Agent header, thus renaming the current client. If the agent was specified in the constructor, even using this method will not override the one specified in the constructor. So, you can only override your useragent with multiple agent()s, not with the constructor and then agent()s. For example:

 my $client = HTTP::Client->new("Bot/1.0");
 my $site = $client->get("http://www.cpan.org");
 $client->agent("NewBot/1.0"); #Wrong! agent is still "Bot/1.0"
 

is wrong but this:

 my $client = HTTP::Client->new;
 my $site = $client->get("http://www.cpan.org");
 $client->agent("NewBot/1.0"); #Right! useragent is NewBot/1.0!
 $client->agent("NewNewBot/1.0"); #Right! useragent is now NewNewBot/1.0!
 

is right and changes the useragent after the second call.

$client->from

from sets the From header, which should be an email address of the person/machine that is sending the request. If the from was specified in the constructor, just like the agent method, using this method will not override the setting in the constructor. Therefore, you can only override from headers by using multiple from() methods, not by using the constructor and then from methods. For example:

 my $client = HTTP::Client->new("Bot/1.1", "nightcat\@crocker.com");
 my $site = $client->get("http://www.cpan.org");
 $client->from("au\@th.or"); #Wrong! From is still nightcat@crocker.com!
 

doesn't work, but this:

 my $client = HTTP::Client->new;
 my $site = $client->get("http://www.cpan.org");
 $client->from("nightcat\@crocker.com"); #Right! From is nightcat@crocker.com!
 $client->from("au\@th.or"); #Right! From is now au@th.or!
 

does. Note that you have to escape the at sign (@) in the address if you are using double quotes, because otherwise it will be interpreted as an array.

$client->status_message

status_message returns the HTTP status message sent by the server. It returns it in the full form, e.g. "200 OK" or "404 Not Found". For example:

 my $site = $client->get("http://www.cpan.org");
 print $client->status_message;
 

prints "200 OK". Note that if here, and anywhere else when getting a site, if a bad hostname is supplies, the program will die with the error "Can't get (url to get); may be a result of a bad hostname: (error message in $!)"

$client->server

returns the value of the Server header sent by the server.

$client->content_type

returns the Content-Type header sent by the server.

$client->last_modified

returns the Last-Modified header sent by the server.

$client->protocol

returns the protocol sent by the server. (Usually something like "HTTP/1.1"

$client->content_encoding

returns the Content-Encoding header sent by the server.

$client->content_length

returns the Content-Length header sent by the server.

$client->warning

returns the Warning header sent be the server.

$client->title

returns the Title header sent by the server.

Note: This is no longer part of the HTTP specification.

$client->date

returns the Date header returned by the server.

$client->host

returns the Host header returned by the server.

EXAMPLE

a real world example for getting documents would be:

 use HTTP::Client;
 my $client = HTTP::Client->new("GetBot/1.0");
 my $url = shift || <STDIN>;
 chomp($url);
 my $site = $client->get($url);
 print "\n" . $client->agent . " got $url successfully.";
 print "\n\nHeaders Recieved:\n";
 my @headers = $client->response_headers;
 print "$headers[$_]\n" foreach (0..$#headers);
 print "\nBody of document:\n\n";
 print $site . "\n\n";

SEE ALSO

http://neilb.org/reviews/http-requesters.html - a review of CPAN modules for making HTTP requests.

In short, you should consider one of the following modules: HTTP::Tiny, LWP::UserAgent, Furl, Mojo::UserAgent, LWP::Curl, Net::Curl.

AUTHOR

As of 1.52, this module is now maintained by Neil Bowers <neilb@cpan.org>.

HTTP::Client was written by Lincoln Ombelets <lincdog85@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2005-2012 Lincoln Ombelets.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.