Миграция с 1.x
Версия 2.0 — новый API на стандартах PSR. Совместимость с 1.x не сохранялась: код нужно перенести. Эта страница — карта соответствий.
Что изменилось в целом
- PSR-7/17/18. Запросы, ответы и клиент — стандартные интерфейсы.
- Неизменяемый клиент.
addMiddleware()больше не меняет клиент,withMiddleware()возвращает новый. - Повторы только идемпотентных методов и после middleware, а не до.
- PHP 8.4.
- Удалены:
CastHeader,ApiService,LoggingMiddleware, магияCast::sendGet().
Соответствие
| 1.x | 2.0 |
|---|---|
Common\CastClient |
Client\CastClient |
Common\CastRequest, Common\CastResponse |
Message\CastRequest, Message\CastResponse |
new CastClient(10, 5, [opts]) |
CastClient::create()->withTimeout(10, 5)->withCurlOptions([…]) |
$client->addMiddleware($m) |
$client = $client->withMiddleware($m) |
CastMiddleware::handle($request, $next) |
CastMiddleware::process($request, $next) |
CastHeader::instance()->json()->authBearer($t) |
->withAccept('application/json')->withBearerToken($t) |
BearerAuthMiddleware($t), BasicAuthMiddleware($u, $p) |
AuthMiddleware::bearer($t), AuthMiddleware::basic($u, $p) |
RetryOnUnauthorizedMiddleware |
RefreshTokenMiddleware |
LoggingMiddleware($logger) |
$client->withLogger($logger) |
Stereotype\ApiService |
свой класс вокруг CastClient — см. Свой API-клиент |
Cast::sendGet($url) |
Cast::get($url)->send() |
Cast::setGlobalClient(), getGlobalClient() |
Cast::setClient(), Cast::client() |
->timeout(int) |
->withTimeout(float) |
->connectTimeout(int) |
->withTimeout($total, connect: …) или Timeouts::of()->withConnect() |
->maxResponseSize() |
->withMaxResponseSize() |
->withQueryParams([...]) |
->withQuery([...]) |
->withOptions([...]) |
->withCurlOptions([...]) |
->retry(3, 500) |
->withRetry(RetryPolicy::exponential(3, 500)) |
| повтор любого метода | только идемпотентные; POST — ->withNonIdempotent() |
->withBody(string) |
->withStringBody(string); withBody() принимает поток PSR-7 |
->withFormParams() |
->withFormBody() |
->throwOnError() |
->withThrowOnError() или ->send()->throw() |
$response->statusCode, $response->body |
getStatusCode(), body() |
$response->headers — ['Name' => 'v'] |
getHeaders() — ['Name' => ['v']] по PSR-7; одно значение — header('Name') |
RequestException на 4xx/5xx |
HttpException, ClientErrorException, ServerErrorException |
ConnectionException |
NetworkException |
Пример
Было (1.x):
$client = new CastClient(10, 5);
$client->addMiddleware(new BearerAuthMiddleware($token));
$response = $client->send(
Cast::post('https://api.example.com/v1/orders')
->withHeaders(CastHeader::instance()->json())
->withJsonBody($order)
->retry(3, 500)
);
$id = $response->json()['id'];Стало (2.0):
$client = CastClient::create()
->withBaseUrl('https://api.example.com/v1')
->withBearerToken($token)
->withAccept('application/json')
->withTimeout(10, 5);
$id = $client->post('orders')
->withJsonBody($order)
->withRetry(RetryPolicy::exponential(3, 500)->withNonIdempotent())
->send()
->throw()
->json()['id'];Обратите внимание на withNonIdempotent(): в 2.0 POST по умолчанию не повторяется.
Включайте это, только если сервер не создаст заказ дважды — например, принимает
Idempotency-Key.
На что проверить код
- Повторы
POST. Раньше повторялись, теперь нет. - Ошибки 4xx/5xx. Если код ловил исключение на статус, добавьте
->throw()илиwithThrowOnError(). - Заголовки ответа. Теперь всегда список значений; для строки используйте
header('Name')илиgetHeaderLine('Name'). - Изменяемый клиент. Код вида
$client->addMiddleware(...)без присваивания в 2.0 не работает — результатwith*()нужно сохранить.