Запросы и ответы
Запрос собирается цепочкой и отправляется вызовом send(). Ответ — PSR-7 объект с
короткими методами для типичного чтения.
Методы
$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
$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 МиБ отправляется из памяти, большее или неизвестного размера — потоком, без загрузки целиком.
Настройки одной отправки
Каждая заменяет настройку клиента только для этого запроса:
$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 клиент |
Ответ
$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.
Сведения о передаче
$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() — запрос последней попытки, именно в том виде, в каком он ушёл.