This page provides a quick introduction to Guzzle and introductory examples. If you have not already installed, Guzzle, head over to the Installation page.
You can send requests with Guzzle in one of two ways: through the procedural
API or using a GuzzleHttp\ClientInterface object. Using the procedural API
is an easy way to send a quick HTTP request. Using a Client object provides
much more flexibility in how requests are transferred and allows you to more
easily test the client.
Here’s an example of sending a POST request using the procedural API.
$response = GuzzleHttp\post('http://httpbin.org/post', [
'headers' => ['X-Foo' => 'Bar'],
'body' => ['field_name' => 'value']
]);
You can send all kinds of HTTP requests with the procedural API. Just call the function that maps to the HTTP method name.
$response = GuzzleHttp\head('http://httpbin.org/get');
$response = GuzzleHttp\post('http://httpbin.org/post');
$response = GuzzleHttp\put('http://httpbin.org/put');
$response = GuzzleHttp\delete('http://httpbin.org/delete');
$response = GuzzleHttp\options('http://httpbin.org/get');
The procedural API is simple but not very testable; it’s best left for quick
prototyping. If you want to use Guzzle in a more flexible and testable way,
then you’ll need to use a GuzzleHttp\ClientInterface object.
use GuzzleHttp\Client;
$client = new Client();
$response = $client->get('http://httpbin.org/get');
// You can use the same methods you saw in the procedural API
$response = $client->delete('http://httpbin.org/delete');
$response = $client->head('http://httpbin.org/get');
$response = $client->options('http://httpbin.org/get');
$response = $client->patch('http://httpbin.org/patch');
$response = $client->post('http://httpbin.org/post');
$response = $client->put('http://httpbin.org/put');
You can create a request with a client and then send the request with the client when you’re ready.
$request = $client->createRequest('GET', 'http://www.foo.com');
$response = $client->send($request);
Client objects provide a great deal of flexibility in how request are transferred including default request options, subscribers that are attached to each request, and a base URL that allows you to send requests with relative URLs. You can find out all about clients in the Clients page of the documentation.
In the previous examples, we retrieved a $response variable. This value is
actually a GuzzleHttp\Message\ResponseInterface object and contains lots
of helpful information.
You can get the status code and reason phrase of the response.
$code = $response->getStatusCode();
// 200
$reason = $response->getReasonPhrase();
// OK
The body of a response can be retrieved and cast to a string.
$body = $response->getBody();
echo $body;
// { "some_json_data" ...}
You can also read read bytes from body of a response like a stream.
$body = $response->getBody();
while (!$body->eof()) {
echo $body->read(1024);
}
You can more easily work with JSON responses using the json() method of a
response.
$response = $client->get('http://httpbin.org/get');
$json = $response->json();
var_dump($json[0]['origin']);
Guzzle internally uses PHP’s json_decode() function to parse responses. If
Guzzle is unable to parse the JSON response body, then a
GuzzleHttp\Exception\ParseException is thrown.
You can use a response’s xml() method to more easily work with responses
that contain XML data.
$response = $client->get('https://github.com/mtdowling.atom');
$xml = $response->xml();
echo $xml->id;
// tag:github.com,2008:/mtdowling
Guzzle internally uses a SimpleXMLElement object to parse responses. If
Guzzle is unable to parse the XML response body, then a
GuzzleHttp\Exception\ParseException is thrown.
Sending query string parameters with a request is easy. You can set query string parameters in the request’s URL.
$response = $client->get('http://httpbin.org?foo=bar');
You can also specify the query string parameters using the query request
option.
$client->get('http://httpbin.org', [
'query' => ['foo' => 'bar']
]);
And finally, you can build up the query string of a request as needed by
calling the getQuery() method of a request and modifying the request’s
GuzzleHttp\Query object as needed.
$request = $client->createRequest('GET', 'http://httpbin.org');
$query = $request->getQuery();
$query->set('foo', 'bar');
// You can use the query string object like an array
$query['baz'] = 'bam';
// The query object can be cast to a string
echo $query;
// foo=bar&baz=bam
// Setting a value to false or null will cause the "=" sign to be omitted
$query['empty'] = null;
echo $query;
// foo=bar&baz=bam&empty
// Use an empty string to include the "=" sign with an empty value
$query['empty'] = '';
echo $query;
// foo=bar&baz=bam&empty=
You can specify request headers when sending or creating requests with a
client. In the following example, we send the X-Foo-Header with a value of
value by setting the headers request option.
$response = $client->get('http://httpbin.org/get', [
'headers' => ['X-Foo-Header' => 'value']
]);
You can view the headers of a response using header specific methods of a response class. Headers work exactly the same way for request and response object.
You can retrieve a header from a request or response using the getHeader()
method of the object. This method is case-insensitive and by default will
return a string containing the header field value.
$response = $client->get('http://www.yahoo.com');
$length = $response->getHeader('Content-Length');
Header fields that contain multiple values can be retrieved as a string or as
an array. Retrieving the field values as a string will naively concatenate all
of the header values together with a comma. Because not all header fields
should be represented this way (e.g., Set-Cookie), you can pass an optional
flag to the getHeader() method to retrieve the header values as an array.
$values = $response->getHeader('Set-Cookie', true);
foreach ($values as $value) {
echo $value;
}
You can test if a request or response has a specific header using the
hasHeader() method. This method accepts a case-insensitive string and
returns true if the header is present or false if it is not.
You can retrieve all of the headers of a message using the getHeaders()
method of a request or response. The return value is an associative array where
the keys represent the header name as it will be sent over the wire, and each
value is an array of strings associated with the header.
$headers = $response->getHeaders();
foreach ($message->getHeaders() as $name => $values) {
echo $name . ": " . implode(", ", $values);
}
The headers of a message can be modified using the setHeader(),
addHeader(), setHeaders(), and removeHeader() methods of a request
or response object.
$request = $client->createRequest('GET', 'http://httpbin.org/get');
// Set a single value for a header
$request->setHeader('User-Agent', 'Testing!');
// Set multiple values for a header in one call
$request->setHeader('X-Foo', ['Baz', 'Bar']);
// Add a header to the message
$request->addHeader('X-Foo', 'Bam');
echo $request->getHeader('X-Foo');
// Baz, Bar, Bam
// Remove a specific header using a case-insensitive name
$request->removeHeader('x-foo');
echo $request->getHeader('X-Foo');
// Echoes an empty string: ''
Guzzle provides several methods of uploading data.
You can send requests that contain a stream of data by passing a string,
resource returned from fopen, or a GuzzleHttp\Stream\StreamInterface
object to the body request option.
$r = $client->post('http://httpbin.org/post', ['body' => 'raw data']);
You can easily upload JSON data using the json request option.
$r = $client->put('http://httpbin.org/put', ['json' => ['foo' => 'bar']]);
In addition to specifying the raw data of a request using the body request
option, Guzzle provides helpful abstractions over sending POST data.
Sending application/x-www-form-urlencoded POST requests requires that you
specify the body of a POST request as an array.
$response = $client->post('http://httpbin.org/post', [
'body' => [
'field_name' => 'abc',
'other_field' => '123'
]
]);
You can also build up POST requests before sending them.
$request = $client->createRequest('POST', 'http://httpbin.org/post');
$postBody = $request->getBody();
// $postBody is an instance of GuzzleHttp\Post\PostBodyInterface
$postBody->setField('foo', 'bar');
echo $postBody->getField('foo');
// 'bar'
echo json_encode($postBody->getFields());
// {"foo": "bar"}
// Send the POST request
$response = $client->send($request);
Sending multipart/form-data POST requests (POST requests that contain
files) is the same as sending application/x-www-form-urlencoded, except
some of the array values of the POST fields map to PHP fopen resources, or
GuzzleHttp\Stream\StreamInterface, or
GuzzleHttp\Post\PostFileInterface objects.
use GuzzleHttp\Post\PostFile;
$response = $client->post('http://httpbin.org/post', [
'body' => [
'field_name' => 'abc',
'file_filed' => fopen('/path/to/file', 'r'),
'other_file' => new PostFile('other_file', 'this is the content')
]
]);
Just like when sending POST fields, you can also build up POST requests with files before sending them.
use GuzzleHttp\Post\PostFile;
$request = $client->createRequest('POST', 'http://httpbin.org/post');
$postBody = $request->getBody();
$postBody->setField('foo', 'bar');
$postBody->addFile(new PostFile('test', fopen('/path/to/file', 'r')));
$response = $client->send($request);
Guzzle will automatically follow redirects unless you tell it not to. You can
customize the redirect behavior using the allow_redirects request option.
Set to true to enable normal redirects with a maximum number of 5 redirects. This is the default setting.
Set to false to disable redirects.
Pass an associative array containing the ‘max’ key to specify the maximum number of redirects and optionally 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).
$response = $client->get('http://github.com');
echo $response->getStatusCode();
// 200
echo $response->getEffectiveUrl();
// 'https://github.com/'
The following example shows that redirects can be disabled.
$response = $client->get('http://github.com', ['allow_redirects' => false]);
echo $response->getStatusCode();
// 301
echo $response->getEffectiveUrl();
// 'http://github.com/'
Guzzle throws exceptions for errors that occur during a transfer.
In the event of a networking error (connection timeout, DNS errors, etc.),
a GuzzleHttp\Exception\RequestException is thrown. This exception
extends from GuzzleHttp\Exception\TransferException. Catching this
exception will catch any exception that can be thrown while transferring
(non-parallel) requests.
use GuzzleHttp\Exception\RequestException;
try {
$client->get('https://github.com/_abc_123_404');
} catch (RequestException $e) {
echo $e->getRequest();
if ($e->hasResponse()) {
echo $e->getResponse();
}
}
A GuzzleHttp\Exception\ClientException is thrown for 400
level errors if the exceptions request option is set to true. This
exception extends from GuzzleHttp\Exception\BadResponseException and
GuzzleHttp\Exception\BadResponseException extends from
GuzzleHttp\Exception\RequestException.
use GuzzleHttp\Exception\ClientException;
try {
$client->get('https://github.com/_abc_123_404');
} catch (ClientException $e) {
echo $e->getRequest();
echo $e->getResponse();
}
A GuzzleHttp\Exception\ServerException is thrown for 500 level
errors if the exceptions request option is set to true. This
exception extends from GuzzleHttp\Exception\BadResponseException.
A GuzzleHttp\Exception\TooManyRedirectsException is thrown when too
many redirects are followed. This exception extends from GuzzleHttp\Exception\RequestException.
A GuzzleHttp\Exception\AdapterException is thrown when an error occurs
in an HTTP adapter during a parallel request. This exception is only thrown
when using the sendAll() method of a client.
All of the above exceptions extend from
GuzzleHttp\Exception\TransferException.