Пакет · cast

Модель работы

В Cast три главных объекта: клиент хранит настройки, запрос описывает одну отправку, ответ отдаёт результат. Всё остальное — настройки (таймауты, повторы, редиректы) и точки расширения (middleware, транспорт).

Три объекта

Объект Что это Стандарт
CastClient настройки и отправка: базовый адрес, заголовки, таймауты, повторы, middleware PSR-18 ClientInterface
CastRequest один запрос: метод, адрес, заголовки, тело и свои настройки отправки PSR-7 RequestInterface
CastResponse ответ: статус, заголовки, тело и сведения о передаче PSR-7 ResponseInterface

Тело запроса и ответа — поток CastStream (PSR-7 StreamInterface), адрес — CastUri.

Всё неизменяемо

Каждый with*() возвращает новый объект, исходный не меняется:

php
$base = CastClient::create()->withBaseUrl('https://api.example.com');
$admin = $base->withBearerToken($adminToken);   // $base остался без токена

Поэтому клиент можно хранить в бине, передавать в сервисы и использовать из многих корутин: никто не изменит его настройки «на лету». Копии делят один пул соединений.

Запрос привязан к клиенту

$client->get(), post() и другие создают запрос, который помнит свой клиент. Метод send() отправляет его через этот клиент:

php
$client->get('users/42')->withHeader('X-Trace', $id)->send();
// то же самое:
$client->send(CastRequest::get('users/42')->withHeader('X-Trace', $id));

Запрос, созданный без клиента (CastRequest::get()), при send() уходит через клиент по умолчанию фасада Cast.

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

От слабого к сильному:

text
значения библиотеки по умолчанию
< withCurlOptions() клиента
< настройки клиента (withTimeout, withRetry, …)
< withCurlOptions() запроса
< настройки запроса (withTimeout, sinkTo, …)

Заголовки собираются так же: заголовки клиента, поверх них заголовки запроса (одноимённые заменяются), поверх них то, что поставят middleware.

Путь запроса

text
$client->get('users/42')->send()
 │
 ├─ 1. базовый адрес + путь → полный URL; заголовки клиента под заголовками запроса
 │
 ├─ 2. middleware — по порядку добавления, один раз на запрос
 │
 ├─ 3. редиректы и повторы — каждая попытка отсюда, middleware не повторяются
 │
 └─ 4. транспорт (cURL) — хендл из пула, User-Agent, тело в память или в файл
        │
        ▼
     CastResponse + info(): время, попытки, редиректы, итоговый адрес

Порядок важен: авторизация в middleware выполняется один раз, а не на каждую попытку; логгер клиента пишет одну строку на запрос с числом попыток. Подробности каждого шага — в Жизненном цикле запроса.

Фасад или клиент

Фасад Cast Свой CastClient
Для чего скрипты, проверки, временный код приложение, сервисы, бины
Настройки по умолчанию (можно заменить Cast::setClient()) свои, видны там, где клиент создан
Тесты общее состояние подменяется через withTransport()

В приложении используйте свой клиент. Фасад удобен, но его настройки общие на весь процесс.