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
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
$client->withMaxResponseSize(50 * 1024 * 1024); // 50 MiB
$client->withMaxResponseSize(null); // no limitThe 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():
$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:
$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 ***.