Manual

The package provides an easy way to perform HTTP requests. It supports GET/POST/HEAD/TRACE/PUT/DELETE, Basic authentication, Proxy, Proxy Authentication, SSL, file uploads etc.

Introduction

Introduction – Introduction to HTTP_Request

Overview

With this package, one can easily perform HTTP request from within PHP scripts. It support GET/POST/HEAD/TRACE/PUT/DELETE, Basic authentication, Proxy, Proxy Authentication, SSL, file uploads etc.

Because of the above mentioned features HTTP_Request makes it possible to mimic big parts of web browsers such as the widely-known Mozilla browser in PHP applications. Possible application areas are:

Checking the validity of WWW links with the help of getResponseCode.
Grabbing remote web pages and parsing the result.
etc.

A few examples

Fetches yahoo.com and displays it

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://www.yahoo.com/");
if (!PEAR::isError($req->sendRequest())) {
    echo $req->getResponseBody();
}
?>

Fetching two website in a row

In this example, two websites are fetched and displayed. To the first one a POST parameter is passed. The POST data stack is cleared before the second website is fetched.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://www.php.net");
$req->setMethod(HTTP_REQUEST_METHOD_POST);
$req->addPostData("Foo", "bar");
if (!PEAR::isError($req->sendRequest())) {
     $response1 = $req->getResponseBody();
} else {
     $response1 = "";
}
     
$req->setMethod(HTTP_REQUEST_METHOD_GET);
$req->setURL("http://pear.php.net");
$req->clearPostData();
if (!PEAR::isError($req->sendRequest())) {
     $response2 = $req->getResponseBody();
} else {
     $response2 = "";
}

echo $response1;
echo $response2;
?>

Basic Authentication

Basic Authentication – Authentication for protected websites

Introduction to Basic Authentication

Basic Authentication is a challenge-response mechanism described in RFC 2617.

How to use Basic Authentication

Basic Authentication

The following example assumes that one wants to fetch a page /protected.html on the host example.com that is protected using Basic Authentication. The necessary username to pass the authentication is johndoe and the appendant password is foo.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/protected.html");
$req->setBasicAuth("johndoe", "foo");

$response = $req->sendRequest();

if (PEAR::isError($response)) {
    echo $response->getMessage();
} else {
    echo $req->getResponseBody();
}
?>

Cookies

Cookies – Making use of Cookies within HTTP_Request.

How to add Cookie to a HTTP request

Adding a cookie to the request

In this example a cookie named version is added to the HTTP request. The value of this cookie is the version string of the PHP interpreter that is running the instance of HTTP_Request.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->addCookie("version", phpversion());

$response = $req->sendRequest();

if (PEAR::isError($response)) {
    echo $response->getMessage();
} else {
    echo $req->getResponseBody();
}
?>

Reading cookies from a HTTP response

Reading cookies that come with a HTTP response is shown in this following example.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");

$response = $req->sendRequest();

if (PEAR::isError($response)) {
    echo $response->getMessage();
} else {
    print_r($req->getResponseCookies());
}
?>

File uploads

File uploads – Uploading files via HTTP

How to use file uploads

Upload a PDF document

In this example a file named /home/johndoe/text.pdf is uploaded to the remote machine upload.example.com. Additionally Basic Authentication is used to ensure that John is allowed to upload something.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://upload.example.com/upload.php");
$req->setBasicAuth("johndoe", "foo");
$req->setMethod(HTTP_REQUEST_METHOD_POST);

$result = $req->addFile('file_upload_field', '/home/johndoe/text.pdf', 'application/pdf');
if (PEAR::isError($result)) {
    echo $result->getMessage();
} else {

    $response = $req->sendRequest();

    if (PEAR::isError($response)) {
        echo $response->getMessage();
    } else {
        echo $req->getResponseBody();
    }
}
?>

Request headers

Request headers – Adding additional headers to the HTTP request.

How to add request headers

Adding a custom request header

In this example a HTTP header X-PHP-Version is added to the HTTP request. The value of this header is the version string of the PHP interpreter that is running the instance of HTTP_Request.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->addHeader("X-PHP-Version", phpversion());

$response = $req->sendRequest();

if (PEAR::isError($response)) {
    echo $response->getMessage();
} else {
    echo $req->getResponseBody();
}
?>

Headers that have been added to the HTTP_Request object can be removed with the method removeHeader(), before sendRequest() has been called.

Proxy Authorization

Proxy Authorization – Making use of a HTTP proxy

How to use Proxy Authorization

Using a proxy server with anonymous access

In this example it is assumed that one wants to use the machine with the hostname proxy.example.com, where a proxy server is listening on port 8080, to proxy the outgoing connection to example.com.

The second parameter of setProxy() is optional and defaults to 8080.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->setProxy("proxy.example.com", 8080);
?>

Using proxy authorization

This is the same example as above, except that a username/password tuple is provided, which authorizes the user at the proxy server: The username is johndoe and the appendant password is foo.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->setProxy("proxy.example.com", 8080, "johndoe", "foo");
?>

Response Evaluation

Response Evaluation – Evaluating the information from a HTTP response

Introduction

Because HTTP is a protocol based on the Request - Response scheme, every HTTP request is followed by a HTTP response. HTTP_Request offers several methods to evaluate the information from these responses.

Response Codes

A important part of the HTTP response is the response code. The most well-known response code probably is 404, which you may have seen in your browser at several occasions. The meaning of 404 is that the requested ressource could not be found. A complete list of status codes can be found in RFC 2616.

Checking the response code

<?php
require_once "HTTP/Request.php";

$urls = array(
    "http://www.example.com/",
    "http://example.com/thisdoesnotexist.html"
    );

$req =& new HTTP_Request("");
foreach ($urls as $url) {
    $req->setURL($url);
    $req->sendRequest();

    $code = $req->getResponseCode();
    switch ($code) {
    case 404:
        echo "Document not found\n";
        break;

    case 200:
        echo "Everything's ok\n";
        break;

    /* ... */
    }
}
?>

Response Headers

Similar to a HTTP request a HTTP response consists of a header and a body. HTTP_Request offers a method to access the header of the response.

Getting all headers from the response

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->sendRequest();

foreach ($req->getResponseHeader() as $name => $value) {
    echo $name . " = " . $value . "\n";
}
?>

This will print all headers and the appendant values.

Getting a specific header

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->sendRequest();

echo $req->getResponseHeader("Date");
?>

This will print the value of the Date: header.

Response Cookies

Fetching the cookies that are part of the HTTP response is described in the Cookies section.

HTTP_Request_Listener

HTTP_Request_Listener – attaching listeners to HTTP_Request operations

Introduction to HTTP_Request_Listener

HTTP_Request_Listener is an abstract class that can be extended to capture events and respond to them as they occur. Included with HTTP_Request is an example of a console-based progress bar. To implement this, the HTTP_Request_DownloadListener class is used, which uses the Console_ProgressBar package to display a download progress meter.

Example usage of HTTP_Request_Listener

In order to use a listener, it must attach to the specific HTTP_Request or HTTP_Response object that you want to monitor. The attach code is shown at the bottom of the example. As you can see, the event listener is propagated from the HTTP_Request object to any child HTTP_Response objects, and attaching only need happen to the first HTTP_Request object.

Download progress bar with HTTP_Request_Listener

<?php
/**
 * An example of Listener usage with HTTP_Request. This downloads and saves 
 * the file displaying the progress bar in the process.
 * 
 * Note two things:
 * 1) The file should be run in console, not in browser;
 * 2) You should turn output buffering OFF for this to work properly.
 */

require_once 'HTTP/Request.php';
require_once 'HTTP/Request/Listener.php';
require_once 'Console/ProgressBar.php';

PEAR::setErrorHandling(PEAR_ERROR_DIE);

set_time_limit(0);

class HTTP_Request_DownloadListener extends HTTP_Request_Listener
{
   /**
    * Handle for the target file
    * @var int
    */
    var $_fp;

   /**
    * Console_ProgressBar intance used to display the indicator
    * @var object
    */
    var $_bar;

   /**
    * Name of the target file
    * @var string
    */
    var $_target;

   /**
    * Number of bytes received so far
    * @var int
    */
    var $_size = 0;

    function HTTP_Request_DownloadListener()
    {
        $this->HTTP_Request_Listener();
    }

   /**
    * Opens the target file
    * @param string Target file name
    * @throws PEAR_Error
    */
    function setTarget($target)
    {
        $this->_target = $target;
        $this->_fp = @fopen($target, 'wb');
        if (!$this->_fp) {
            PEAR::raiseError("Cannot open '{$target}'");
        }
    }

    function update(&$subject, $event, $data = null)
    {
        switch ($event) {
            case 'sentRequest': 
                $this->_target = basename($subject->_url->path);
                break;

            case 'gotHeaders':
                if (isset($data['content-disposition']) &&
                    preg_match('/filename="([^"]+)"/', $data['content-disposition'], $matches)) {

                    $this->setTarget(basename($matches[1]));
                } else {
                    $this->setTarget($this->_target);
                }
                $this->_bar =& new Console_ProgressBar(
                    '* ' . $this->_target . ' %fraction% KB [%bar%] %percent%', '=>', '-', 
                    79, (isset($data['content-length'])? round($data['content-length'] / 1024): 100)
                );
                $this->_size = 0;
                break;

            case 'tick':
                $this->_size += strlen($data);
                $this->_bar->update(round($this->_size / 1024));
                fwrite($this->_fp, $data);
                break;

            case 'gotBody':
                fclose($this->_fp);
                break;

            case 'connect':
            case 'disconnect':
                break;

            default:
                PEAR::raiseError("Unhandled event '{$event}'");
        } // switch
    }
}

// Try using any other package if you like, but choose the bigger ones
// to be able to see the progress bar
$url = 'http://pear.php.net/get/HTML_QuickForm-stable';

$req =& new HTTP_Request($url);

$download =& new HTTP_Request_DownloadListener();
$req->attach($download);
$req->sendRequest(false);
?>

Events that can be caught

The HTTP_Request class sends these events:

connect - upon server connection, this event is sent
sentRequest - after the request was sent, this event is sent
disconnect - after server disconnect, this event is sent

The HTTP_Response class sends these events:

gotHeaders - this event is sent after receiving response headers (headers are passed in $data as an associative array)
tick - this event is sent on receiving a part of response body (the part is passed in $data as a string)
gzTick - this event is sent on receiving a part of response body that is gzip-compressed (the part is passed in $data as a string)
gotBody - this event is sent on after receiving the complete response body (the decoded body is passed as a string in $data if it was gzipped)