Request Options

You can customize requests created by a client using request options. Request options control various aspects of a request including, headers, query string parameters, timeout settings, the body of a request, and much more.

All of the following examples use the following client:

$client = new GuzzleHttp\Client(['base_url' => 'http://httpbin.org']);

headers

// Set various headers on a request
$client->get('/get', [
    'headers' => [
        'User-Agent' => 'testing/1.0',
        'Accept'     => 'application/json',
        'X-Foo'      => ['Bar', 'Baz']
    ]
]);

body

This setting can be set to any of the following types:

• string

  // You can send requests that use a string as the message body.
  $client->put('/put', ['body' => 'foo']);

• resource returned from fopen()

  // You can send requests that use a stream resource as the body.
  $resource = fopen('http://httpbin.org', 'r');
  $client->put('/put', ['body' => $resource]);

• Array

  Use an array to send POST style requests that use a GuzzleHttp\Post\PostBodyInterface object as the body.

  // You can send requests that use a POST body containing fields & files.
  $client->post('/post', [
      'body' => [
          'field' => 'abc',
          'other_field' => '123',
          'file_name' => fopen('/path/to/file', 'r')
      ]
  ]);

• GuzzleHttp\Stream\StreamInterface

  // You can send requests that use a Guzzle stream object as the body
  $stream = GuzzleHttp\Stream\Stream::factory('contents...');
  $client->post('/post', ['body' => $stream]);

json

$request = $client->createRequest('PUT', '/put', ['json' => ['foo' => 'bar']]);
echo $request->getHeader('Content-Type');
// application/json
echo $request->getBody();
// {"foo":"bar"}

Note

This request option does not support customizing the Content-Type header or any of the options from PHP’s json_encode() function. If you need to customize these settings, then you must pass the JSON encoded data into the request yourself using the body request option and you must specify the correct Content-Type header using the headers request option.

query

// Send a GET request to /get?foo=bar
$client->get('/get', ['query' => ['foo' => 'bar']]);

Query strings specified in the query option are combined with any query string values that are parsed from the URL.

// Send a GET request to /get?abc=123&foo=bar
$client->get('/get?abc=123', ['query' => ['foo' => 'bar']]);

auth

The built-in authentication types are as follows:

basic

Use basic HTTP authentication in the Authorization header (the default setting used if none is specified).

$client->get('/get', ['auth' => ['username', 'password']]);

digest

Use digest authentication (must be supported by the HTTP handler).

$client->get('/get', ['auth' => ['username', 'password', 'digest']]);

This is currently only supported when using the cURL handler, but creating a replacement that can be used with any HTTP handler is planned.

Important

The authentication type (whether it’s provided as a string or as the third option in an array) is always converted to a lowercase string. Take this into account when implementing custom authentication types and when implementing custom message factories.

Custom Authentication Schemes

You can also provide a string representing a custom authentication type name. When using a custom authentication type string, you will need to implement the authentication method in an event listener that checks the auth request option of a request before it is sent. Authentication listeners that require a request is not modified after they are signed should have a very low priority to ensure that they are fired last or near last in the event chain.

use GuzzleHttp\Event\BeforeEvent;
use GuzzleHttp\Event\RequestEvents;
/**
 * Custom authentication listener that handles the "foo" auth type.
 *
 * Listens to the "before" event of a request and only modifies the request
 * when the "auth" config setting of the request is "foo".
 */
class FooAuth implements GuzzleHttp\Event\SubscriberInterface
{
    private $password;
    public function __construct($password)
    {
        $this->password = $password;
    }
    public function getEvents()
    {
        return ['before' => ['sign', RequestEvents::SIGN_REQUEST]];
    }
    public function sign(BeforeEvent $e)
    {
        if ($e->getRequest()->getConfig()['auth'] == 'foo') {
            $e->getRequest()->setHeader('X-Foo', 'Foo ' . $this->password);
        }
    }
}
$client->getEmitter()->attach(new FooAuth('password'));
$client->get('/', ['auth' => 'foo']);

Adapter Specific Authentication Schemes

If you need to use authentication methods provided by cURL (e.g., NTLM, GSS, etc.), then you need to specify a curl handler option in the options request option array. See config for more information.

cookies

Set to true to use a shared cookie session associated with the client.

// Enable cookies using the shared cookie jar of the client.
$client->get('/get', ['cookies' => true]);

Pass an associative array containing cookies to send in the request and start a new cookie session.

// Enable cookies and send specific cookies
$client->get('/get', ['cookies' => ['foo' => 'bar']]);

Set to a GuzzleHttp\Cookie\CookieJarInterface object to use an existing cookie jar.

$jar = new GuzzleHttp\Cookie\CookieJar();
$client->get('/get', ['cookies' => $jar]);

allow_redirects

[
    ‘max’       => 5,
    ‘strict’    => false,
    ‘referer’   => true,
    ‘protocols’ => [‘http’, ‘https’]
]

Set to false to disable redirects.

$res = $client->get('/redirect/3', ['allow_redirects' => false]);
echo $res->getStatusCode();
// 302

Set to true (the default setting) to enable normal redirects with a maximum number of 5 redirects.

$res = $client->get('/redirect/3');
echo $res->getStatusCode();
// 200

Pass an associative array containing the ‘max’ key to specify the maximum number of redirects, provide a ‘strict’ key value to specify whether or not to use strict RFC compliant redirects (meaning redirect POST requests with POST requests vs. doing what most browsers do which is redirect POST requests with GET requests), provide a ‘referer’ key to specify whether or not the “Referer” header should be added when redirecting, and provide a ‘protocols’ array that specifies which protocols are supported for redirects (defaults to ['http', 'https']).

$res = $client->get('/redirect/3', [
    'allow_redirects' => [
        'max'       => 10,       // allow at most 10 redirects.
        'strict'    => true,     // use "strict" RFC compliant redirects.
        'referer'   => true,     // add a Referer header
        'protocols' => ['https'] // only allow https URLs
    ]
]);
echo $res->getStatusCode();
// 200

decode_content

This option can be used to control how content-encoded response bodies are handled. By default, decode_content is set to true, meaning any gzipped or deflated response will be decoded by Guzzle.

When set to false, the body of a response is never decoded, meaning the bytes pass through the handler unchanged.

// Request gzipped data, but do not decode it while downloading
$client->get('/foo.js', [
    'headers'        => ['Accept-Encoding' => 'gzip'],
    'decode_content' => false
]);

When set to a string, the bytes of a response are decoded and the string value provided to the decode_content option is passed as the Accept-Encoding header of the request.

// Pass "gzip" as the Accept-Encoding header.
$client->get('/foo.js', ['decode_content' => 'gzip']);

save_to

Pass a string to specify the path to a file that will store the contents of the response body:

$client->get('/stream/20', ['save_to' => '/path/to/file']);

Pass a resource returned from fopen() to write the response to a PHP stream:

$resource = fopen('/path/to/file', 'w');
$client->get('/stream/20', ['save_to' => $resource]);

Pass a GuzzleHttp\Stream\StreamInterface object to stream the response body to an open Guzzle stream:

$resource = fopen('/path/to/file', 'w');
$stream = GuzzleHttp\Stream\Stream::factory($resource);
$client->get('/stream/20', ['save_to' => $stream]);

events

use GuzzleHttp\Event\BeforeEvent;
use GuzzleHttp\Event\HeadersEvent;
use GuzzleHttp\Event\CompleteEvent;
use GuzzleHttp\Event\ErrorEvent;
$client->get('/', [
    'events' => [
        'before' => function (BeforeEvent $e) { echo 'Before'; },
        'complete' => function (CompleteEvent $e) { echo 'Complete'; },
        'error' => function (ErrorEvent $e) { echo 'Error'; },
    ]
]);

Here’s an example of using the associative array format for control over the priority and whether or not an event should be triggered more than once.

$client->get('/', [
    'events' => [
        'before' => [
            'fn'       => function (BeforeEvent $e) { echo 'Before'; },
            'priority' => 100,
            'once'     => true
        ]
    ]
]);

subscribers

use GuzzleHttp\Subscriber\History;
use GuzzleHttp\Subscriber\Mock;
use GuzzleHttp\Message\Response;
$history = new History();
$mock = new Mock([new Response(200)]);
$client->get('/', ['subscribers' => [$history, $mock]]);
echo $history;
// Outputs the request and response history

exceptions

$client->get('/status/500');
// Throws a GuzzleHttp\Exception\ServerException
$res = $client->get('/status/500', ['exceptions' => false]);
echo $res->getStatusCode();
// 500

timeout

// Timeout if a server does not return a response in 3.14 seconds.
$client->get('/delay/5', ['timeout' => 3.14]);
// PHP Fatal error:  Uncaught exception 'GuzzleHttp\Exception\RequestException'

connect_timeout

// Timeout if the client fails to connect to the server in 3.14 seconds.
$client->get('/delay/5', ['connect_timeout' => 3.14]);

Note

This setting must be supported by the HTTP handler used to send a request. connect_timeout is currently only supported by the built-in cURL handler.

verify

// Use the system's CA bundle (this is the default setting)
$client->get('/', ['verify' => true]);
// Use a custom SSL certificate on disk.
$client->get('/', ['verify' => '/path/to/cert.pem']);
// Disable validation entirely (don't do this!).
$client->get('/', ['verify' => false]);

Not all system’s have a known CA bundle on disk. For example, Windows and OS X do not have a single common location for CA bundles. When setting “verify” to true, Guzzle will do its best to find the most appropriate CA bundle on your system. When using cURL or the PHP stream wrapper on PHP versions >= 5.6, this happens by default. When using the PHP stream wrapper on versions < 5.6, Guzzle tries to find your CA bundle in the following order:

1. Check if openssl.cafile is set in your php.ini file.
2. Check if curl.cainfo is set in your php.ini file.
3. Check if /etc/pki/tls/certs/ca-bundle.crt exists (Red Hat, CentOS, Fedora; provided by the ca-certificates package)
4. Check if /etc/ssl/certs/ca-certificates.crt exists (Ubuntu, Debian; provided by the ca-certificates package)
5. Check if /usr/local/share/certs/ca-root-nss.crt exists (FreeBSD; provided by the ca_root_nss package)
6. Check if /usr/local/etc/openssl/cert.pem (OS X; provided by homebrew)
7. Check if C:\windows\system32\curl-ca-bundle.crt exists (Windows)
8. Check if C:\windows\curl-ca-bundle.crt exists (Windows)

The result of this lookup is cached in memory so that subsequent calls in the same process will return very quickly. However, when sending only a single request per-process in something like Apache, you should consider setting the openssl.cafile environment variable to the path on disk to the file so that this entire process is skipped.

If you do not need a specific certificate bundle, then Mozilla provides a commonly used CA bundle which can be downloaded here (provided by the maintainer of cURL). Once you have a CA bundle available on disk, you can set the “openssl.cafile” PHP ini setting to point to the path to the file, allowing you to omit the “verify” request option. Much more detail on SSL certificates can be found on the cURL website.

cert

$client->get('/', ['cert' => ['/path/server.pem', 'password']]);

ssl_key

Note

ssl_key is implemented by HTTP handlers. This is currently only supported by the cURL handler, but might be supported by other third-part handlers.

proxy

Pass a string to specify a proxy for all protocols.

$client->get('/', ['proxy' => 'tcp://localhost:8125']);

Pass an associative array to specify HTTP proxies for specific URI schemes (i.e., “http”, “https”).

$client->get('/', [
    'proxy' => [
        'http'  => 'tcp://localhost:8125', // Use this proxy with "http"
        'https' => 'tcp://localhost:9124'  // Use this proxy with "https"
    ]
]);

Note

You can provide proxy URLs that contain a scheme, username, and password. For example, "http://username:password@192.168.16.1:10".

debug

$client->get('/get', ['debug' => true]);

Running the above example would output something like the following:

* About to connect() to httpbin.org port 80 (#0)
*   Trying 107.21.213.98... * Connected to httpbin.org (107.21.213.98) port 80 (#0)
> GET /get HTTP/1.1
Host: httpbin.org
User-Agent: Guzzle/4.0 curl/7.21.4 PHP/5.5.7
< HTTP/1.1 200 OK
< Access-Control-Allow-Origin: *
< Content-Type: application/json
< Date: Sun, 16 Feb 2014 06:50:09 GMT
< Server: gunicorn/0.17.4
< Content-Length: 335
< Connection: keep-alive
<
* Connection #0 to host httpbin.org left intact

stream

$response = $client->get('/stream/20', ['stream' => true]);
// Read bytes off of the stream until the end of the stream is reached
$body = $response->getBody();
while (!$body->eof()) {
    echo $body->read(1024);
}

Note

Streaming response support must be implemented by the HTTP handler used by a client. This option might not be supported by every HTTP handler, but the interface of the response object remains the same regardless of whether or not it is supported by the handler.

expect

Set to true to enable the “Expect: 100-Continue” header for all requests that sends a body. Set to false to disable the “Expect: 100-Continue” header for all requests. Set to a number so that the size of the payload must be greater than the number in order to send the Expect header. Setting to a number will send the Expect header for all requests in which the size of the payload cannot be determined or where the body is not rewindable.

By default, Guzzle will add the “Expect: 100-Continue” header when the size of the body of a request is greater than 1 MB and a request is using HTTP/1.1.

Note

This option only takes effect when using HTTP/1.1. The HTTP/1.0 and HTTP/2.0 protocols do not support the “Expect: 100-Continue” header. Support for handling the “Expect: 100-Continue” workflow must be implemented by Guzzle HTTP handlers used by a client.

version

// Force HTTP/1.0
$request = $client->createRequest('GET', '/get', ['version' => 1.0]);
echo $request->getProtocolVersion();
// 1.0

config

$request = $client->createRequest('GET', '/get', ['config' => ['foo' => 'bar']]);
echo $request->getConfig('foo');
// 'bar'

Some HTTP handlers allow you to specify custom handler-specific settings. For example, you can pass custom cURL options to requests by passing an associative array in the config request option under the curl key.

// Use custom cURL options with the request. This example uses NTLM auth
// to authenticate with a server.
$client->get('/', [
    'config' => [
        'curl' => [
            CURLOPT_HTTPAUTH => CURLAUTH_NTLM,
            CURLOPT_USERPWD  => 'username:password'
        ]
    ]
]);

future

By default, Guzzle requests should be synchronous. You can create asynchronous future responses by passing the future request option as true. The response will only be executed when it is used like a normal response, the wait() method of the response is called, or the corresponding handler that created the response is destructing and there are futures that have not been resolved.

Important

This option only has an effect if your handler can create and return future responses. However, even if a response is completed synchronously, Guzzle will ensure that a FutureResponse object is returned for API consistency.

$response = $client->get('/foo', ['future' => true])
    ->then(function ($response) {
        echo 'I got a response! ' . $response;
    });