Пакет · cast

Настройка клиента

Клиент собирается цепочкой with*() один раз — обычно при старте приложения или в бине — и дальше только отправляет запросы.

Создание

php
use Flytachi\Winter\Cast\Client\CastClient;

$client = CastClient::create()             // то же, что new CastClient()
  ->withBaseUrl('https://api.example.com/v1')
  ->withHeaders(['Accept' => 'application/json', 'X-Tenant' => 'acme'])
  ->withBearerToken($token)
  ->withUserAgent('billing/2.3')
  ->withTimeout(10);

Без настроек клиент уже рабочий: соединение 5 с, попытка 30 с, без повторов, до 10 редиректов, тело в памяти до 10 МиБ.

Базовый адрес

Относительный путь запроса дописывается к базовому адресу:

База Путь Итог
https://api.com users/42 https://api.com/users/42
https://api.com/v1 users https://api.com/v1/users
https://api.com/v1/ /users https://api.com/v1/users
https://api.com/v1?key=1 users?page=2 https://api.com/v1/users?key=1&page=2

Это не разрешение адресов по RFC 3986: по нему https://api.com/v1 + users дало бы https://api.com/users, и сегмент v1 молча пропал бы. Абсолютный адрес в запросе используется как есть, базовый к нему не применяется.

Без базового адреса относительный путь — ошибка RequestException при отправке.

Заголовки по умолчанию

Метод Что делает
withHeader($name, $value) задать один (значение — строка или список)
withHeaders([...]) задать несколько; одноимённые заменяются, остальные остаются
withAddedHeader($name, $value) добавить значение к существующему
withoutHeader($name) убрать
withBearerToken($token) Authorization: Bearer …
withBasicAuth($user, $password) Authorization: Basic …
withAccept(...$types) Accept: a, b

Имена регистронезависимы: content-type и Content-Type — один заголовок, отправляется написание, заданное последним. Заголовок запроса с тем же именем заменяет заголовок клиента.

Заголовки, которые вычисляются на каждый запрос (X-Request-ID, подпись), задаются через middleware.

User-Agent

Настройка Отправляется
ничего WinterCast/2.0.0 curl/8.11.0
withUserAgent('billing/2.3') billing/2.3 WinterCast/2.0.0 curl/8.11.0
withUserAgent('billing/2.3', exact: true) billing/2.3

Ваш агент идёт первым (RFC 9110 рекомендует от главного к второстепенному). Суффикс добавляется последним, при отправке, поэтому его получает и агент, поставленный в middleware. Повторно он не добавляется.

Размер ответа

php
$client->withMaxResponseSize(50 * 1024 * 1024);   // 50 МиБ
$client->withMaxResponseSize(null);               // без ограничения

Ограничение — 10 МиБ — действует на тело, которое держится в памяти. Ответ больше даёт TooLargeException: по Content-Length сразу, без скачивания, иначе — как только принятые байты превысят предел. На скачивание в файл (sinkTo()) ограничение не действует.

Почему 10 МиБ

json() превращает тело в массив, а массив занимает в 5–10 раз больше памяти, чем JSON. Ответ API больше 10 МиБ почти всегда либо выгрузка (её место — sinkTo()), либо ошибка вроде сломанной пагинации. Лучше узнать об этом сразу.

Свои опции cURL

Прокси, сертификаты, привязка к интерфейсу — через withCurlOptions():

php
$client->withCurlOptions([
  CURLOPT_PROXY => 'http://proxy.internal:3128',
  CURLOPT_CAINFO => '/etc/ssl/internal-ca.pem',
]);

Опции, на которых держится сама библиотека (адрес, метод, заголовки, тело, обратные вызовы, редиректы), задать нельзя: будет InvalidArgumentException с подсказкой, каким методом это делается. Полный список — CurlTransport::RESERVED.

Несколько клиентов от одного

Клиент неизменяем, поэтому от общего удобно делать частные:

php
$base = CastClient::create()->withUserAgent('billing/2.3')->withTimeout(10);

$github = $base->withBaseUrl('https://api.github.com')->withBearerToken($githubToken);
$stripe = $base->withBaseUrl('https://api.stripe.com/v1')->withBasicAuth($stripeKey, '');

Все трое делят один пул соединений.

Чтение настроек

getBaseUrl(), getHeaders(), getTimeouts(), getRetryPolicy(), getRedirects(), getMiddleware() — для отладки и тестов. var_dump($client) показывает настройки, а значения Authorization, Proxy-Authorization, Cookie и X-Api-Key заменяет на ***.