Guzzle client error

Создание запроса¶

Вы можете отправлять запросы с помощью Guzzle, используя объект GuzzleHttpClientInterface.

use GuzzleHttpClient;

$client = new Client([
    // Base URI is used with relative requests
    'base_uri' => 'http://httpbin.org',
    // You can set any number of default request options.
    'timeout'  => 2.0,
]);

$response = $client->get('http://httpbin.org/get');
$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');

use GuzzleHttpPsr7Request;

$request = new Request('PUT', 'http://httpbin.org/put');
$response = $client->send($request, ['timeout' => 2]);

$promise = $client->getAsync('http://httpbin.org/get');
$promise = $client->deleteAsync('http://httpbin.org/delete');
$promise = $client->headAsync('http://httpbin.org/get');
$promise = $client->optionsAsync('http://httpbin.org/get');
$promise = $client->patchAsync('http://httpbin.org/patch');
$promise = $client->postAsync('http://httpbin.org/post');
$promise = $client->putAsync('http://httpbin.org/put');

use GuzzleHttpPsr7Request;

// Create a PSR-7 request object to send
$headers = ['X-Foo' => 'Bar'];
$body = 'Hello!';
$request = new Request('HEAD', 'http://httpbin.org/head', $headers, $body);
$promise = $client->sendAsync($request);

// Or, if you don't need to pass in a request instance:
$promise = $client->requestAsync('GET', 'http://httpbin.org/get');

use PsrHttpMessageResponseInterface;
use GuzzleHttpExceptionRequestException;

$promise = $client->requestAsync('GET', 'http://httpbin.org/get');
$promise->then(
    function (ResponseInterface $res) {
        echo $res->getStatusCode() . "n";
    },
    function (RequestException $e) {
        echo $e->getMessage() . "n";
        echo $e->getRequest()->getMethod();
    }
);

use GuzzleHttpClient;
use GuzzleHttpPromise;

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

// Initiate each request but do not block
$promises = [
    'image' => $client->getAsync('/image'),
    'png'   => $client->getAsync('/image/png'),
    'jpeg'  => $client->getAsync('/image/jpeg'),
    'webp'  => $client->getAsync('/image/webp')
];

// Wait for the requests to complete; throws a ConnectException
// if any of the requests fail
$responses = PromiseUtils::unwrap($promises);

// You can access each response using the key of the promise
echo $responses['image']->getHeader('Content-Length')[0];
echo $responses['png']->getHeader('Content-Length')[0];

// Wait for the requests to complete, even if some of them fail
$responses = PromiseUtils::settle($promises)->wait();

// Values returned above are wrapped in an array with 2 keys: "state" (either fulfilled or rejected) and "value" (contains the response)
echo $responses['image']['state']; // returns "fulfilled"
echo $responses['image']['value']->getHeader('Content-Length')[0];
echo $responses['png']['value']->getHeader('Content-Length')[0];

use GuzzleHttpClient;
use GuzzleHttpExceptionRequestException;
use GuzzleHttpPool;
use GuzzleHttpPsr7Request;
use GuzzleHttpPsr7Response;

$client = new Client();

$requests = function ($total) {
    $uri = 'http://127.0.0.1:8126/guzzle-server/perf';
    for ($i = 0; $i < $total; $i++) {
        yield new Request('GET', $uri);
    }
};

$pool = new Pool($client, $requests(100), [
    'concurrency' => 5,
    'fulfilled' => function (Response $response, $index) {
        // this is delivered each successful response
    },
    'rejected' => function (RequestException $reason, $index) {
        // this is delivered each failed request
    },
]);

// Initiate the transfers and create a promise
$promise = $pool->promise();

// Force the pool of requests to complete.
$promise->wait();

$client = new Client();

$requests = function ($total) use ($client) {
    $uri = 'http://127.0.0.1:8126/guzzle-server/perf';
    for ($i = 0; $i < $total; $i++) {
        yield function() use ($client, $uri) {
            return $client->getAsync($uri);
        };
    }
};

$pool = new Pool($client, $requests(100));

Использование ответов¶

В предыдущих примерах мы извлекали переменную $response или нам был
получили ответ из обещания. Объект response реализует PSR-7
ответ, PsrHttpMessageResponseInterface, и содержит много
полезной информации.

Вы можете получить код состояния и фразу причины ответа:

$code = $response->getStatusCode(); // 200
$reason = $response->getReasonPhrase(); // OK

Вы можете получить заголовки из ответа:

// Check if a header exists.
if ($response->hasHeader('Content-Length')) {
    echo "It exists";
}

// Get a header from the response.
echo $response->getHeader('Content-Length')[0];

// Get all of the response headers.
foreach ($response->getHeaders() as $name => $values) {
    echo $name . ': ' . implode(', ', $values) . "rn";
}

Тело ответа можно получить с помощью метода getBody. Тело может быть использовано как строка, приведено к строке или использовано как потокоподобный объект.

$body = $response->getBody();
// Implicitly cast the body to a string and echo it
echo $body;
// Explicitly cast the body to a string
$stringBody = (string) $body;
// Read 10 bytes from the body
$tenBytes = $body->read(10);
// Read the remaining contents of the body as a string
$remainingBytes = $body->getContents();

Параметры строки запроса¶

Вы можете предоставить параметры строки запроса вместе с запросом несколькими способами.

Вы можете задать параметры строки запроса в URI запроса:

$response = $client->request('GET', 'http://httpbin.org?foo=bar');

Параметры строки запроса можно задать с помощью опции запроса query в виде массива.

$client->request('GET', 'http://httpbin.org', [
    'query' => ['foo' => 'bar']
]);

Если предоставить опцию в виде массива, то для форматирования строки запроса будет использоваться функция PHP http_build_query.

И, наконец, вы можете предоставить параметр запроса query в виде строки.

$client->request('GET', 'http://httpbin.org', ['query' => 'foo=bar']);

Загрузка данных¶

Guzzle предоставляет несколько методов для загрузки данных.

Вы можете отправлять запросы, содержащие поток данных, передавая строку,
ресурс, возвращаемый из fopen, или экземпляр файла
PsrHttpMessageStreamInterface в опцию body запроса.

use GuzzleHttpPsr7;

// Provide the body as a string.
$r = $client->request('POST', 'http://httpbin.org/post', [
    'body' => 'raw data'
]);

// Provide an fopen resource.
$body = Psr7Utils::tryFopen('/path/to/file', 'r');
$r = $client->request('POST', 'http://httpbin.org/post', ['body' => $body]);

// Use the Utils::streamFor method to create a PSR-7 stream.
$body = Psr7Utils::streamFor('hello!');
$r = $client->request('POST', 'http://httpbin.org/post', ['body' => $body]);

Простой способ загрузить данные JSON и установить соответствующий заголовок — использовать опцию запроса json:

$r = $client->request('PUT', 'http://httpbin.org/put', [
    'json' => ['foo' => 'bar']
]);

$response = $client->request('POST', 'http://httpbin.org/post', [
    'form_params' => [
        'field_name' => 'abc',
        'other_field' => '123',
        'nested_field' => [
            'nested' => 'hello'
        ]
    ]
]);

use GuzzleHttpPsr7;

$response = $client->request('POST', 'http://httpbin.org/post', [
    'multipart' => [
        [
            'name'     => 'field_name',
            'contents' => 'abc'
        ],
        [
            'name'     => 'file_name',
            'contents' => Psr7Utils::tryFopen('/path/to/file', 'r')
        ],
        [
            'name'     => 'other_file',
            'contents' => 'hello',
            'filename' => 'filename.txt',
            'headers'  => [
                'X-Foo' => 'this is an extra header to include'
            ]
        ]
    ]
]);

Cookies¶

Guzzle может поддерживать сессию cookie для вас, если вы проинструктированы с помощью опции
cookies опцию запроса. При отправке запроса опция cookies
должна быть установлена на экземпляр GuzzleHttpCookieCookieJarInterface.

// Use a specific cookie jar
$jar = new GuzzleHttpCookieCookieJar;
$r = $client->request('GET', 'http://httpbin.org/cookies', [
    'cookies' => $jar
]);

Вы можете установить cookies в true в конструкторе клиента, если вы хотите использовать общий банк cookie для всех запросов.

// Use a shared client cookie jar
$client = new GuzzleHttpClient(['cookies' => true]);
$r = $client->request('GET', 'http://httpbin.org/cookies');

Для GuzzleHttpCookieCookieJarInterface существуют различные реализации:

• Класс GuzzleHttpCookieCookieJar хранит cookies в виде массива.
• Класс GuzzleHttpCookieFileCookieJar сохраняет несеансовые cookies
  используя файл в формате JSON.
• Класс GuzzleHttpCookieSessionCookieJar сохраняет cookies в
  клиентской сессии.

Вы можете вручную установить куки в банку куки с помощью именованного конструктора fromArray(array $cookies, $domain).

$jar = GuzzleHttpCookieCookieJar::fromArray(
    [
        'some_cookie' => 'foo',
        'other_cookie' => 'barbaz1234'
    ],
    'example.org'
);

Вы можете получить cookie по его имени с помощью метода getCookieByName($name), который возвращает экземпляр GuzzleHttpCookieSetCookie.

$cookie = $jar->getCookieByName('some_cookie');

$cookie->getValue(); // 'foo'
$cookie->getDomain(); // 'example.org'
$cookie->getExpires(); // expiration date as a Unix timestamp

Куки также могут быть собраны в массив благодаря методу toArray().
Интерфейс GuzzleHttpCookieCookieJarInterface расширяет.
Traversable, поэтому его можно итерировать в цикле foreach.

Перенаправления¶

Guzzle будет автоматически следовать перенаправлениям, если вы не запретите ему это делать. Вы можете настроить поведение перенаправления с помощью опции запроса allow_redirects.

• Установите значение true, чтобы включить нормальные перенаправления с максимальным числом 5
  перенаправлений. Это значение установлено по умолчанию.
• Установите значение false, чтобы отключить перенаправления.
• Передайте ассоциативный массив, содержащий ключ ‘max’ для указания максимального
  количество перенаправлений и, по желанию, значение ключа ‘strict’ для указания того.
  использовать ли строгие RFC-совместимые перенаправления (то есть перенаправлять POST-запросы с POST-запросами, а не делать то, что делает большинство браузеров).
  запросы с POST-запросами, а не делать то, что делает большинство браузеров, а именно
  перенаправлять POST-запросы с GET-запросами).

$response = $client->request('GET', 'http://github.com');
echo $response->getStatusCode();
// 200

В следующем примере показано, что перенаправления могут быть отключены.

$response = $client->request('GET', 'http://github.com', [
    'allow_redirects' => false
]);
echo $response->getStatusCode();
// 301

Исключения¶

Вид дерева

Следующее древовидное представление описывает, как исключения Guzzle зависят друг от друга.

. RuntimeException
└── TransferException (implements GuzzleException)
    ├── ConnectException (implements NetworkExceptionInterface)
    └── RequestException
        ├── BadResponseException
        │   ├── ServerException
        │   └── ClientException
        └── TooManyRedirectsException

Guzzle выбрасывает исключения для ошибок, возникающих во время передачи.

• Исключение GuzzleHttpExceptionConnectException выбрасывается в случае ошибки подключения к сети.
  в случае ошибки подключения к сети. Это исключение расширяется от
  GuzzleHttpExceptionTransferException.

• Исключение GuzzleHttpExceptionClientException бросается для 400
  уровня, если опция http_errors запроса установлена в true. Этот
  исключение расширяется от GuzzleHttpExceptionBadResponseException и
  GuzzleHttpExceptionBadResponseException расширяется от
  GuzzleHttpExceptionRequestException.

  use GuzzleHttpPsr7;
  use GuzzleHttpExceptionClientException;
  
  try {
      $client->request('GET', 'https://github.com/_abc_123_404');
  } catch (ClientException $e) {
      echo Psr7Message::toString($e->getRequest());
      echo Psr7Message::toString($e->getResponse());
  }
  

• Исключение GuzzleHttpExceptionServerException выбрасывается для 500 уровня
  ошибки, если опция http_errors запроса установлена в true. Этот
  исключение расширяется от GuzzleHttpExceptionBadResponseException.

• Исключение GuzzleHttpExceptionTooManyRedirectsException выбрасывается, когда слишком
  много перенаправлений. Это исключение расширяет GuzzleHttpExceptionRequestException.

Все вышеперечисленные исключения вытекают из GuzzleHttpExceptionTransferException.

Переменные среды¶

Guzzle предоставляет несколько переменных окружения, которые можно использовать для настройки поведения библиотеки.

GUZZLE_CURL_SELECT_TIMEOUT

Контролирует продолжительность в секундах, которую обработчик curl_multi_* будет использовать при
выбора в обработчиках curl с помощью curl_multi_select(). Некоторые системы
имеют проблемы с реализацией PHP curl_multi_select(), где
вызов этой функции всегда приводит к ожиданию максимальной продолжительности
таймаута.

HTTP_PROXY

Определяет прокси-сервер для использования при отправке запросов по протоколу «http»

Примечание: поскольку переменная HTTP_PROXY может содержать произвольный пользовательский ввод в некоторых (CGI) средах, эта переменная используется только в CLI SAPI. См. https://httpoxy.org для получения дополнительной информации.

HTTPS_PROXY

Определяет прокси-сервер, который будет использоваться при отправке запросов по протоколу «https».

NO_PROXY

Определяет URL, для которых не следует использовать прокси. Об использовании см. в proxy.

Creating a Client¶

Clients create requests, send requests, and set responses on a request object. When instantiating a client object,
you can pass an optional «base URL» and optional array of configuration options. A base URL is a
URI template that contains the URL of a remote server. When creating requests with a relative
URL, the base URL of a client will be merged into the request’s URL.

use GuzzleHttpClient;

// Create a client and provide a base URL
$client = new Client('https://api.github.com');

$request = $client->get('/user');
$request->setAuth('user', 'pass');
echo $request->getUrl();
// >>> https://api.github.com/user

// You must send a request in order for the transfer to occur
$response = $request->send();

echo $response->getBody();
// >>> {"type":"User", ...

echo $response->getHeader('Content-Length');
// >>> 792

$data = $response->json();
echo $data['type'];
// >>> User

use GuzzleHttpClient;

$client = new Client('https://api.twitter.com/{version}', array(
    'version'        => 'v1.1',
    'request.options' => array(
        'headers' => array('Foo' => 'Bar'),
        'query'   => array('testing' => '123'),
        'auth'    => array('username', 'password', 'Basic|Digest|NTLM|Any'),
        'proxy'   => 'tcp://localhost:80'
    )
));

// Completely override the default User-Agent
$client->setUserAgent('Test/123');

// Prepend a string to the default User-Agent
$client->setUserAgent('Test/123', true);

Creating requests with a client¶

A Client object exposes several methods used to create Request objects:

• Create a custom HTTP request: $client->createRequest($method, $uri, array $headers, $body, $options)
• Create a GET request: $client->get($uri, array $headers, $options)
• Create a HEAD request: $client->head($uri, array $headers, $options)
• Create a DELETE request: $client->delete($uri, array $headers, $body, $options)
• Create a POST request: $client->post($uri, array $headers, $postBody, $options)
• Create a PUT request: $client->put($uri, array $headers, $body, $options)
• Create a PATCH request: $client->patch($uri, array $headers, $body, $options)

use GuzzleHttpClient;

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

// Create a GET request using Relative to base URL
// URL of the request: http://baseurl.com/api/v1/path?query=123&value=abc)
$request = $client->get('path?query=123&value=abc');
$response = $request->send();

// Create HEAD request using a relative URL with an absolute path
// URL of the request: http://baseurl.com/path?query=123&value=abc
$request = $client->head('/path?query=123&value=abc');
$response = $request->send();

// Create a DELETE request using an absolute URL
$request = $client->delete('http://www.example.com/path?query=123&value=abc');
$response = $request->send();

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

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

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

Client objects create Request objects using a request factory (GuzzleHttpMessageRequestFactoryInterface).
You can inject a custom request factory into the Client using $client->setRequestFactory(), but you can typically
rely on a Client’s default request factory.

Static clients¶

You can use Guzzle’s static client facade to more easily send simple HTTP requests.

// Mount the client so that you can access it at Guzzle
GuzzleHttpStaticClient::mount();
$response = Guzzle::get('http://guzzlephp.org');

Each request method of the static client (e.g. get(), post()`, «put(), etc) accepts an associative array of request
options to apply to the request.

$response = Guzzle::post('http://test.com', array(
    'headers' => array('X-Foo' => 'Bar'),
    'body'    => array('Test' => '123'),
    'timeout' => 10
));

Request options¶

Request options can be specified when creating a request or in the request.options parameter of a client. These
options can control various aspects of a request including: headers to send, query string data, where the response
should be downloaded, proxies, auth, etc.

$request = $client->get($url, array(), array(
    'query' => array('abc' => '123')
));

$client = new GuzzleHttpClient();

// Set a single query string parameter using path syntax
$client->setDefaultOption('query/abc', '123');

// Set an array of default query string parameters
$client->setDefaultOption('query', array('abc' => '123'));

$request = $client->get($url, array(), array(
    'auth' => array('username', 'password', 'Digest')
));

// You can add auth headers to every request of a client
$client->setDefaultOption('auth', array('username', 'password', 'Digest'));

$request = $client->get($url, array(), array(
    'events' => array(
        'request.before_send' => function (GuzzleCommonEvent $e) {
            echo 'About to send ' . $e['request'];
        }
    )
));

// Using the static client:
Guzzle::get($url, array(
    'events' => array(
        'request.before_send' => function (GuzzleCommonEvent $e) {
            echo 'About to send ' . $e['request'];
        }
    )
));

// Using the static client:
Guzzle::get($url, array(
    'plugins' => array(
        new GuzzlePluginCacheCachePlugin(),
        new GuzzlePluginCookieCookiePlugin()
    )
));

$request = $client->get('http://www.example.com', array(), array(
    'timeout'         => 20,
    'connect_timeout' => 1.5
));

$request = $client->get('https://www.example.com', array(), array(
    'cert' => '/etc/pki/client_certificate.pem'
)

$request = $client->get('https://www.example.com', array(), array(
    'cert' => array('/etc/pki/client_certificate.pem', 's3cr3tp455w0rd')
)

$request = $client->get('https://www.example.com', array(), array(
    'ssl_key' => '/etc/pki/private_key.pem'
)

$request = $client->get('https://www.example.com', array(), array(
    'ssl_key' => array('/etc/pki/private_key.pem', 's3cr3tp455w0rd')
)

$stream = Guzzle::get('http://guzzlephp.org', array('stream' => true));
while (!$stream->feof()) {
    echo $stream->readLine();
}

Sending requests¶

Requests can be sent by calling the send() method of a Request object, but you can also send requests using the
send() method of a Client.

$request = $client->get('http://www.amazon.com');
$response = $client->send($request);

use GuzzleCommonExceptionMultiTransferException;

try {
    $responses = $client->send(array(
        $client->get('http://www.google.com/'),
        $client->head('http://www.google.com/'),
        $client->get('https://www.github.com/')
    ));
} catch (MultiTransferException $e) {

    echo "The following exceptions were encountered:n";
    foreach ($e as $exception) {
        echo $exception->getMessage() . "n";
    }

    echo "The following requests failed:n";
    foreach ($e->getFailedRequests() as $request) {
        echo $request . "nn";
    }

    echo "The following requests succeeded:n";
    foreach ($e->getSuccessfulRequests() as $request) {
        echo $request . "nn";
    }
}

Plugins and events¶

Guzzle provides easy to use request plugins that add behavior to requests based on signal slot event notifications
powered by the
Symfony2 Event Dispatcher component. Any
event listener or subscriber attached to a Client object will automatically be attached to each request created by the
client.

use GuzzlePluginCookieCookiePlugin;
use GuzzlePluginCookieCookieJarArrayCookieJar;

// Create a new cookie plugin
$cookiePlugin = new CookiePlugin(new ArrayCookieJar());

// Add the cookie plugin to the client
$client->addSubscriber($cookiePlugin);

use GuzzleCommonEvent;
use GuzzleHttpClient;

$client = new Client();

// Add a listener that will echo out requests as they are created
$client->getEventDispatcher()->addListener('client.create_request', function (Event $e) {
    echo 'Client object: ' . spl_object_hash($e['client']) . "n";
    echo "Request object: {$e['request']}n";
});

Version

HTTP Client

• Introduction
• Making Requests
  • Request Data
  • Headers
  • Authentication
  • Timeout
  • Retries
  • Error Handling
  • Guzzle Middleware
  • Guzzle Options
• Concurrent Requests
• Macros
• Testing
  • Faking Responses
  • Inspecting Requests
  • Preventing Stray Requests
• Events

Introduction

Laravel provides an expressive, minimal API around the Guzzle HTTP client, allowing you to quickly make outgoing HTTP requests to communicate with other web applications. Laravel’s wrapper around Guzzle is focused on its most common use cases and a wonderful developer experience.

Before getting started, you should ensure that you have installed the Guzzle package as a dependency of your application. By default, Laravel automatically includes this dependency. However, if you have previously removed the package, you may install it again via Composer:

composer require guzzlehttp/guzzle

Making Requests

To make requests, you may use the head, get, post, put, patch, and delete methods provided by the Http facade. First, let’s examine how to make a basic GET request to another URL:

use IlluminateSupportFacadesHttp;
$response = Http::get('http://example.com');

The get method returns an instance of IlluminateHttpClientResponse, which provides a variety of methods that may be used to inspect the response:

$response->body() : string;
$response->json($key = null, $default = null) : array|mixed;



  


                       
  



$response->object() : object;
$response->collect($key = null) : IlluminateSupportCollection;
$response->status() : int;
$response->successful() : bool;
$response->redirect(): bool;
$response->failed() : bool;
$response->clientError() : bool;
$response->header($header) : string;
$response->headers() : array;

The IlluminateHttpClientResponse object also implements the PHP ArrayAccess interface, allowing you to access JSON response data directly on the response:

return Http::get('http://example.com/users/1')['name'];

In addition to the response methods listed above, the following methods may be used to determine if the response has a given status code:

$response->ok() : bool;                  // 200 OK
$response->created() : bool;             // 201 Created
$response->accepted() : bool;            // 202 Accepted
$response->noContent() : bool;           // 204 No Content
$response->movedPermanently() : bool;    // 301 Moved Permanently
$response->found() : bool;               // 302 Found
$response->badRequest() : bool;          // 400 Bad Request
$response->unauthorized() : bool;        // 401 Unauthorized



  


                       
  



$response->paymentRequired() : bool;     // 402 Payment Required
$response->forbidden() : bool;           // 403 Forbidden
$response->notFound() : bool;            // 404 Not Found
$response->requestTimeout() : bool;      // 408 Request Timeout
$response->conflict() : bool;            // 409 Conflict
$response->unprocessableEntity() : bool; // 422 Unprocessable Entity
$response->tooManyRequests() : bool;     // 429 Too Many Requests
$response->serverError() : bool;         // 500 Internal Server Error

URI Templates

The HTTP client also allows you to construct request URLs using the URI template specification. To define the URL parameters that can be expanded by your URI template, you may use the withUrlParameters method:

Http::withUrlParameters([



  


                       
  



    'endpoint' => 'https://laravel.com',
    'page' => 'docs',
    'version' => '9.x',
    'topic' => 'validation',
])->get('{+endpoint}/{page}/{version}/{topic}');

Dumping Requests

If you would like to dump the outgoing request instance before it is sent and terminate the script’s execution, you may add the dd method to the beginning of your request definition:

return Http::dd()->get('http://example.com');

Request Data

Of course, it is common when making POST, PUT, and PATCH requests to send additional data with your request, so these methods accept an array of data as their second argument. By default, data will be sent using the application/json content type:

use IlluminateSupportFacadesHttp;
$response = Http::post('http://example.com/users', [



  


                       
  



    'name' => 'Steve',
    'role' => 'Network Administrator',
]);

GET Request Query Parameters

When making GET requests, you may either append a query string to the URL directly or pass an array of key / value pairs as the second argument to the get method:

$response = Http::get('http://example.com/users', [
    'name' => 'Taylor',
    'page' => 1,
]);

Sending Form URL Encoded Requests

If you would like to send data using the application/x-www-form-urlencoded content type, you should call the asForm method before making your request:

$response = Http::asForm()->post('http://example.com/users', [



  


                       
  



    'name' => 'Sara',
    'role' => 'Privacy Consultant',
]);

Sending A Raw Request Body

You may use the withBody method if you would like to provide a raw request body when making a request. The content type may be provided via the method’s second argument:

$response = Http::withBody(
    base64_encode($photo), 'image/jpeg'
)->post('http://example.com/photo');

Multi-Part Requests

If you would like to send files as multi-part requests, you should call the attach method before making your request. This method accepts the name of the file and its contents. If needed, you may provide a third argument which will be considered the file’s filename:

$response = Http::attach(
    'attachment', file_get_contents('photo.jpg'), 'photo.jpg'
)->post('http://example.com/attachments');

Instead of passing the raw contents of a file, you may pass a stream resource:

$photo = fopen('photo.jpg', 'r');
$response = Http::attach(
    'attachment', $photo, 'photo.jpg'
)->post('http://example.com/attachments');

Headers

Headers may be added to requests using the withHeaders method. This withHeaders method accepts an array of key / value pairs:

$response = Http::withHeaders([
    'X-First' => 'foo',
    'X-Second' => 'bar'
])->post('http://example.com/users', [
    'name' => 'Taylor',
]);

You may use the accept method to specify the content type that your application is expecting in response to your request:

$response = Http::accept('application/json')->get('http://example.com/users');

For convenience, you may use the acceptJson method to quickly specify that your application expects the application/json content type in response to your request:

$response = Http::acceptJson()->get('http://example.com/users');

Authentication

You may specify basic and digest authentication credentials using the withBasicAuth and withDigestAuth methods, respectively:

// Basic authentication...
$response = Http::withBasicAuth('[email protected]', 'secret')->post(/* ... */);
// Digest authentication...
$response = Http::withDigestAuth('[email protected]', 'secret')->post(/* ... */);

Bearer Tokens

If you would like to quickly add a bearer token to the request’s Authorization header, you may use the withToken method:

$response = Http::withToken('token')->post(/* ... */);

Timeout

The timeout method may be used to specify the maximum number of seconds to wait for a response:

$response = Http::timeout(3)->get(/* ... */);

If the given timeout is exceeded, an instance of IlluminateHttpClientConnectionException will be thrown.

You may specify the maximum number of seconds to wait while trying to connect to a server using the connectTimeout method:

$response = Http::connectTimeout(3)->get(/* ... */);

Retries

If you would like the HTTP client to automatically retry the request if a client or server error occurs, you may use the retry method. The retry method accepts the maximum number of times the request should be attempted and the number of milliseconds that Laravel should wait in between attempts:

$response = Http::retry(3, 100)->post(/* ... */);

If needed, you may pass a third argument to the retry method. The third argument should be a callable that determines if the retries should actually be attempted. For example, you may wish to only retry the request if the initial request encounters an ConnectionException:

$response = Http::retry(3, 100, function ($exception, $request) {
    return $exception instanceof ConnectionException;
})->post(/* ... */);

If a request attempt fails, you may wish to make a change to the request before a new attempt is made. You can achieve this by modifying the request argument provided to the callable you provided to the retry method. For example, you might want to retry the request with a new authorization token if the first attempt returned an authentication error:

$response = Http::withToken($this->getToken())->retry(2, 0, function ($exception, $request) {
    if (! $exception instanceof RequestException || $exception->response->status() !== 401) {
        return false;
    }
    $request->withToken($this->getNewToken());
    return true;
})->post(/* ... */);

If all of the requests fail, an instance of IlluminateHttpClientRequestException will be thrown. If you would like to disable this behavior, you may provide a throw argument with a value of false. When disabled, the last response received by the client will be returned after all retries have been attempted:

$response = Http::retry(3, 100, throw: false)->post(/* ... */);

Warning
If all of the requests fail because of a connection issue, a IlluminateHttpClientConnectionException will still be thrown even when the throw argument is set to false.

Error Handling

Unlike Guzzle’s default behavior, Laravel’s HTTP client wrapper does not throw exceptions on client or server errors (400 and 500 level responses from servers). You may determine if one of these errors was returned using the successful, clientError, or serverError methods:

// Determine if the status code is >= 200 and < 300...
$response->successful();
// Determine if the status code is >= 400...
$response->failed();
// Determine if the response has a 400 level status code...
$response->clientError();
// Determine if the response has a 500 level status code...
$response->serverError();
// Immediately execute the given callback if there was a client or server error...
$response->onError(callable $callback);

Throwing Exceptions

If you have a response instance and would like to throw an instance of IlluminateHttpClientRequestException if the response status code indicates a client or server error, you may use the throw or throwIf methods:

$response = Http::post(/* ... */);
// Throw an exception if a client or server error occurred...
$response->throw();
// Throw an exception if an error occurred and the given condition is true...
$response->throwIf($condition);
// Throw an exception if an error occurred and the given closure resolves to true...
$response->throwIf(fn ($response) => true);
// Throw an exception if an error occurred and the given condition is false...
$response->throwUnless($condition);
// Throw an exception if an error occurred and the given closure resolves to false...
$response->throwUnless(fn ($response) => false);
// Throw an exception if the response has a specific status code...
$response->throwIfStatus(403);
// Throw an exception unless the response has a specific status code...
$response->throwUnlessStatus(200);
return $response['user']['id'];

The IlluminateHttpClientRequestException instance has a public $response property which will allow you to inspect the returned response.

The throw method returns the response instance if no error occurred, allowing you to chain other operations onto the throw method:

return Http::post(/* ... */)->throw()->json();

If you would like to perform some additional logic before the exception is thrown, you may pass a closure to the throw method. The exception will be thrown automatically after the closure is invoked, so you do not need to re-throw the exception from within the closure:

return Http::post(/* ... */)->throw(function ($response, $e) {
    //
})->json();

Guzzle Middleware

Since Laravel’s HTTP client is powered by Guzzle, you may take advantage of Guzzle Middleware to manipulate the outgoing request or inspect the incoming response. To manipulate the outgoing request, register a Guzzle middleware via the withMiddleware method in combination with Guzzle’s mapRequest middleware factory:

use GuzzleHttpMiddleware;
use IlluminateSupportFacadesHttp;
use PsrHttpMessageRequestInterface;
$response = Http::withMiddleware(
    Middleware::mapRequest(function (RequestInterface $request) {
        $request = $request->withHeader('X-Example', 'Value');
        return $request;
    })
)->get('http://example.com');

Likewise, you can inspect the incoming HTTP response by registering a middleware via the withMiddleware method in combination with Guzzle’s mapResponse middleware factory:

use GuzzleHttpMiddleware;
use IlluminateSupportFacadesHttp;
use PsrHttpMessageResponseInterface;
$response = Http::withMiddleware(
    Middleware::mapResponse(function (ResponseInterface $response) {
        $header = $response->getHeader('X-Example');
        // ...
        return $response;
    })
)->get('http://example.com');

Guzzle Options

You may specify additional Guzzle request options using the withOptions method. The withOptions method accepts an array of key / value pairs:

$response = Http::withOptions([
    'debug' => true,
])->get('http://example.com/users');

Concurrent Requests

Sometimes, you may wish to make multiple HTTP requests concurrently. In other words, you want several requests to be dispatched at the same time instead of issuing the requests sequentially. This can lead to substantial performance improvements when interacting with slow HTTP APIs.

Thankfully, you may accomplish this using the pool method. The pool method accepts a closure which receives an IlluminateHttpClientPool instance, allowing you to easily add requests to the request pool for dispatching:

use IlluminateHttpClientPool;
use IlluminateSupportFacadesHttp;
$responses = Http::pool(fn (Pool $pool) => [
    $pool->get('http://localhost/first'),
    $pool->get('http://localhost/second'),
    $pool->get('http://localhost/third'),
]);
return $responses[0]->ok() &&
       $responses[1]->ok() &&
       $responses[2]->ok();

As you can see, each response instance can be accessed based on the order it was added to the pool. If you wish, you can name the requests using the as method, which allows you to access the corresponding responses by name:

use IlluminateHttpClientPool;
use IlluminateSupportFacadesHttp;
$responses = Http::pool(fn (Pool $pool) => [
    $pool->as('first')->get('http://localhost/first'),
    $pool->as('second')->get('http://localhost/second'),
    $pool->as('third')->get('http://localhost/third'),
]);
return $responses['first']->ok();

Macros

The Laravel HTTP client allows you to define «macros», which can serve as a fluent, expressive mechanism to configure common request paths and headers when interacting with services throughout your application. To get started, you may define the macro within the boot method of your application’s AppProvidersAppServiceProvider class:

use IlluminateSupportFacadesHttp;
/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    Http::macro('github', function () {
        return Http::withHeaders([
            'X-Example' => 'example',
        ])->baseUrl('https://github.com');
    });
}

Once your macro has been configured, you may invoke it from anywhere in your application to create a pending request with the specified configuration:

$response = Http::github()->get('/');

Testing

Many Laravel services provide functionality to help you easily and expressively write tests, and Laravel’s HTTP client is no exception. The Http facade’s fake method allows you to instruct the HTTP client to return stubbed / dummy responses when requests are made.

Faking Responses

For example, to instruct the HTTP client to return empty, 200 status code responses for every request, you may call the fake method with no arguments:

use IlluminateSupportFacadesHttp;
Http::fake();
$response = Http::post(/* ... */);

Faking Specific URLs

Alternatively, you may pass an array to the fake method. The array’s keys should represent URL patterns that you wish to fake and their associated responses. The * character may be used as a wildcard character. Any requests made to URLs that have not been faked will actually be executed. You may use the Http facade’s response method to construct stub / fake responses for these endpoints:

Http::fake([
    // Stub a JSON response for GitHub endpoints...
    'github.com/*' => Http::response(['foo' => 'bar'], 200, $headers),
    // Stub a string response for Google endpoints...
    'google.com/*' => Http::response('Hello World', 200, $headers),
]);

If you would like to specify a fallback URL pattern that will stub all unmatched URLs, you may use a single * character:

Http::fake([
    // Stub a JSON response for GitHub endpoints...
    'github.com/*' => Http::response(['foo' => 'bar'], 200, ['Headers']),
    // Stub a string response for all other endpoints...
    '*' => Http::response('Hello World', 200, ['Headers']),
]);

Faking Response Sequences

Sometimes you may need to specify that a single URL should return a series of fake responses in a specific order. You may accomplish this using the Http::sequence method to build the responses:

Http::fake([
    // Stub a series of responses for GitHub endpoints...
    'github.com/*' => Http::sequence()
                            ->push('Hello World', 200)
                            ->push(['foo' => 'bar'], 200)
                            ->pushStatus(404),
]);

When all the responses in a response sequence have been consumed, any further requests will cause the response sequence to throw an exception. If you would like to specify a default response that should be returned when a sequence is empty, you may use the whenEmpty method:

Http::fake([
    // Stub a series of responses for GitHub endpoints...
    'github.com/*' => Http::sequence()
                            ->push('Hello World', 200)
                            ->push(['foo' => 'bar'], 200)
                            ->whenEmpty(Http::response()),
]);

If you would like to fake a sequence of responses but do not need to specify a specific URL pattern that should be faked, you may use the Http::fakeSequence method:

Http::fakeSequence()
        ->push('Hello World', 200)
        ->whenEmpty(Http::response());

Fake Callback

If you require more complicated logic to determine what responses to return for certain endpoints, you may pass a closure to the fake method. This closure will receive an instance of IlluminateHttpClientRequest and should return a response instance. Within your closure, you may perform whatever logic is necessary to determine what type of response to return:

use IlluminateHttpClientRequest;
Http::fake(function (Request $request) {
    return Http::response('Hello World', 200);
});

Preventing Stray Requests

If you would like to ensure that all requests sent via the HTTP client have been faked throughout your individual test or complete test suite, you can call the preventStrayRequests method. After calling this method, any requests that do not have a corresponding fake response will throw an exception rather than making the actual HTTP request:

use IlluminateSupportFacadesHttp;
Http::preventStrayRequests();
Http::fake([
    'github.com/*' => Http::response('ok'),
]);
// An "ok" response is returned...
Http::get('https://github.com/laravel/framework');
// An exception is thrown...
Http::get('https://laravel.com');

Inspecting Requests

When faking responses, you may occasionally wish to inspect the requests the client receives in order to make sure your application is sending the correct data or headers. You may accomplish this by calling the Http::assertSent method after calling Http::fake.

The assertSent method accepts a closure which will receive an IlluminateHttpClientRequest instance and should return a boolean value indicating if the request matches your expectations. In order for the test to pass, at least one request must have been issued matching the given expectations:

use IlluminateHttpClientRequest;
use IlluminateSupportFacadesHttp;
Http::fake();
Http::withHeaders([
    'X-First' => 'foo',
])->post('http://example.com/users', [
    'name' => 'Taylor',
    'role' => 'Developer',
]);
Http::assertSent(function (Request $request) {
    return $request->hasHeader('X-First', 'foo') &&
           $request->url() == 'http://example.com/users' &&
           $request['name'] == 'Taylor' &&
           $request['role'] == 'Developer';
});

If needed, you may assert that a specific request was not sent using the assertNotSent method:

use IlluminateHttpClientRequest;
use IlluminateSupportFacadesHttp;
Http::fake();
Http::post('http://example.com/users', [
    'name' => 'Taylor',
    'role' => 'Developer',
]);
Http::assertNotSent(function (Request $request) {
    return $request->url() === 'http://example.com/posts';
});

You may use the assertSentCount method to assert how many requests were «sent» during the test:

Http::fake();
Http::assertSentCount(5);

Or, you may use the assertNothingSent method to assert that no requests were sent during the test:

Http::fake();
Http::assertNothingSent();

Recording Requests / Responses

You may use the recorded method to gather all requests and their corresponding responses. The recorded method returns a collection of arrays that contains instances of IlluminateHttpClientRequest and IlluminateHttpClientResponse:

Http::fake([
    'https://laravel.com' => Http::response(status: 500),
    'https://nova.laravel.com/' => Http::response(),
]);
Http::get('https://laravel.com');
Http::get('https://nova.laravel.com/');
$recorded = Http::recorded();
[$request, $response] = $recorded[0];

Additionally, the recorded method accepts a closure which will receive an instance of IlluminateHttpClientRequest and IlluminateHttpClientResponse and may be used to filter request / response pairs based on your expectations:

use IlluminateHttpClientRequest;
use IlluminateHttpClientResponse;
Http::fake([
    'https://laravel.com' => Http::response(status: 500),
    'https://nova.laravel.com/' => Http::response(),
]);
Http::get('https://laravel.com');
Http::get('https://nova.laravel.com/');
$recorded = Http::recorded(function (Request $request, Response $response) {
    return $request->url() !== 'https://laravel.com' &&
           $response->successful();
});

Events

Laravel fires three events during the process of sending HTTP requests. The RequestSending event is fired prior to a request being sent, while the ResponseReceived event is fired after a response is received for a given request. The ConnectionFailed event is fired if no response is received for a given request.

The RequestSending and ConnectionFailed events both contain a public $request property that you may use to inspect the IlluminateHttpClientRequest instance. Likewise, the ResponseReceived event contains a $request property as well as a $response property which may be used to inspect the IlluminateHttpClientResponse instance. You may register event listeners for this event in your AppProvidersEventServiceProvider service provider:

/**
 * The event listener mappings for the application.
 *
 * @var array
 */
protected $listen = [
    'IlluminateHttpClientEventsRequestSending' => [
        'AppListenersLogRequestSending',
    ],
    'IlluminateHttpClientEventsResponseReceived' => [
        'AppListenersLogResponseReceived',
    ],
    'IlluminateHttpClientEventsConnectionFailed' => [
        'AppListenersLogConnectionFailed',
    ],
];

Related