Package · cast

Configuring the client

A client is built once with a chain of with*() calls — usually at application start or in a bean — and after that it only sends requests.

Creating one

php
use Flytachi\Winter\Cast\Client\CastClient;

$client = CastClient::create()             // the same as new CastClient()
  ->withBaseUrl('https://api.example.com/v1')
  ->withHeaders(['Accept' => 'application/json', 'X-Tenant' => 'acme'])
  ->withBearerToken($token)
  ->withUserAgent('billing/2.3')
  ->withTimeout(10);

A client works without any settings: 5 s to connect, 30 s per attempt, no retries, up to 10 redirects, at most 10 MiB of body in memory.

Base URL

A request’s relative path is appended to the base URL:

Base Path Result
https://api.com users/42 https://api.com/users/42
https://api.com/v1 users https://api.com/v1/users
https://api.com/v1/ /users https://api.com/v1/users
https://api.com/v1?key=1 users?page=2 https://api.com/v1/users?key=1&page=2

This is not RFC 3986 resolution: under it, https://api.com/v1 + users would give https://api.com/users, silently dropping the v1 segment. An absolute address in a request is used as it is; the base URL does not apply to it.

Without a base URL, a relative path is a RequestException at send time.

Default headers

Method What it does
withHeader($name, $value) set one (the value is a string or a list)
withHeaders([...]) set several; same-name headers are replaced, the others stay
withAddedHeader($name, $value) add a value to an existing one
withoutHeader($name) remove
withBearerToken($token) Authorization: Bearer …
withBasicAuth($user, $password) Authorization: Basic …
withAccept(...$types) Accept: a, b

Names are case-insensitive: content-type and Content-Type are one header, and the spelling set last is the one sent. A request header with the same name replaces the client’s.

Headers computed for every request (X-Request-ID, a signature) belong in middleware.

User-Agent

Setting Sent
nothing WinterCast/2.0.0 curl/8.11.0
withUserAgent('billing/2.3') billing/2.3 WinterCast/2.0.0 curl/8.11.0
withUserAgent('billing/2.3', exact: true) billing/2.3

Your agent comes first (RFC 9110 recommends most significant first). The suffix is added last, at send time, so an agent set in middleware gets it too. It is never added twice.

Response size

php
$client->withMaxResponseSize(50 * 1024 * 1024);   // 50 MiB
$client->withMaxResponseSize(null);               // no limit

The limit — 10 MiB — applies to a body kept in memory. A larger response gives a TooLargeException: immediately by Content-Length, without downloading, or otherwise as soon as the received bytes exceed the limit. Downloading to a file (sinkTo()) is not limited.

Why 10 MiB

json() turns the body into an array, and an array takes 5–10 times the memory of the JSON. An API response over 10 MiB is almost always either an export (which belongs in sinkTo()) or a bug such as broken pagination. Better to find out right away.

Custom cURL options

Proxies, certificates, binding to an interface — through withCurlOptions():

php
$client->withCurlOptions([
  CURLOPT_PROXY => 'http://proxy.internal:3128',
  CURLOPT_CAINFO => '/etc/ssl/internal-ca.pem',
]);

Options the library itself relies on (address, method, headers, body, callbacks, redirects) cannot be set: you get an InvalidArgumentException naming the method to use instead. The full list is CurlTransport::RESERVED.

Several clients from one

The client is immutable, so it is convenient to derive specific clients from a common one:

php
$base = CastClient::create()->withUserAgent('billing/2.3')->withTimeout(10);

$github = $base->withBaseUrl('https://api.github.com')->withBearerToken($githubToken);
$stripe = $base->withBaseUrl('https://api.stripe.com/v1')->withBasicAuth($stripeKey, '');

All three share one connection pool.

Reading the settings

getBaseUrl(), getHeaders(), getTimeouts(), getRetryPolicy(), getRedirects(), getMiddleware() — for debugging and tests. var_dump($client) shows the settings with the values of Authorization, Proxy-Authorization, Cookie and X-Api-Key replaced by ***.