Пакет · cast
Справочник API
Все публичные классы пакета. Методы with*() возвращают копию: объект, на котором они
вызваны, не меняется.
| Класс |
Пространство имён |
Cast |
Flytachi\Winter\Cast |
CastClient, Timeouts, RetryPolicy, Redirects |
…\Cast\Client |
CastRequest, CastResponse, CastStream, CastUri, Multipart, TransferInfo, TransferProgress |
…\Cast\Message |
CastMiddleware, AuthMiddleware, HeadersMiddleware, RefreshTokenMiddleware |
…\Cast\Middleware |
Transport, CurlTransport, MockTransport |
…\Cast\Transport |
CastFactory |
…\Cast\Factory |
| исключения |
…\Cast\Exception — см. Исключения |
CastClient
final class CastClient implements Psr\Http\Client\ClientInterface
Создание
| Метод |
Описание |
__construct() |
клиент с настройками по умолчанию |
static create(): self |
то же, для цепочки |
Настройка
| Метод |
Описание |
withBaseUrl(string|UriInterface $url) |
базовый адрес; должен быть абсолютным http(s), иначе InvalidArgumentException |
withHeader(string $name, string|array $value) |
заголовок по умолчанию |
withHeaders(array $headers) |
несколько; одноимённые заменяются, остальные остаются |
withAddedHeader(string $name, string|array $value) |
добавить значение |
withoutHeader(string $name) |
убрать |
withBearerToken(string $token) |
Authorization: Bearer … |
withBasicAuth(string $user, string $password) |
Authorization: Basic … |
withAccept(string ...$types) |
Accept |
withUserAgent(string $agent, bool $exact = false) |
агент приложения; exact — без суффикса библиотеки |
withTimeouts(Timeouts $timeouts) |
все таймауты |
withTimeout(float $total, ?float $connect = null) |
попытка и соединение |
withRetry(RetryPolicy $policy) |
повторы |
withRedirects(Redirects $redirects) |
редиректы |
withConcurrency(int $limit) |
одновременность sendAll(); по умолчанию 16 |
withMaxResponseSize(?int $bytes) |
предел тела в памяти; по умолчанию 10 МиБ, null — без предела |
withThrowOnError(bool $throw = true) |
send() бросает HttpException на 4xx/5xx |
withMiddleware(CastMiddleware|callable ...$middleware) |
добавить в конец цепочки |
withoutMiddleware(string $class) |
убрать по классу (и наследникам) |
withCurlOptions(array $options) |
свои опции cURL; служебные — InvalidArgumentException |
withLogger(?LoggerInterface $logger) |
логгер PSR-3 |
withTransport(Transport $transport) |
свой транспорт |
Чтение
getBaseUrl(): ?CastUri, getHeaders(): array, getTimeouts(): Timeouts,
getRetryPolicy(): RetryPolicy, getRedirects(): Redirects, getMiddleware(): array.
Запросы, привязанные к клиенту
| Метод |
Возвращает |
get(string|UriInterface $uri, array $query = []) |
CastRequest |
post(), put(), patch(), delete(), head(), options() — те же аргументы |
CastRequest |
request(Method|string $method, string|UriInterface $uri) |
CastRequest |
Отправка
| Метод |
Описание |
send(RequestInterface $request): CastResponse |
отправить; с withThrowOnError() бросает на 4xx/5xx |
sendRequest(RequestInterface $request): CastResponse |
PSR-18; на статус не бросает никогда |
sendAll(iterable $requests, ?int $concurrency = null): array |
одновременно; ответы с ключами запросов; BatchException, если часть без ответа |
CastRequest
final class CastRequest implements Psr\Http\Message\RequestInterface
Создание
| Метод |
Описание |
__construct(string $method, string|UriInterface $uri, array $headers = [], $body = null, string $version = '1.1') |
тело — строка, поток или ресурс |
static get($uri, array $query = []), post, put, patch, delete, head, options |
без клиента |
static from(RequestInterface $request): self |
любой PSR-7 запрос как CastRequest |
Заголовки
PSR-7: withHeader(), withAddedHeader(), withoutHeader(), getHeader(),
getHeaderLine(), hasHeader(), getHeaders(). Дополнительно:
| Метод |
Описание |
withHeaders(array $headers) |
несколько; одноимённые заменяются |
replaceHeaders(array $headers) |
заменить все (Host снова берётся из адреса) |
withBearerToken(string $token), withBasicAuth($user, $password), withAccept(...$types) |
сокращения |
withUserAgent(string $agent, bool $exact = false) |
агент этого запроса |
Адрес
| Метод |
Описание |
withQuery(array $params) |
добавить или заменить параметры; остальные остаются как есть |
withQueryParam(string $name, mixed $value) |
один параметр |
withUri(UriInterface $uri, bool $preserveHost = false) |
PSR-7 |
Тело
| Метод |
Описание |
withJsonBody(mixed $data, int $flags = 0) |
JSON; InvalidArgumentException, если не кодируется |
withFormBody(array $fields) |
application/x-www-form-urlencoded |
withMultipartBody(Multipart|array $parts) |
multipart/form-data |
withStringBody(string $body, ?string $contentType = null) |
строка |
withFileBody(string $path, ?string $contentType = null) |
файл потоком |
withBody(StreamInterface $body) |
PSR-7 поток |
Настройки отправки
| Метод |
Описание |
withTimeout(float $total, ?float $connect = null) |
меняет только эти два; остальные таймауты клиента остаются |
withTimeouts(Timeouts $timeouts) |
заменяет все таймауты клиента |
withRetry(RetryPolicy $policy), withoutRetry() |
повторы |
withRedirects(Redirects $redirects) |
редиректы |
withMaxResponseSize(?int $bytes) |
предел тела |
withThrowOnError(bool $throw = true) |
исключение на 4xx/5xx |
sinkTo(string|resource|StreamInterface $target) |
писать успешное тело в файл, ресурс или поток |
onProgress(callable $callback) |
fn(TransferProgress $p) |
withCurlOptions(array $options) |
опции cURL этого запроса |
Отправка
| Метод |
Описание |
send(): CastResponse |
через клиент, создавший запрос, или клиент фасада |
sendVia(ClientInterface $client): ResponseInterface |
через любой PSR-18 клиент |
CastResponse
final class CastResponse implements Psr\Http\Message\ResponseInterface
| Метод |
Описание |
__construct(int $status = 200, array $headers = [], $body = null, string $version = '1.1', ?string $reason = null) |
|
static fromJson(mixed $data, int $status = 200, array $headers = []) |
JSON-ответ — для тестов |
static fromString(string $body, int $status = 200, array $headers = []) |
ответ со строкой |
status(): ?HttpCode |
статус как enum winter-base |
isSuccess(), isRedirect(), isClientError(), isServerError() |
2xx, 3xx, 4xx, 5xx |
header(string $name): ?string |
одной строкой; null, если нет |
body(): string |
всё тело |
json(): ?array |
объект или массив JSON; иначе null |
jsonOrFail(): array |
то же или CastException |
throw(): static |
HttpException на 4xx/5xx, иначе сам ответ |
info(): TransferInfo |
сведения о передаче |
getRequest(): ?CastRequest |
запрос последней попытки |
isSunk(): bool |
тело записано в цель sinkTo() |
Timeouts
final readonly class Timeouts — свойства connect, total, idle,
idleMinBytesPerSecond, deadline (секунды; null — выключено).
| Метод |
Описание |
static of(?float $total = 30.0, float $connect = 5.0) |
попытка и соединение |
static forDownload(float $idle = 60.0, int $minBytesPerSecond = 1024, float $connect = 5.0) |
без total, с защитой от зависания |
withConnect(float $seconds) |
|
withTotal(?float $seconds) |
|
withIdle(?float $seconds, int $minBytesPerSecond = 1) |
|
withDeadline(?float $seconds) |
вся операция с повторами |
Нулевое или отрицательное значение — InvalidArgumentException.
RetryPolicy
final readonly class RetryPolicy
| Метод |
Описание |
static none() |
без повторов (по умолчанию) |
static exponential(int $attempts = 3, int $delayMs = 500) |
×2 с каждой попыткой, ±30 %, не больше 30 с |
static fixed(int $attempts, int $delayMs) |
одинаковая пауза |
withMethods(Method|string ...$methods) |
какие методы повторять |
withNonIdempotent() |
добавить POST и PATCH |
withStatuses(int ...$statuses) |
какие статусы повторять |
withMaxDelay(int $ms) |
потолок паузы |
respectRetryAfter(bool $respect = true) |
учитывать Retry-After |
enabled(): bool |
больше одной попытки |
attempts — число попыток всего, включая первую.
Redirects
final readonly class Redirects — свойства max, allowDowngrade.
| Метод |
Описание |
static follow(int $max = 10, bool $allowDowngrade = false) |
следовать |
static none() |
не следовать |
enabled(): bool |
|
Multipart
final readonly class Multipart
| Метод |
Описание |
static create() |
пустое тело |
static fromArray(array $fields) |
строки — поля, CURLFile / CURLStringFile — файлы |
withField(string $name, string $value) |
поле |
withFile(string $name, string $path, ?string $filename = null, ?string $contentType = null) |
файл с диска |
withContent(string $name, string $content, string $filename, ?string $contentType = null) |
строка как файл |
withStream(string $name, StreamInterface $stream, string $filename, ?string $contentType = null) |
поток как файл |
contentType(): string |
multipart/form-data; boundary=… |
toStream(): CastStream |
тело по RFC 7578 — для других клиентов |
CastStream
final class CastStream implements Psr\Http\Message\StreamInterface
| Метод |
Описание |
static fromString(string $content = '') |
в памяти |
static fromFile(string $path, string $mode = 'r') |
файл |
static fromResource($resource) |
открытый ресурс |
static temp(int $memoryLimit = 2 MiB) |
в памяти до предела, дальше — во временном файле |
getPath(): ?string |
путь, если поток над файлом |
CastUri
final class CastUri implements Psr\Http\Message\UriInterface
| Метод |
Описание |
static parse(string|UriInterface $uri) |
разобрать; InvalidArgumentException на неверный адрес |
isAbsolute(): bool |
есть схема и хост |
resolve(string|UriInterface $relative): self |
дописать путь к этому адресу — правило базового адреса |
withQueryParams(array $params): self |
добавить или заменить параметры |
redacted(): string |
адрес без query и user:password@ — для логов |
TransferInfo
final readonly class TransferInfo — $response->info().
| Свойство |
Описание |
totalTime, connectTime, startTransferTime |
секунды, последняя попытка |
effectiveUri |
итоговый адрес |
redirects |
число переходов |
attempts |
число попыток |
primaryIp |
IP сервера |
downloadedBytes, uploadedBytes |
байты |
protocol |
1.1 или 2 |
TransferProgress
final readonly class TransferProgress — аргумент функции onProgress().
| Член |
Описание |
downloaded, uploaded |
получено и отправлено байт |
downloadTotal, uploadTotal |
ожидаемый размер; null, пока неизвестен |
downloadPercent(): ?float, uploadPercent(): ?float |
проценты; null без размера |
Middleware
phpinterface CastMiddleware
{
/** @param callable(CastRequest): CastResponse $next */
public function process(CastRequest $request, callable $next): CastResponse;
}
| Класс |
Создание |
AuthMiddleware |
::bearer(string|callable $token), ::basic(string $user, string $password), ::header(string $name, string|callable $value) |
HeadersMiddleware |
new HeadersMiddleware(array|callable $headers) |
RefreshTokenMiddleware |
new RefreshTokenMiddleware(callable $refresh, int $maxRetries = 1) |
Подробно — в Middleware.
Cast
final class Cast — фасад над клиентом по умолчанию.
| Метод |
Описание |
get($uri, array $query = []) … options() |
CastRequest, привязанный к клиенту по умолчанию |
send(RequestInterface $request): CastResponse |
|
sendAll(iterable $requests, ?int $concurrency = null): array |
|
client(): CastClient |
клиент по умолчанию; создаётся при первом вызове |
setClient(?CastClient $client): void |
заменить; null — вернуть настройки по умолчанию |
Транспорт
phpinterface Transport
{
public function execute(CastRequest $request, TransferOptions $options): CastResponse;
}
CurlTransport — по умолчанию. CurlTransport::RESERVED — служебные опции cURL с
подсказкой, каким методом их задавать.
MockTransport — для тестов: __construct(CastResponse|Throwable|callable ...$responses),
static fail(string $message = 'Connection refused', int $curlErrno = 7), append(...),
requests(), lastRequest(), remaining(). См. Тестирование.
CastFactory
final class CastFactory — все четыре фабрики PSR-17: RequestFactoryInterface,
ResponseFactoryInterface, StreamFactoryInterface, UriFactoryInterface.
php$factory = new CastFactory();
$sdk = new SomeVendorSdk(httpClient: $client, requestFactory: $factory, streamFactory: $factory);