Модель работы
В Cast три главных объекта: клиент хранит настройки, запрос описывает одну отправку, ответ отдаёт результат. Всё остальное — настройки (таймауты, повторы, редиректы) и точки расширения (middleware, транспорт).
Три объекта
| Объект | Что это | Стандарт |
|---|---|---|
CastClient |
настройки и отправка: базовый адрес, заголовки, таймауты, повторы, middleware | PSR-18 ClientInterface |
CastRequest |
один запрос: метод, адрес, заголовки, тело и свои настройки отправки | PSR-7 RequestInterface |
CastResponse |
ответ: статус, заголовки, тело и сведения о передаче | PSR-7 ResponseInterface |
Тело запроса и ответа — поток CastStream (PSR-7 StreamInterface), адрес — CastUri.
Всё неизменяемо
Каждый with*() возвращает новый объект, исходный не меняется:
$base = CastClient::create()->withBaseUrl('https://api.example.com');
$admin = $base->withBearerToken($adminToken); // $base остался без токенаПоэтому клиент можно хранить в бине, передавать в сервисы и использовать из многих корутин: никто не изменит его настройки «на лету». Копии делят один пул соединений.
Запрос привязан к клиенту
$client->get(), post() и другие создают запрос, который помнит свой клиент. Метод
send() отправляет его через этот клиент:
$client->get('users/42')->withHeader('X-Trace', $id)->send();
// то же самое:
$client->send(CastRequest::get('users/42')->withHeader('X-Trace', $id));Запрос, созданный без клиента (CastRequest::get()), при send() уходит через клиент по
умолчанию фасада Cast.
Приоритет настроек
От слабого к сильному:
значения библиотеки по умолчанию
< withCurlOptions() клиента
< настройки клиента (withTimeout, withRetry, …)
< withCurlOptions() запроса
< настройки запроса (withTimeout, sinkTo, …)Заголовки собираются так же: заголовки клиента, поверх них заголовки запроса (одноимённые заменяются), поверх них то, что поставят middleware.
Путь запроса
$client->get('users/42')->send()
│
├─ 1. базовый адрес + путь → полный URL; заголовки клиента под заголовками запроса
│
├─ 2. middleware — по порядку добавления, один раз на запрос
│
├─ 3. редиректы и повторы — каждая попытка отсюда, middleware не повторяются
│
└─ 4. транспорт (cURL) — хендл из пула, User-Agent, тело в память или в файл
│
▼
CastResponse + info(): время, попытки, редиректы, итоговый адресПорядок важен: авторизация в middleware выполняется один раз, а не на каждую попытку; логгер клиента пишет одну строку на запрос с числом попыток. Подробности каждого шага — в Жизненном цикле запроса.
Фасад или клиент
Фасад Cast |
Свой CastClient |
|
|---|---|---|
| Для чего | скрипты, проверки, временный код | приложение, сервисы, бины |
| Настройки | по умолчанию (можно заменить Cast::setClient()) |
свои, видны там, где клиент создан |
| Тесты | общее состояние | подменяется через withTransport() |
В приложении используйте свой клиент. Фасад удобен, но его настройки общие на весь процесс.