Package · cast

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:

php
$base = CastClient::create()->withBaseUrl('https://api.example.com');
$admin = $base->withBearerToken($adminToken);   // $base still has no token

That 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:

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

text
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

text
$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 address

The 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.