Quickstart

This page provides a quick introduction to Guzzle and introductory examples. If you have not already installed, Guzzle, head over to the Installation page.

Make a Request

You can send requests with Guzzle using a GuzzleHttp\ClientInterface object.

Creating a Client

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.

Using Responses

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

By providing the future request option to a request, you can send requests asynchronously using the promise interface of a future response.

$client->get('http://httpbin.org', ['future' => true])
    ->then(function ($response) {
        echo $response->getStatusCode();
    });

Response Body

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);
}

JSON Responses

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.

XML Responses

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.

Query String Parameters

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=

Request and Response Headers

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);
}

Modifying headers

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: ''

Uploading Data

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']]);

POST Requests

In addition to specifying the raw data of a request using the body request option, Guzzle provides helpful abstractions over sending POST data.

Sending POST Fields

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 POST Files

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);

Cookies

Guzzle can maintain a cookie session for you if instructed using the cookies request option.

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

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

• Set to a GuzzleHttp\Subscriber\CookieJar\CookieJarInterface object to use an existing cookie jar.

Redirects

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/'

Exceptions

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.

All of the above exceptions extend from GuzzleHttp\Exception\TransferException.