Cast
Winter Cast — HTTP-клиент фреймворка Winter. Он построен на стандартах PSR-7, PSR-17 и PSR-18, работает поверх cURL и одинаково ведёт себя в PHP-FPM, CLI и корутинах Swoole. Клиент настраивается один раз и дальше используется как обычное значение: его можно держать бином и делить между корутинами.
Как это выглядит
use Flytachi\Winter\Cast\Client\CastClient;
use Flytachi\Winter\Cast\Client\RetryPolicy;
$api = CastClient::create()
->withBaseUrl('https://api.example.com/v1')
->withBearerToken($token)
->withRetry(RetryPolicy::exponential());
$user = $api->get('users/42')->send()->throw()->json();Клиент знает базовый адрес и ключ, запрос дописывает к адресу свой путь, throw()
превращает ответ 4xx/5xx в исключение, а json() возвращает массив. Полный сценарий — в
быстром старте.
Что умеет
| Возможность | Где описано |
|---|---|
| Базовый адрес, заголовки по умолчанию, User-Agent | Настройка клиента |
| JSON, формы, multipart, файлы; чтение ответа | Запросы и ответы |
| 4xx/5xx как ответ или как исключение | Обработка ошибок |
Таймауты на попытку, общий дедлайн, повторы с Retry-After |
Таймауты и повторы |
| Редиректы без утечки ключей на чужой хост | Редиректы и безопасность |
| Скачивание в файл, отправка файлов потоком, прогресс | Файлы |
| Несколько запросов за время самого медленного | Параллельные запросы |
| Авторизация, обновление токена, свои шаги | Middleware |
| Клиент как бин, логи через winter-logger | Интеграция с Winter |
| Подмена сети в тестах | Тестирование |
Принципы
Стандарты вместо своего формата. Запросы и ответы — PSR-7, фабрики — PSR-17, клиент —
PSR-18. Cast можно отдать любой библиотеке, которая принимает ClientInterface, и
принимать от неё её запросы.
Неизменяемость. Каждый with*() возвращает копию. Настроенный клиент нельзя случайно
испортить из другого места, а одну копию безопасно используют сотни корутин.
Ошибка статуса — это ответ. По правилу PSR-18 ответ 404 или 500 возвращается как ответ.
Исключением он становится там, где вы решили: ->throw() в вызове или
withThrowOnError() у клиента.
Осторожные значения по умолчанию. Повторы выключены, пока их не попросят, и даже тогда повторяются только идемпотентные методы. На каждую попытку есть таймаут, тело в памяти ограничено, ключи не уходят на чужой хост при редиректе.
Одинаково в FPM и Swoole. Код вызова не зависит от среды: sendAll() сам выбирает
корутины Swoole или Fiber с curl_multi.
Требования
PHP 8.4 и расширение curl. Swoole не обязателен. Подробности — на странице
Установка.
Ссылки
- Пакет:
flytachi/winter-cast - Исходный код: github.com/flytachi/winter-cast
- Переход с версии 1.x: Миграция с 1.x