HTTP client for PHP¶

Base URLs¶

Notice that the URI provided to the client’s get() method is relative. Relative URIs will always merge into the base URL of the client. There are a few rules that control how the URIs are merged.

In the above example, we passed /user to the get() method of the client. This is a relative URI, so it will merge into the base URL of the client– resulting in the derived URL of https://api.github.com/users.

/user is a relative URL but uses an absolute path because it contains the leading slash. Absolute paths will overwrite any existing path of the base URL. If an absolute path is provided (e.g. /path/to/something), then the path specified in the base URL of the client will be replaced with the absolute path, and the query string provided will replace the query string of the base URL.

Omitting the leading slash and using relative paths will add to the path of the base URL of the client. So using a client base URL of https://api.twitter.com/v1.1 and creating a GET request with statuses/user_timeline.json will result in a URL of https://api.twitter.com/v1.1/statuses/user_timeline.json. If a relative path and a query string are provided, then the relative path will be appended to the base URL path, and the query string provided will be merged into the query string of the base URL.

If an absolute URL is provided (e.g. http://httpbin.org/ip), then the request will completely use the absolute URL as-is without merging in any of the URL parts specified in the base URL.

Configuration options¶

The second argument of the client’s constructor is an array of configuration data. This can include URI template data or special options that alter the client’s behavior:

• curl.options: Associative array of cURL options to apply to every request created by the client.
• ssl.certificate_authority: Set to true to use the bundled SSL certificate bundle, system to use the bundle on your system, a string pointing to a file to use a specific certificate authority, a string pointing to a directory to use multiple certificates, or false to disable SSL validation.
• request.params: Associative array of parameters to apply to the parameter collection of every request created by the client.
• command.params: When using a Guzzle\Service\Client object, this is an associative array of default options to set on each command created by the client.

use Guzzle\Http\Client;

$client = new Client('https://api.twitter.com/{version}', array(
    'version' => 'v1.1',
    'curl.options' => array(
        CURLOPT_PROXY => 'tcp://localhost:80'
    ),
    'ssl.certificate_authority' => 'system',
    'request.params' => array(
        'foo' => 'bar'
    )
));

Requests¶

Requests can be created from a client using method names that match the HTTP verb. Guzzle supports the following HTTP methods: GET, HEAD, DELETE, PUT, POST, PATCH, and OPTIONS. You can use any other custom HTTP method by calling $client->createRequest($methodName).

use Guzzle\Http\Client;

$client = new Client('http://baseurl.com/api/v1');

// Relative to base URL (http://baseurl.com/api/v1/path?query=123&value=abc)
$request = $client->get('path?query=123&value=abc');

// Overrides base URL's path (http://baseurl.com/path?query=123&value=abc)
$request = $client->head('/path?query=123&value=abc');

// Delete using an Absolute URL
$request = $client->delete('http://www.example.com/path?query=123&value=abc');

// Create a PUT request using the contents of a PHP stream as the body
$request = $client->put('http://www.example.com/upload', array(
    'X-Header' => 'My Header'
), fopen('http://www.test.com/', 'r'));

// Create a POST request and add the POST files manually
$request = $client->post('http://localhost:8983/solr/update')
    ->addPostFiles(array('file' => '/path/to/documents.xml'));

// Check if a resource supports the DELETE method
$supportsDelete = $client->options('/path')->send()->isMethodAllowed('DELETE');

If you know exactly what HTTP message you want to send, you can create request objects from messages:

use Guzzle\Http\Message\RequestFactory;

$request = RequestFactory::fromMessage(
    "PUT / HTTP/1.1\r\n" .
    "Host: test.com:8081\r\n" .
    "Content-Type: text/plain\r\n" .
    "Transfer-Encoding: chunked\r\n\r\n" .
    "this is the body"
);

Request objects are all about building an HTTP message. Each part of an HTTP request message can be set individually using methods on the request object or set in bulk using the setUrl() method. Here’s the format of an HTTP request with each part of the request referencing the method used to change it:

PUT(a) /path(b)?query=123(c) HTTP/1.1(d)
X-Header(e): header
Content-Length(e): 4

data(f)

$request = new Guzzle\Http\Message\Request('GET', 'http://www.example.com?foo=bar&abc=123');

$query = $request->getQuery();
echo "{$query}\n";
//> foo=bar&abc=123

$query->remove('abc');
echo "{$query}\n";
//> foo=bar

$query->set('foo', 'baz');
echo "{$query}\n";
//> foo=baz

$query->add('foo', 'bar');
echo "{$query}\n";
//> foo%5B0%5D=baz&foo%5B1%5D=bar

$query->useUrlEncoding(false);
echo "{$query}\n";
//> foo[0]=baz&foo[1]=bar

$response = $client->put('http://httpbin.org/put', null, 'this is the body')->send();

$request = $client->post('http://httpbin.org/post')
    ->addPostFields(array('custom_key' => 'value'))
    ->addPostFiles(array('file' => '/path/to/file.xml'));

$request = $client->post('http://www.example.com/upload', null, array(
    'custom_field' => 'my custom value',
    'file_field'   => '@/path/to/file.xml'
));

// Prevent users from accessing sensitive files by sanitizing input
$_POST = array('firstname' => '@/etc/passwd');
$request = $client->post('http://www.example.com', null, array (
    'firstname' => str_replace('@', '', $_POST['firstname'])
));

$response = $client->post('http://httpbin.org/post', null, 'this is the body')->send();

Responses¶

Sending a request will return a Guzzle\Http\Message\Response object. You can view the HTTP response message by casting the Response object to a string. Casting the response to a string will return the entity body of the response as a string too, so this might be an expensive operation if the entity body is stored in a file or network stream. If you only want to see the response headers, you can call getRawHeaders().

The Response object contains helper methods for retrieving common response headers. These helper methods normalize the variations of HTTP response headers:

$response->getContentMd5();
$response->getEtag();
$response->getCacheControl();
$response->getHeader('Content-Length');
// ... There are methods for every known response header

The entity body object of a response can be retrieved by calling $response->getBody(). The response EntityBody can be cast to a string, or you can pass true to this method to retrieve the body as a string.

$data = $response->json();
echo gettype($data);
// >>> array

$xml = $response->xml();
echo $xml->foo;
// >>> Bar!

Request and response headers¶

HTTP message headers are case insensitive, multiple occurrences of any header can be present in an HTTP message (whether it’s valid or not), and some servers require specific casing of particular headers. Because of this, request and response headers are stored in Guzzle\Http\Message\Header objects. The Header object can be cast as a string, counted, or iterated to retrieve each value from the header. Casting a Header object to a string will return all of the header values concatenated together using a glue string (typically ‘, ‘). Let’s take the following example to see what is returned:

$request = new Request('GET', 'http://httpbin.com/cookies');
// addHeader will set and append to any existing header values
$request->addHeader('Foo', 'bar');
$request->addHeader('foo', 'baz');
// setHeader overwrites any existing values
$request->setHeader('Test', '123');

// Requests can be cast as a string
echo $request->getHeader('Foo');
// >>> bar, baz
echo $request->getHeader('Test');
// >>> "123"

// You can count the number of headers of a particular case insensitive name
echo count($request->getHeader('foO'));
// >>> 2

// You can iterate over Header objects
foreach ($request->getHeader('foo') as $header) {
    echo $header;
}

// Missing headers return NULL
var_export($request->getHeader('Missing'));
// >>> null

// You can see all of the different variations of a header by calling raw() on the Header
var_export($request->getHeader('foo')->raw());

Redirects¶

By default, Guzzle will automatically follow redirects using the non-RFC compliant implementation used by most web browsers. This means that redirects for POST requests are followed by a GET request. You can force RFC compliance by enabling the strict mode on a request’s parameter object:

// Set per request
$request = $client->post();
$request->getParams()->set('redirect.strict', true);
// Set globally on a client so that all requests use strict redirects
$client->getConfig()->set('request.params', array('redirect.strict' => true));

By default, Guzzle will redirect up to 5 times before throwing a Guzzle\Http\Exception\TooManyRedirectsException. You can raise or lower this value using the redirect.max parameter of a request object:

$request->getParams()->set('redirect.max', 2);

You can get the full chain of request/response objects that were sent to complete an HTTP transaction using the getPreviousResponse() method of a response object.:

$response = $request->send();

do {
    echo "{$response}\n\n";
    $response = $response->getPreviousResponse();
} while ($response);

You can disable redirects on a client by passing a configuration option in the client’s constructor:

$client = new Client(null, array('redirect.disable' => true));

You can also disable redirects per request:

$request->getParams()->set('redirect.disable', true);

$request = $client->post('http://httpbin.com/redirect/2', null, fopen('http://httpbin.com/get', 'r'));
// Add a custom function that can be used to rewind the stream (reopen in this example)
$request->getBody()->setRewindFunction(function ($body) {
    $body->setStream(fopen('http://httpbin.com/get', 'r'));
    return true;
);
$response = $client->send();

Dealing with errors¶

try {
    $response = $client->get('/not_found.xml')->send();
} catch (Guzzle\Http\Exception\BadResponseException $e) {
    echo 'Uh oh! ' . $e->getMessage();
}

// Add custom error handling to any request created by this client
$client->getEventDispatcher()->addListener('request.error', function(Event $event) {

    if ($event['response']->getStatusCode() == 401) {

        $newRequest = $event['request']->clone();
        $newRequest->setHeader('X-Auth-Header', MyApplication::getNewAuthToken());
        $newResponse = $newRequest->send();

        // Set the response object of the request without firing more events
        $event['response'] = $newResponse;

        // You can also change the response and fire the normal chain of
        // events by calling $event['request']->setResponse($newResponse);

        // Stop other events from firing when you override 401 responses
        $event->stopPropagation();
    }

});

Entity Bodies¶

Entity body is the term used for the body of an HTTP message. The entity body of requests and responses is inherently a PHP stream in Guzzle. The body of the request can be either a string or a PHP stream which are converted into a Guzzle\Http\EntityBody object using its factory method. When using a string, the entity body is stored in a temp PHP stream. The use of temp PHP streams helps to protect your application from running out of memory when sending or receiving large entity bodies in your messages. When more than 2MB of data is stored in a temp stream, it automatically stores the data on disk rather than in memory.

EntityBody objects provide a great deal of functionality: compression, decompression, calculate the Content-MD5, calculate the Content-Length (when the resource is repeatable), guessing the Content-Type, and more. Guzzle doesn’t need to load an entire entity body into a string when sending or retrieving data; entity bodies are streamed when being uploaded and downloaded.

Here’s an example of gzip compressing a text file then sending the file to a URL:

use Guzzle\Http\EntityBody;

$body = EntityBody::factory(fopen('/path/to/file.txt', 'r'));
$body->compress();
$response = $client->put('http://localhost:8080/uploads', null, $body)->send();

The body of the request can be specified in the Client::put() or Client::post() method, or, you can specify the body of the request by calling the setBody() method of any Guzzle\Http\Message\EntityEnclosingRequestInterface object.

The entity body received from a response is stored in a temp stream by default. If you need the entity body of a response to use a destination other than a temporary stream (e.g. FTP, HTTP, a specific file, an open stream), you can set the entity body object that will be used to hold the response body by calling setResponseBody() on any request object.

Send HTTP requests in parallel¶

Sending many HTTP requests serially (one at a time) can cause an unnecessary delay in a script’s execution. Each request must complete before a subsequent request can be sent. By sending requests in parallel, a pool of HTTP requests can complete at the speed of the slowest request in the pool, significantly reducing the amount of time needed to execute multiple HTTP requests. Guzzle provides a wrapper for the curl_multi functions in PHP.

You can pass a single request or an array of requests to a client’s send() method. Here’s an example of sending three requests in parallel using a client object:

use Guzzle\Common\Exception\ExceptionCollection;

try {
    $responses = $client->send(array(
        $client->get('http://www.google.com/'),
        $client->head('http://www.google.com/'),
        $client->get('https://www.github.com/')
    ));
} catch (ExceptionCollection $e) {
    echo "The following exceptions were encountered:\n";
    foreach ($e as $exception) {
        echo $exception->getMessage() . "\n";
    }
}

A single request failure will not cause the entire pool of requests to fail. Any exceptions thrown while transferring a pool of requests will be aggregated into a Guzzle\Common\Exception\ExceptionCollection exception.

Managed persistent HTTP connections¶

Persistent HTTP connections are an extremely important aspect of the HTTP/1.1 protocol that is often overlooked by PHP HTTP clients. Persistent connections allows data to be transferred between a client and server without the need to reconnect each time a subsequent request is sent, providing a significant performance boost to applications that need to send many HTTP requests to the same host. Guzzle implicitly manages persistent connections for all requests.

All HTTP requests sent using the same client object will use the same cURL multi handle. cURL will maintain a cache of persistent connections on a multi handle. More information about cURL’s internal design and persistent connection handling can be found at http://curl.haxx.se/dev/internals.html.

Low level cURL access¶

Most of the functionality implemented in the libcurl bindings has been simplified and abstracted by Guzzle. Developers who need access to cURL specific functionality that is not abstracted by Guzzle (e.g. proxies and some SSL options) can still add cURL handle specific behavior to Guzzle HTTP requests by modifying the cURL options collection of a request:

$request->getCurlOptions()->set(CURLOPT_SSL_VERIFYHOST, true);

You can add cURL options to every request sent from your client by adding configuration options to the curl.options array. Clients will automatically map cURL constants for keys and values to their correct PHP value.

$client = new Guzzle\Http\Client('https://example.com/', array(
    'curl.options' => array(
        CURLOPT_SSL_VERIFYHOST   => false,
        'CURLOPT_SSL_VERIFYPEER' => false,
        CURLOPT_PROXY            => 'proxy.mydomain.com:8080',
        'CURLOPT_PROXYTYPE'      => 'CURLPROXY_HTTP'
    )
));

If you are using Service Descriptions then you can override the cURL options within the definition of an operation, for example:

{
    "operations": {
        "get_users": {
            "httpMethod": "GET",
            "uri": "/users",
            "curl.options": {
                "CURLOPT_CONNECTTIMEOUT": "100"
            }
        }
    }
}

You can blacklist cURL options and headers from ever being sent by cURL by adding a blacklist configuration option to the curl.options array of your client. The following example demonstrates how to blacklist the CURLOPT_ENCODING option from ever being set on a request and prevents cURL from ever sending an Accept header on any request.

$client = new Guzzle\Http\Client('https://example.com/', array(
    'curl.options' => array(
        'blacklist' => array(CURLOPT_ENCODING, 'header.Accept')
    )
));

Other special options that can be set in the curl.options array include:

• debug: Adds verbose cURL output to a temp stream owned by the cURL handle object
• progress: Instructs cURL to emit events when IO events occur. This allows you to be notified when bytes are transferred over the wire by subscribing to a request’s curl.callback.read, curl.callback.write, and curl.callback.progress events.