Package · cast

Migrating from 1.x

Version 2.0 is a new API built on the PSR standards. Compatibility with 1.x was not kept: code has to be ported. This page is the map.

What changed overall

  • PSR-7/17/18. Requests, responses and the client are the standard interfaces.
  • An immutable client. addMiddleware() no longer changes the client; withMiddleware() returns a new one.
  • Only idempotent methods are retried, and retries happen after middleware, not before.
  • PHP 8.4.
  • Removed: CastHeader, ApiService, LoggingMiddleware, the magic Cast::sendGet().

Mapping

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 a class of your own around CastClient — see Your own API client
Cast::sendGet($url) Cast::get($url)->send()
Cast::setGlobalClient(), getGlobalClient() Cast::setClient(), Cast::client()
->timeout(int) ->withTimeout(float)
->connectTimeout(int) ->withTimeout($total, connect: …) or Timeouts::of()->withConnect()
->maxResponseSize() ->withMaxResponseSize()
->withQueryParams([...]) ->withQuery([...])
->withOptions([...]) ->withCurlOptions([...])
->retry(3, 500) ->withRetry(RetryPolicy::exponential(3, 500))
any method was retried idempotent only; POST with ->withNonIdempotent()
->withBody(string) ->withStringBody(string); withBody() takes a PSR-7 stream
->withFormParams() ->withFormBody()
->throwOnError() ->withThrowOnError() or ->send()->throw()
$response->statusCode, $response->body getStatusCode(), body()
$response->headers — ['Name' => 'v'] getHeaders() — ['Name' => ['v']] per PSR-7; one value — header('Name')
RequestException on 4xx/5xx HttpException, ClientErrorException, ServerErrorException
ConnectionException NetworkException

Example

Before (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'];

After (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'];

Note withNonIdempotent(): in 2.0 a POST is not retried by default. Turn it on only if the server will not create the order twice — for example, because it accepts an Idempotency-Key.

What to check in your code

  1. Retried POSTs. They used to be retried; now they are not.
  2. 4xx/5xx errors. If your code caught an exception on a status, add ->throw() or withThrowOnError().
  3. Response headers. They are always a list of values now; for a string use header('Name') or getHeaderLine('Name').
  4. The mutable client. Code like $client->addMiddleware(...) without an assignment does not work in 2.0 — the result of with*() has to be kept.