Настройка клиента
Клиент собирается цепочкой with*() один раз — обычно при старте приложения или в бине —
и дальше только отправляет запросы.
Создание
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. Повторно он не добавляется.
Размер ответа
$client->withMaxResponseSize(50 * 1024 * 1024); // 50 МиБ
$client->withMaxResponseSize(null); // без ограниченияОграничение — 10 МиБ — действует на тело, которое держится в памяти. Ответ больше даёт
TooLargeException: по Content-Length сразу, без скачивания, иначе — как только
принятые байты превысят предел. На скачивание в файл (sinkTo()) ограничение не
действует.
Почему 10 МиБ
json() превращает тело в массив, а массив занимает в 5–10 раз больше памяти, чем JSON.
Ответ API больше 10 МиБ почти всегда либо выгрузка (её место — sinkTo()), либо ошибка
вроде сломанной пагинации. Лучше узнать об этом сразу.
Свои опции cURL
Прокси, сертификаты, привязка к интерфейсу — через withCurlOptions():
$client->withCurlOptions([
CURLOPT_PROXY => 'http://proxy.internal:3128',
CURLOPT_CAINFO => '/etc/ssl/internal-ca.pem',
]);Опции, на которых держится сама библиотека (адрес, метод, заголовки, тело, обратные
вызовы, редиректы), задать нельзя: будет InvalidArgumentException с подсказкой, каким
методом это делается. Полный список — CurlTransport::RESERVED.
Несколько клиентов от одного
Клиент неизменяем, поэтому от общего удобно делать частные:
$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 заменяет на ***.