Пакет · 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

php
interface 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 — вернуть настройки по умолчанию

Транспорт

php
interface 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);