Table Of Contents

• Overview
• Quickstart
• Request Options
  • allow_redirects
  • auth
  • body
  • cert
  • cookies
  • connect_timeout
  • debug
  • decode_content
  • delay
  • expect
  • force_ip_resolve
  • form_params
  • headers
  • http_errors
  • idn_conversion
  • json
  • multipart
  • on_headers
  • on_stats
  • progress
  • proxy
  • query
  • read_timeout
  • sink
  • ssl_key
  • stream
  • synchronous
  • verify
  • timeout
  • version
• Guzzle and PSR-7
• Handlers and Middleware
• Testing Guzzle Clients
• FAQ

allow_redirects¶

Summary

Describes the redirect behavior of a request

Types

• bool
• array

Default

[    'max'             => 5,    'strict'          => false,    'referer'         => false,    'protocols'       => ['http', 'https'],    'track_redirects' => false]

Constant

GuzzleHttp\RequestOptions::ALLOW_REDIRECTS

Set tofalse to disable redirects.

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

Set totrue (the default setting) to enable normal redirects with a maximumnumber of 5 redirects.

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

You can also pass an associative array containing the following key valuepairs:

• max: (int, default=5) maximum number of allowed redirects.

• strict: (bool, default=false) Set to true to use strict redirects.Strict RFC compliant redirects mean that POST redirect requests are sent asPOST requests vs. doing what most browsers do which is redirect POST requestswith GET requests.

• referer: (bool, default=false) Set to true to enable adding the Refererheader when redirecting.

• protocols: (array, default=['http', 'https']) Specified which protocols areallowed for redirect requests.

• on_redirect: (callable) PHP callable that is invoked when a redirectis encountered. The callable is invoked with the original request and theredirect response that was received. Any return value from the on_redirectfunction is ignored.

• track_redirects: (bool) When set totrue, each redirected URI and statuscode encountered will be tracked in theX-Guzzle-Redirect-History andX-Guzzle-Redirect-Status-History headers respectively. All URIs andstatus codes will be stored in the order which the redirects were encountered.

  Note: When tracking redirects theX-Guzzle-Redirect-History header willexclude the initial request's URI and theX-Guzzle-Redirect-Status-Historyheader will exclude the final status code.

usePsr\Http\Message\RequestInterface;usePsr\Http\Message\ResponseInterface;usePsr\Http\Message\UriInterface;$onRedirect=function(RequestInterface$request,ResponseInterface$response,UriInterface$uri){echo'Redirecting! '.$request->getUri().' to '.$uri."\n";};$res=$client->request('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'on_redirect'=>$onRedirect,'track_redirects'=>true]]);echo$res->getStatusCode();// 200echo$res->getHeaderLine('X-Guzzle-Redirect-History');// http://first-redirect, http://second-redirect, etc...echo$res->getHeaderLine('X-Guzzle-Redirect-Status-History');// 301, 302, etc...

auth¶

Summary

Pass an array of HTTP authentication parameters to use with therequest. The array must contain the username in index [0], the password inindex [1], and you can optionally provide a built-in authentication type inindex [2]. Passnull to disable authentication for a request.

Types

• array
• string
• null

Default

None

Constant

GuzzleHttp\RequestOptions::AUTH

The built-in authentication types are as follows:

basic

Usebasic HTTP authenticationin theAuthorization header (the default setting used if none isspecified).

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

digest

Usedigest authentication(must be supported by the HTTP handler).

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

ntlm

UseMicrosoft NTLM authentication(must be supported by the HTTP handler).

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

body¶

Summary

Thebody option is used to control the body of an entityenclosing request (e.g., PUT, POST, PATCH).

Types

• string
• fopen() resource
• Psr\Http\Message\StreamInterface

Default

None

Constant

GuzzleHttp\RequestOptions::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->request('PUT','/put',['body'=>'foo']);

• resource returned fromfopen()

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

• Psr\Http\Message\StreamInterface

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

cert¶

Summary

Set to a string to specify the path to a file containing a PEMformatted client side certificate. If a password is required, then set toan array containing the path to the PEM file in the first array elementfollowed by the password required for the certificate in the second arrayelement.

Types

• string
• array

Default

None

Constant

GuzzleHttp\RequestOptions::CERT

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

cookies¶

Summary

Specifies whether or not cookies are used in a request or what cookiejar to use or what cookies to send.

Types

GuzzleHttp\Cookie\CookieJarInterface

Default

None

Constant

GuzzleHttp\RequestOptions::COOKIES

You must specify the cookies option as aGuzzleHttp\Cookie\CookieJarInterface orfalse.

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

connect_timeout¶

Summary

Float describing the number of seconds to wait while trying to connectto a server. Use0 to wait indefinitely (the default behavior).

Types

float

Default

0

Constant

GuzzleHttp\RequestOptions::CONNECT_TIMEOUT

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

debug¶

Summary

Set totrue or set to a PHP stream returned byfopen() toenable debug output with the handler used to send a request. For example,when using cURL to transfer requests, cURL's verbose ofCURLOPT_VERBOSEwill be emitted. When using the PHP stream wrapper, stream wrappernotifications will be emitted. If set to true, the output is written toPHP's STDOUT. If a PHP stream is provided, output is written to the stream.

Types

• bool
• fopen() resource

Default

None

Constant

GuzzleHttp\RequestOptions::DEBUG

$client->request('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.1Host: httpbin.orgUser-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

decode_content¶

Summary

Specify whether or notContent-Encoding responses (gzip,deflate, etc.) are automatically decoded.

Types

• string
• bool

Default

true

Constant

GuzzleHttp\RequestOptions::DECODE_CONTENT

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

When set tofalse, the body of a response is never decoded, meaning thebytes pass through the handler unchanged.

// Request gzipped data, but do not decode it while downloading$client->request('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 valueprovided to thedecode_content option is passed as theAccept-Encodingheader of the request.

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

delay¶

Summary

The number of milliseconds to delay before sending the request.

Types

• integer
• float

Default

null

Constant

GuzzleHttp\RequestOptions::DELAY

expect¶

Summary

Controls the behavior of the "Expect: 100-Continue" header.

Types

• bool
• integer

Default

1048576

Constant

GuzzleHttp\RequestOptions::EXPECT

Set totrue to enable the "Expect: 100-Continue" header for all requeststhat sends a body. Set tofalse to disable the "Expect: 100-Continue"header for all requests. Set to a number so that the size of the payload mustbe greater than the number in order to send the Expect header. Setting to anumber will send the Expect header for all requests in which the size of thepayload cannot be determined or where the body is not rewindable.

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

force_ip_resolve¶

Summary

Set to "v4" if you want the HTTP handlers to use only ipv4 protocol or "v6" for ipv6 protocol.

Types

string

Default

null

Constant

GuzzleHttp\RequestOptions::FORCE_IP_RESOLVE

// Force ipv4 protocol$client->request('GET','/foo',['force_ip_resolve'=>'v4']);// Force ipv6 protocol$client->request('GET','/foo',['force_ip_resolve'=>'v6']);

form_params¶

Summary

Used to send anapplication/x-www-form-urlencoded POST request.

Types

array

Constant

GuzzleHttp\RequestOptions::FORM_PARAMS

Associative array of form field names to values where each value is a string orarray of strings. Sets the Content-Type header toapplication/x-www-form-urlencoded when no Content-Type header is alreadypresent.

$client->request('POST','/post',['form_params'=>['foo'=>'bar','baz'=>['hi','there!']]]);

headers¶

Summary

Associative array of headers to add to the request. Each key is thename of a header, and each value is a string or array of stringsrepresenting the header field values.

Types

array

Defaults

None

Constant

GuzzleHttp\RequestOptions::HEADERS

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

Headers may be added as default options when creating a client. When headersare used as default options, they are only applied if the request being createddoes not already contain the specific header. This includes both requests passedto the client in thesend() andsendAsync() methods, and requestscreated by the client (e.g.,request() andrequestAsync()).

$client=newGuzzleHttp\Client(['headers'=>['X-Foo'=>'Bar']]);// Will send a request with the X-Foo header.$client->request('GET','/get');// Sets the X-Foo header to "test", which prevents the default header// from being applied.$client->request('GET','/get',['headers'=>['X-Foo'=>'test']]);// Will disable adding in default headers.$client->request('GET','/get',['headers'=>null]);// Will not overwrite the X-Foo header because it is in the message.useGuzzleHttp\Psr7\Request;$request=newRequest('GET','http://foo.com',['X-Foo'=>'test']);$client->send($request);// Will overwrite the X-Foo header with the request option provided in the// send method.useGuzzleHttp\Psr7\Request;$request=newRequest('GET','http://foo.com',['X-Foo'=>'test']);$client->send($request,['headers'=>['X-Foo'=>'overwrite']]);

http_errors¶

Summary

Set tofalse to disable throwing exceptions on an HTTP protocolerrors (i.e., 4xx and 5xx responses). Exceptions are thrown by default whenHTTP protocol errors are encountered.

Types

bool

Default

true

Constant

GuzzleHttp\RequestOptions::HTTP_ERRORS

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

idn_conversion¶

Summary

Internationalized Domain Name (IDN) support (enabled by default ifintl extension is available).

Types

• bool
• int

Default

true ifintl extension is available (and ICU library is 4.6+ for PHP 7.2+),false otherwise

Constant

GuzzleHttp\RequestOptions::IDN_CONVERSION

$client->request('GET','https://яндекс.рф');// яндекс.рф is translated to xn--d1acpjx3f.xn--p1ai before passing it to the handler$res=$client->request('GET','https://яндекс.рф',['idn_conversion'=>false]);// The domain part (яндекс.рф) stays unmodified

Enables/disables IDN support, can also be used for precise control by combiningIDNA_* constants (except IDNA_ERROR_*), see$options parameter inidn_to_ascii()documentation for more details.

json¶

Summary

Thejson option is used to easily upload JSON encoded data as thebody of a request. A Content-Type header ofapplication/json will beadded if no Content-Type header is already present on the message.

Types

Any PHP type that can be operated on by PHP'sjson_encode() function.

Default

None

Constant

GuzzleHttp\RequestOptions::JSON

$response=$client->request('PUT','/put',['json'=>['foo'=>'bar']]);

Here's an example of using thetap middleware to see what request is sentover the wire.

useGuzzleHttp\Middleware;// Create a middleware that echoes parts of the request.$tapMiddleware=Middleware::tap(function($request){echo$request->getHeaderLine('Content-Type');// application/jsonecho$request->getBody();// {"foo":"bar"}});// The $handler variable is the handler passed in the// options to the client constructor.$response=$client->request('PUT','/put',['json'=>['foo'=>'bar'],'handler'=>$tapMiddleware($handler)]);

multipart¶

Summary

Sets the body of the request to amultipart/form-data form.

Types

array

Constant

GuzzleHttp\RequestOptions::MULTIPART

The value ofmultipart is an array of associative arrays, each containingthe following key value pairs:

• name: (string, required) the form field name
• contents: (StreamInterface/resource/string, required) The data to use inthe form element.
• headers: (array) Optional associative array of custom headers to use withthe form element.
• filename: (string) Optional string to send as the filename in the part.

useGuzzleHttp\Psr7;$client->request('POST','/post',['multipart'=>[['name'=>'foo','contents'=>'data','headers'=>['X-Baz'=>'bar']],['name'=>'baz','contents'=>Psr7\Utils::tryFopen('/path/to/file','r')],['name'=>'qux','contents'=>Psr7\Utils::tryFopen('/path/to/file','r'),'filename'=>'custom_filename.txt'],]]);

on_headers¶

Summary

A callable that is invoked when the HTTP headers of the response havebeen received but the body has not yet begun to download.

Types

• callable

Constant

GuzzleHttp\RequestOptions::ON_HEADERS

The callable accepts aPsr\Http\Message\ResponseInterface object. If an exceptionis thrown by the callable, then the promise associated with the response willbe rejected with aGuzzleHttp\Exception\RequestException that wraps theexception that was thrown.

You may need to know what headers and status codes were received before datacan be written to the sink.

// Reject responses that are greater than 1024 bytes.$client->request('GET','http://httpbin.org/stream/1024',['on_headers'=>function(ResponseInterface$response){if($response->getHeaderLine('Content-Length')>1024){thrownew\Exception('The file is too big!');}}]);

on_stats¶

Summary

on_stats allows you to get access to transfer statistics of arequest and access the lower level transfer details of the handlerassociated with your client.on_stats is a callable that is invokedwhen a handler has finished sending a request. The callback is invokedwith transfer statistics about the request, the response received, or theerror encountered. Included in the data is the total amount of time takento send the request.

Types

• callable

Constant

GuzzleHttp\RequestOptions::ON_STATS

The callable accepts aGuzzleHttp\TransferStats object.

useGuzzleHttp\TransferStats;$client=newGuzzleHttp\Client();$client->request('GET','http://httpbin.org/stream/1024',['on_stats'=>function(TransferStats$stats){echo$stats->getEffectiveUri()."\n";echo$stats->getTransferTime()."\n";var_dump($stats->getHandlerStats());// You must check if a response was received before using the// response object.if($stats->hasResponse()){echo$stats->getResponse()->getStatusCode();}else{// Error data is handler specific. You will need to know what// type of error data your handler uses before using this// value.var_dump($stats->getHandlerErrorData());}}]);

progress¶

Summary

Defines a function to invoke when transfer progress is made.

Types

• callable

Default

None

Constant

GuzzleHttp\RequestOptions::PROGRESS

The function accepts the following positional arguments:

• the total number of bytes expected to be downloaded, zero if unknown
• the number of bytes downloaded so far
• the total number of bytes expected to be uploaded
• the number of bytes uploaded so far

// Send a GET request to /get?foo=bar$result=$client->request('GET','/',['progress'=>function($downloadTotal,$downloadedBytes,$uploadTotal,$uploadedBytes){//do something},]);

proxy¶

Summary

Pass a string to specify an HTTP proxy, or an array to specifydifferent proxies for different protocols.

Types

• string
• array

Default

None

Constant

GuzzleHttp\RequestOptions::PROXY

Pass a string to specify a proxy for all protocols.

$client->request('GET','/',['proxy'=>'http://localhost:8125']);

Pass an associative array to specify HTTP proxies for specific URI schemes(i.e., "http", "https"). Provide ano key value pair to provide a list ofhost names that should not be proxied to.

$client->request('GET','/',['proxy'=>['http'=>'http://localhost:8125',// Use this proxy with "http"'https'=>'http://localhost:9124',// Use this proxy with "https",'no'=>['.mit.edu','foo.com']// Don't use a proxy with these]]);

query¶

Summary

Associative array of query string values or query string to add tothe request.

Types

• array
• string

Default

None

Constant

GuzzleHttp\RequestOptions::QUERY

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

Query strings specified in thequery option will overwrite all query stringvalues supplied in the URI of a request.

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

read_timeout¶

Summary

Float describing the timeout to use when reading a streamed body

Types

float

Default

Defaults to the value of thedefault_socket_timeout PHP ini setting

Constant

GuzzleHttp\RequestOptions::READ_TIMEOUT

The timeout applies to individual read operations on a streamed body (when thestream option is enabled).

$response=$client->request('GET','/stream',['stream'=>true,'read_timeout'=>10,]);$body=$response->getBody();// Returns false on timeout$data=$body->read(1024);// Returns false on timeout$line=fgets($body->detach());

sink¶

Summary

Specify where the body of a response will be saved.

Types

• string (path to file on disk)
• fopen() resource
• Psr\Http\Message\StreamInterface

Default

PHP temp stream

Constant

GuzzleHttp\RequestOptions::SINK

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

$client->request('GET','/stream/20',['sink'=>'/path/to/file']);

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

$resource=\GuzzleHttp\Psr7\Utils::tryFopen('/path/to/file','w');$client->request('GET','/stream/20',['sink'=>$resource]);

Pass aPsr\Http\Message\StreamInterface object to stream the responsebody to an open PSR-7 stream.

$resource=\GuzzleHttp\Psr7\Utils::tryFopen('/path/to/file','w');$stream=\GuzzleHttp\Psr7\Utils::streamFor($resource);$client->request('GET','/stream/20',['save_to'=>$stream]);

ssl_key¶

Summary

Specify the path to a file containing a private SSL key in PEMformat. If a password is required, then set to an array containing the pathto the SSL key in the first array element followed by the password requiredfor the certificate in the second element.

Types

• string
• array

Default

None

Constant

GuzzleHttp\RequestOptions::SSL_KEY

stream¶

Summary

Set totrue to stream a response rather than download it allup-front.

Types

bool

Default

false

Constant

GuzzleHttp\RequestOptions::STREAM

$response=$client->request('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);}

synchronous¶

Summary

Set to true to inform HTTP handlers that you intend on waiting on theresponse. This can be useful for optimizations.

Types

bool

Default

none

Constant

GuzzleHttp\RequestOptions::SYNCHRONOUS

verify¶

Summary

Describes the SSL certificate verification behavior of a request.

• Set totrue to enable SSL certificate verification and use the defaultCA bundle provided by operating system.
• Set tofalse to disable certificate verification (this is insecure!).
• Set to a string to provide the path to a CA bundle to enable verificationusing a custom certificate.

Types

• bool
• string

Default

true

Constant

GuzzleHttp\RequestOptions::VERIFY

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

If you do not need a specific certificate bundle, then Mozilla provides acommonly used CA bundle which can be downloadedhere(provided by the maintainer of cURL). Once you have a CA bundle available ondisk, you can set the "openssl.cafile" PHP ini setting to point to the path tothe file, allowing you to omit the "verify" request option. Much more detail onSSL certificates can be found on thecURL website.

timeout¶

Summary

Float describing the total timeout of the request in seconds. Use0to wait indefinitely (the default behavior).

Types

float

Default

0

Constant

GuzzleHttp\RequestOptions::TIMEOUT

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

version¶

Summary

Protocol version to use with the request.

Types

string, float

Default

1.1

Constant

GuzzleHttp\RequestOptions::VERSION

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