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 magicCast::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):
$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):
$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
- Retried
POSTs. They used to be retried; now they are not. - 4xx/5xx errors. If your code caught an exception on a status, add
->throw()orwithThrowOnError(). - Response headers. They are always a list of values now; for a string use
header('Name')orgetHeaderLine('Name'). - The mutable client. Code like
$client->addMiddleware(...)without an assignment does not work in 2.0 — the result ofwith*()has to be kept.