Mental model
Cast has three main objects: the client holds the settings, the request describes one send, and the response returns the result. Everything else is settings (timeouts, retries, redirects) and extension points (middleware, the transport).
Three objects
| Object | What it is | Standard |
|---|---|---|
CastClient |
settings and sending: base URL, headers, timeouts, retries, middleware | PSR-18 ClientInterface |
CastRequest |
one request: method, address, headers, body and its own send settings | PSR-7 RequestInterface |
CastResponse |
the response: status, headers, body and transfer details | PSR-7 ResponseInterface |
The body of a request or response is a CastStream (PSR-7 StreamInterface); the address is
a CastUri.
Everything is immutable
Every with*() returns a new object and leaves the original unchanged:
$base = CastClient::create()->withBaseUrl('https://api.example.com');
$admin = $base->withBearerToken($adminToken); // $base still has no tokenThat is why a client can live in a bean, be passed to services and be used from many coroutines: nobody can change its settings on the fly. Copies share one connection pool.
A request is bound to its client
$client->get(), post() and the others create a request that remembers its client. Its
send() method sends it through that client:
$client->get('users/42')->withHeader('X-Trace', $id)->send();
// the same as:
$client->send(CastRequest::get('users/42')->withHeader('X-Trace', $id));A request created without a client (CastRequest::get()) is sent through the default client
of the Cast facade when you call send().
Settings precedence
From weakest to strongest:
the library's defaults
< the client's withCurlOptions()
< the client's settings (withTimeout, withRetry, …)
< the request's withCurlOptions()
< the request's settings (withTimeout, sinkTo, …)Headers are assembled the same way: the client’s headers, then the request’s on top (headers of the same name are replaced), then whatever middleware sets.
A request’s path
$client->get('users/42')->send()
│
├─ 1. base URL + path → full URL; the client's headers under the request's
│
├─ 2. middleware — in the order added, once per request
│
├─ 3. redirects and retries — every attempt starts here, middleware does not run again
│
└─ 4. transport (cURL) — a handle from the pool, User-Agent, body to memory or a file
│
▼
CastResponse + info(): time, attempts, redirects, final addressThe order matters: authentication in middleware runs once, not on every attempt, and the client’s logger writes one line per request with the number of attempts. Each step in detail is in Request lifecycle.
Facade or client
The Cast facade |
Your own CastClient |
|
|---|---|---|
| For | scripts, checks, throwaway code | applications, services, beans |
| Settings | defaults (replaceable with Cast::setClient()) |
your own, visible where the client is created |
| Tests | shared state | replaced through withTransport() |
Use your own client in an application. The facade is convenient, but its settings are shared by the whole process.