Package · cast

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.

Package flytachi/winter-castPHP ≥ 8.4Standards PSR-7 · PSR-17 · PSR-18

What it looks like

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