Пакет · cast

Миграция с 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):

php
$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):

php
$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.

На что проверить код

  1. Повторы POST. Раньше повторялись, теперь нет.
  2. Ошибки 4xx/5xx. Если код ловил исключение на статус, добавьте ->throw() или withThrowOnError().
  3. Заголовки ответа. Теперь всегда список значений; для строки используйте header('Name') или getHeaderLine('Name').
  4. Изменяемый клиент. Код вида $client->addMiddleware(...) без присваивания в 2.0 не работает — результат with*() нужно сохранить.