Пакет · cast

Запросы и ответы

Запрос собирается цепочкой и отправляется вызовом send(). Ответ — PSR-7 объект с короткими методами для типичного чтения.

Методы

php
$client->get('users', ['page' => 2]);      // второй аргумент — query
$client->post('users');
$client->put('users/42');
$client->patch('users/42');
$client->delete('users/42');
$client->head('files/7');
$client->options('users');
$client->request(Method::PATCH, 'users/42');   // enum Method из winter-base
$client->request('PURGE', 'cache/x');         // или любой метод строкой

Без клиента — статическими методами: CastRequest::get($url, $query) и так далее, или через фасад: Cast::get($url, $query).

Query

php
$client->get('search', ['q' => 'winter', 'tags' => ['php', 'http']])
  ->withQuery(['page' => 2])        // добавить или заменить несколько
  ->withQueryParam('limit', 50);    // одно

Параметры, уже записанные в адресе (search?sort=name), сохраняются как есть, заменяются только ключи с теми же именами.

Заголовки

У запроса тот же набор, что у клиента: withHeader(), withHeaders() (добавляет), withAddedHeader(), withoutHeader(), withBearerToken(), withBasicAuth(), withAccept(), withUserAgent(). Кроме того, replaceHeaders([...]) заменяет все заголовки сразу.

Заголовок с переводом строки или NUL в имени или значении отклоняется (InvalidArgumentException): подставить свой заголовок через пользовательский ввод нельзя.

Тело

Метод Что отправляет
withJsonBody($data, $flags = 0) JSON, Content-Type: application/json
withFormBody([...]) application/x-www-form-urlencoded
withMultipartBody(Multipart|array) multipart/form-data — см. Файлы
withStringBody($body, $contentType = null) строку как есть
withFileBody($path, $contentType = null) файл с диска, потоком
withBody(StreamInterface) любой PSR-7 поток

Данные, которые нельзя закодировать в JSON (NAN, неверный UTF-8), дают InvalidArgumentException сразу, а не пустое тело на сервере.

Тело до 1 МиБ отправляется из памяти, большее или неизвестного размера — потоком, без загрузки целиком.

Настройки одной отправки

Каждая заменяет настройку клиента только для этого запроса:

php
$client->get('report')
  ->withTimeout(120)                     // total; connect и дедлайн клиента остаются
  ->withoutRetry()
  ->withMaxResponseSize(null)
  ->withThrowOnError()
  ->send();

Полный список: withTimeout(), withTimeouts(), withRetry(), withoutRetry(), withRedirects(), withMaxResponseSize(), withThrowOnError(), withCurlOptions(), sinkTo(), onProgress().

Отправка

Метод Через что
$request->send() клиент, создавший запрос, или клиент фасада
$client->send($request) этот клиент; принимает любой PSR-7 запрос
$request->sendVia($psr18Client) любой PSR-18 клиент

Ответ

php
$response = $client->get('users/42')->send();

$response->getStatusCode();     // 200
$response->status();            // HttpCode::OK — enum из winter-base
$response->isSuccess();         // 2xx; ещё isRedirect(), isClientError(), isServerError()

$response->header('ETag');      // одной строкой; null, если заголовка нет
$response->getHeader('Set-Cookie');   // PSR-7: список значений

$response->body();              // всё тело строкой
$response->json();              // массив; null, если тело пустое, не JSON или JSON-скаляр
$response->jsonOrFail();        // массив или CastException
$response->throw();             // исключение на 4xx/5xx, иначе сам ответ — для цепочек

json() нарочно не бросает исключений: ответ 204 или HTML-страница ошибки дают null. Если ожидается именно объект, используйте jsonOrFail().

Сжатые ответы

Cast сам просит сжатие (Accept-Encoding) и распаковывает ответ. После распаковки Content-Encoding и Content-Length описывали бы байты в сети, а не полученное тело, поэтому они переносятся в X-Encoded-Content-Encoding и X-Encoded-Content-Length.

Сведения о передаче

php
$info = $response->info();

$info->totalTime;        // секунды, вся последняя попытка
$info->connectTime;
$info->startTransferTime;
$info->attempts;         // сколько было попыток
$info->redirects;        // сколько переходов
$info->effectiveUri;     // итоговый адрес после редиректов
$info->primaryIp;
$info->protocol;         // "1.1" или "2"
$info->downloadedBytes;
$info->uploadedBytes;

$response->getRequest() — запрос последней попытки, именно в том виде, в каком он ушёл.