Клієнт HTTP

• Вступ
• View запитів
  • Запит даних
  • Заголовки
  • Аутентифікація
  • Timeout
  • Повторні спроби
  • Обробка помилок
  • Options Guzzle
• Тестування
  • Фейкові відповіді
  • Перевірка запитів

Вступ

Laravel забезпечує виразний, мінімальний API навколоGuzzle HTTP-клієнт, що дозволяє швидко робити вихідні HTTP-запити для спілкування з іншими веб-програмами. Обгортка Laravel навколо Guzzle орієнтована на найпоширеніші випадки використання та чудовий досвід розробника.

Перед початком роботи переконайтесь, що ви встановили пакет Guzzle як залежність вашої програми. За замовчуванням Laravel автоматично включає таку залежність:

composer require guzzlehttp/guzzle

View запитів

Для надсилання запитів ви можете використовуватиget,post,put,patch, іdeleteметоди. Спочатку розглянемо, як скласти базовийGETзапит:

use Illuminate\Support\Facades\Http;

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

getметод повертає екземплярIlluminate\Http\Client\Response, який надає різноманітні методи, які можуть бути використані для перевірки реакції:

$response->body() : string;
$response->json() : array|mixed;
$response->status() : int;
$response->ok() : bool;
$response->successful() : bool;
$response->failed() : bool;
$response->serverError() : bool;
$response->clientError() : bool;
$response->header($header) : string;
$response->headers() : array;

Illuminate\Http\Client\Responseоб'єкт також реалізує PHPArrayAccessінтерфейс, що дозволяє отримати доступ до даних відповідей JSON безпосередньо у відповіді:

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

Запит даних

Звичайно, це часто при використанніPOST,PUT, іPATCHщоб надіслати додаткові дані разом із вашим запитом. Отже, ці методи приймають масив даних як другий аргумент. За замовчуванням дані надсилатимуться за допомогоюapplication/jsonтип вмісту:

$response = Http::post('http://example.com/users', [
    'name' => 'Steve',
    'role' => 'Network Administrator',
]);

ОТРИМАТИ параметри запиту запиту

При виготовленніGETзапити, ви можете або додати рядок запиту до URL-адреси, або передати масив пар ключ / значення як другий аргумент доgetметод:

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

Надсилання зашифрованих запитів URL-адреси форми

Якщо ви хочете надіслати дані за допомогоюapplication/x-www-form-urlencodedтипу вмісту, вам слід зателефонувати доasFormметод перед Viewм запиту:

$response = Http::asForm()->post('http://example.com/users', [
    'name' => 'Sara',
    'role' => 'Privacy Consultant',
]);

Надсилання основного запиту

Ви можете використовуватиwithBodyметод, якщо ви хочете надати необроблений текст запиту під час надсилання запиту:

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

Багатокомпонентні запити

Якщо ви хочете надіслати файли як багатокомпонентні запити, вам слід зателефонувати доattachметод перед Viewм запиту. Цей метод приймає ім'я файлу та його вміст. За бажанням ви можете надати третій аргумент, який буде вважатись ім’ям файлу:

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

Замість передачі необробленого вмісту файлу ви також можете передати потоковий ресурс:

$photo = fopen('photo.jpg', 'r');

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

Заголовки

Заголовки можна додавати до запитів за допомогоюwithHeadersметод. ЦеwithHeadersметод приймає масив пар ключ / значення:

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

Аутентифікація

Ви можете вказати основні та дайджест-ідентифікаційні дані, використовуючиwithBasicAuthіwithDigestAuthметодів, відповідно:

// Basic authentication...
$response = Http::withBasicAuth('taylor@laravel.com', 'secret')->post(...);

// Digest authentication...
$response = Http::withDigestAuth('taylor@laravel.com', 'secret')->post(...);

Жетони на пред'явника

Якщо ви хочете швидко додатиAuthorizationЗаголовок токена на пред'явника до запиту, ви можете використовуватиwithTokenметод:

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

Timeout

timeoutметод може бути використаний для вказівки максимальної кількості секунд очікування відповіді:

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

Якщо вказаний тайм-аут перевищено, екземплярIlluminate\Http\Client\ConnectionExceptionбуде кинуто.

Повторні спроби

Якщо ви хочете, щоб клієнт HTTP автоматично повторив запит, якщо сталася помилка клієнта або сервера, ви можете використовуватиretryметод.retryметод приймає два аргументи: кількість спроб запиту та кількість мілісекунд, протягом яких Laravel повинен чекати між спробами:

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

Якщо всі запити не вдаються, екземплярIlluminate\Http\Client\RequestExceptionбуде кинуто.

Обробка помилок

На відміну від поведінки Guzzle за замовчуванням, клієнтська обгортка Laravel не створює винятків щодо помилок клієнта або сервера (400і500відповіді рівня від серверів). Ви можете визначити, чи була повернута одна з цих помилок за допомогоюsuccessful,clientError, абоserverErrorметоди:

// Determine if the status code was >= 200 and < 300...
$response->successful();

// Determine if the status code was >= 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();

Кидання винятків

Якщо у вас є екземпляр відповіді і ви хочете викинути екземплярIlluminate\Http\Client\RequestExceptionякщо відповідь - помилка клієнта або сервера, ви можете використовуватиthrowметод:

$response = Http::post(...);

// Throw an exception if a client or server error occurred...
$response->throw();

return $response['user']['id'];

Illuminate\Http\Client\RequestExceptionінстанція має паблік$responseвластивість, що дозволить перевірити повернуту відповідь.

throwметод повертає екземпляр відповіді, якщо помилки не сталося, дозволяючи зв'язати інші операції зthrowметод:

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

Якщо ви хочете виконати деяку додаткову логіку до того, як буде вилучено виняток, ви можете передати Закриття вthrowметод. Виняток буде автоматично видано після виклику Закриття, тому Вам не потрібно повторно викидати виняток із Закриття:

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

Options Guzzle

Ви можете вказати додатковіПараметри запиту Guzzleза допомогоюwithOptionsметод.withOptionsметод приймає масив пар ключ / значення:

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

Тестування

Багато служб Laravel забезпечують функціональність, яка допоможе вам легко та виразно писати тести, і обгортка HTTP від ​​Laravel не є винятком.HttpфасадніfakeМетод дозволяє вказувати клієнтові HTTP повертати тактові / фіктивні відповіді під час надсилання запитів.

Фейкові відповіді

Наприклад, щоб доручити клієнту HTTP повертати порожнє,200відповіді коду стану на кожен запит, ви можете зателефонувати доfakeметод без аргументів:

use Illuminate\Support\Facades\Http;

Http::fake();

$response = Http::post(...);

При підробці запитів клієнтське програмне забезпечення HTTP не виконується. Ви повинні визначити очікування щодо фальшивих відповідей, ніби це Middlware працювало правильно.

Підробка конкретних URL-адрес

Крім того, ви можете передати масив доfakeметод. Ключі масиву повинні представляти шаблони URL-адрес, які ви хочете підробити, та відповідні відповіді.*символ може використовуватися як символ підстановки. Будь-які запити на URL-адреси, які не були сфальсифікованими, насправді будуть виконані. Ви можете використовуватиresponseметод побудови заглушених / підроблених відповідей для цих кінцевих точок:

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

Якщо ви хочете вказати резервний шаблон URL-адреси, який буде заглушати всі нерівні URL-адреси, ви можете використовувати один*характер:

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

Підроблені послідовності відповідей

Іноді може знадобитися вказати, що одна URL-адреса повинна повертати ряд фальшивих відповідей у ​​певному порядку. Ви можете досягти цього за допомогоюHttp::sequenceметод побудови відповідей:

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

Коли всі відповіді в послідовності відповідей будуть використані, будь-які подальші запити змусять послідовність відповідей викликати виняток. Якщо ви хочете вказати відповідь за замовчуванням, яку слід повертати, коли послідовність порожня, ви можете використовуватиwhenEmptyметод:

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()),
]);

Якщо ви хочете сфальсифікувати послідовність відповідей, але вам не потрібно вказувати конкретний шаблон URL-адреси, який слід сфальсифікувати, ви можете використовуватиHttp::fakeSequenceметод:

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

Підроблений зворотний дзвінок

Якщо вам потрібна більш складна логіка для визначення того, які відповіді повертати для певних кінцевих точок, ви можете передати зворотний дзвінок доfakeметод. Цей зворотний дзвінок отримає екземплярIlluminate\Http\Client\Requestі повинен повернути екземпляр відповіді:

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

Перевірка запитів

Підробляючи відповіді, ви можете іноді побажати перевірити запити, які отримує клієнт, щоб переконатися, що ваша програма надсилає правильні дані або заголовки. Ви можете досягти цього, зателефонувавши доHttp::assertSentметод після викликуHttp::fake.

The assertSentметод приймає зворотний виклик, який отримаєIlluminate\Http\Client\Requestекземпляр і повинен повернути логічне значення, яке вказує, чи відповідає запит вашим очікуванням. Щоб тест міг пройти, повинен бути виданий принаймні один запит, що відповідає заданим очікуванням:

Http::fake();

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

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

Якщо потрібно, ви можете стверджувати, що конкретний запит не було надіслано за допомогоюassertNotSentметод:

Http::fake();

Http::post('http://example.com/users', [
    'name' => 'Taylor',
    'role' => 'Developer',
]);

Http::assertNotSent(function (Request $request) {
    return $request->url() === 'http://example.com/posts';
});

Або, якщо ви хочете стверджувати, що жодних запитів не надсилали, ви можете використовуватиassertNothingSentметод:

Http::fake();

Http::assertNothingSent();