HTTP_Request2

HTTP_Request2 – Class representing a HTTP request message

Request URL and `GET` Parameters

Request URL can be set in HTTP_Request2 constructor or via HTTP_Request2::setUrl() method. Both of these accept either a string or an instance of Net_URL2. URL is stored internally as an instance of Net_URL2 that can be accessed via HTTP_Request2::getUrl().

GET request parameters can be added to URL via Net_URL2::setQueryVariable() and Net_URL2::setQueryVariables():

Setting GET parameters


<?php
$request = new HTTP_Request2('http://pear.php.net/bugs/search.php');
$url = $request->getUrl();
// Explicitly set use_brackets
$url->setOption(Net_URL2::OPTION_USE_BRACKETS, true);
$url->setQueryVariables(array(
    'package_name' => array('HTTP_Request2', 'Net_URL2'),
    'status'       => 'Open'
));
$url->setQueryVariable('cmd', 'display');

// This will output a page with open bugs for Net_URL2 and HTTP_Request2
echo $request->send()->getBody();
?>

HTTP Authentication

HTTP_Request2 supports both Basic and Digest authentication schemes defined in RFC 2617. Authentication credentials can be set via HTTP_Request2::setAuth() method or given in the request URL (but in the latter case authentication scheme will default to Basic).

Setting authentication credentials


<?php
// This will set credentials for basic auth
$request = new HTTP_Request2('http://user:password@www.example.com/secret/');

// This will set credentials for Digest auth
$request->setAuth('user', 'password', HTTP_Request2::AUTH_DIGEST);
?>

There is currently an issue with Digest authentication support in Curl Adapter due to an underlying PHP cURL extension problem.

Request Headers and Cookies

Additional request headers can be set via HTTP_Request2::setHeader() method. It also allows removing previosly set headers

Setting request headers


<?php
// setting one header
$request->setHeader('Accept-Charset', 'utf-25');

// setting several headers in one go
$request->setHeader(array(
    'Connection' => 'close',
    'Referer'    => 'http://localhost/'
));

// removing a header
$request->setHeader('User-Agent', null);
?>

Cookies can be added to the request via setHeader() method, but a specialized HTTP_Request2::addCookie() method is also provided

Adding cookies to the request


<?php
$request->addCookie('CUSTOMER', 'WILE_E_COYOTE');
$request->addCookie('PART_NUMBER', 'ROCKET_LAUNCHER_0001');
?>

Request Body

If you are doing a POST request with Content-Type 'application/x-www-form-urlencoded' or 'multipart/form-data' (in other words, emulating POST form submission), you can add parameters via HTTP_Request2::addPostParameter() and file uploads via HTTP_Request2::addUpload(). HTTP_Request2 will take care of generating proper request body. File uploads will be streamed from disk by HTTP_Request2_MultipartBody to reduce memory consumption.

Emulating POST form submission


<?php
$request = new HTTP_Request2('http://www.example.com/profile.php');
$request->setMethod(HTTP_Request2::METHOD_POST)
    ->addPostParameter('username', 'vassily')
    ->addPostParameter(array(
        'email' => 'vassily.pupkin@mail.ru',
        'phone' => '+7 (495) 123-45-67'
    ))
    ->addUpload('avatar', './exploit.exe', 'me_and_my_cat.jpg', 'image/jpeg');
?>

HTTP request body can also be set directly, by providing a string or a filename to HTTP_Request2::setBody() method. This is the only way to set a request body for non-POST request.

Setting "raw" request body


<?php
$request = new HTTP_Request2('http://rpc.example.com');
$request->setMethod(HTTP_Request2::METHOD_POST)
    ->setHeader('Content-type: text/xml; charset=utf-8')
    ->setBody(
        "<?xml version=\"1.0\" encoding=\"utf-8\"?" . ">\r\n" .
        "<methodCall>\r\n" .
        " <methodName>foo.bar</methodName>\r\n" .
        " <params>\r\n" .
        "  <param><value><string>Hello, world!</string></value></param>\r\n" .
        "  <param><value><int>42</int></value></param>\r\n" .
        " </params>\r\n" .
        "</methodCall>"
    );
?>

HTTP Redirects

Since release 0.5.0 HTTP_Request2 can automatically follow HTTP redirects if follow_redirects parameter is set to TRUE.

HTTP_Request2 will only follow redirects to HTTP(S) URLs, redirects to other protocols will result in an Exception.

HTTP_Request2::send will return only the final response, if you are interested in the intermediate ones you should use Observers.