Cast
Winter Cast is the HTTP client of the Winter framework. It is built on PSR-7, PSR-17 and PSR-18, runs on cURL, and behaves the same in PHP-FPM, the CLI and Swoole coroutines. You configure a client once and then use it like any other value: keep it as a bean and share it between coroutines.
What it looks like
use Flytachi\Winter\Cast\Client\CastClient;
use Flytachi\Winter\Cast\Client\RetryPolicy;
$api = CastClient::create()
->withBaseUrl('https://api.example.com/v1')
->withBearerToken($token)
->withRetry(RetryPolicy::exponential());
$user = $api->get('users/42')->send()->throw()->json();The client knows the base address and the key. The request appends its path to the address,
throw() turns a 4xx/5xx response into an exception, and json() returns an array. The full
walkthrough is in the quick start.
What it can do
| Feature | Where it is described |
|---|---|
| Base URL, default headers, User-Agent | Configuring the client |
| JSON, forms, multipart, files; reading responses | Requests and responses |
| 4xx/5xx as a response or as an exception | Error handling |
Per-attempt timeouts, an overall deadline, retries with Retry-After |
Timeouts and retries |
| Redirects that do not leak keys to other hosts | Redirects and security |
| Downloading to a file, streaming uploads, progress | Files |
| Several requests in the time of the slowest one | Concurrent requests |
| Authentication, token refresh, steps of your own | Middleware |
| The client as a bean, logs through winter-logger | Winter integration |
| Replacing the network in tests | Testing |
Principles
Standards instead of a format of its own. Requests and responses are PSR-7, factories are
PSR-17, the client is PSR-18. Cast can be handed to any library that takes a
ClientInterface, and it accepts that library’s requests.
Immutability. Every with*() returns a copy. A configured client cannot be broken by
accident from somewhere else, and hundreds of coroutines can safely share one instance.
An error status is a response. By the PSR-18 rule, a 404 or a 500 is returned as a
response. It becomes an exception where you decide: ->throw() on a call, or
withThrowOnError() on the client.
Careful defaults. Retries are off until you ask for them, and even then only idempotent methods are retried. Every attempt has a timeout, the body kept in memory is capped, and keys are not sent to another host on a redirect.
The same in FPM and Swoole. The calling code does not depend on the environment:
sendAll() picks Swoole coroutines or Fibers with curl_multi by itself.
Requirements
PHP 8.4 and the curl extension. Swoole is optional. Details are on the
Installation page.
Links
- Package:
flytachi/winter-cast - Source code: github.com/flytachi/winter-cast
- Coming from 1.x: Migrating from 1.x