HTTP_Request2
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
// Explicitly set request method and use_brackets
$request = new HTTP_Request2('http://pear.php.net/bugs/search.php',
HTTP_Request2::METHOD_GET, array('use_brackets' => true));
$url = $request->getUrl();
$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
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
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');
?>
Using cookie jar to manage cookies across requests
Since release 2.0.0beta1 the package contains HTTP_Request2_CookieJar class that can be used manage cookies across requests. You can enable this functionality by passing either an existing instance of HTTP_Request2_CookieJar or TRUE to create a new instance to HTTP_Request2::setCookieJar() method. Cookie Jar can be later accessed by HTTP_Request2::getCookieJar().
Cookie jar will automatically store cookies set in HTTP response and pass them to requests with URLs matching cookie parameters. You can also manually add cookies to jar by using HTTP_Request2_CookieJar::store() method.
By default Public Suffix List is used to check whether a cookie domain matches the given URL. The same list is used to restrict cookie setting by Firefox, Chrome and Opera browsers. It can be disabled if needed by HTTP_Request2_CookieJar::usePublicSuffixList().
HTTP_Request2_CookieJar implements Serializable interface and thus can be easily serialized and stored somewhere. You can control whether session cookies stored in a jar should be serialized by calling HTTP_Request2_CookieJar::serializeSessionCookies().
When HTTP_Request2 instance has a cookie jar set, HTTP_Request2::addCookie() method will add a cookie to jar, rather than directly to
'Cookie'header, using current request URL for setting its'domain'and'path'components.
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');
?>
addUpload() can accept either a string with a local file name or a pointer to
an open file, as returned by fopen(). You currently can't
directly pass a string with the file contents, however you can pass a pointer to php://memory or
php://temp:
<?php
$fp = fopen('php://temp/maxmemory:1048576', 'r+');
fwrite($fp, generateFileUploadData());
$request->addUpload('stuff', $fp, 'custom.name', 'application/octet-stream');
?>
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.