Обработка ошибок
В Cast два разных вида проблем. Сервер ответил ошибкой — это ответ, его можно прочитать. Ответа нет вовсе — это исключение.
Статус ошибки — это ответ
PSR-18 требует: клиент бросает исключение, только если ответа нет. 404 и 500 — ответы:
$response = $client->get('users/999')->send();
if ($response->getStatusCode() === 404) {
return null;
}Когда ошибка статуса должна прервать выполнение, есть два способа.
В вызове — throw() возвращает тот же ответ или бросает исключение:
$user = $client->get('users/42')->send()->throw()->json();Для всего клиента — withThrowOnError(): каждый send() бросает на 4xx/5xx:
$strict = $client->withThrowOnError();
$strict->get('users/42')->send(); // HttpException на 4xx/5xxsendRequest() — метод PSR-18 — не бросает на статус никогда, даже с
withThrowOnError(). Так стороннее PSR-18 приложение получает то поведение, которого
ждёт.
Что ловить
use Flytachi\Winter\Cast\Exception\ClientErrorException;
use Flytachi\Winter\Cast\Exception\NetworkException;
use Flytachi\Winter\Cast\Exception\ServerErrorException;
use Flytachi\Winter\Cast\Exception\TimeoutException;
try {
$report = $client->get('reports/2026')->send()->throw()->json();
} catch (ClientErrorException $e) { // 4xx — запрос неверен, повтор не поможет
$problem = $e->getResponse()->json();
} catch (ServerErrorException $e) { // 5xx — сервер сломался
$status = $e->getStatusCode();
} catch (TimeoutException $e) { // не дождались
$e->isConnect(); // не удалось даже подключиться
} catch (NetworkException $e) { // нет связи: DNS, отказ, обрыв, TLS
$e->isTransient(); // повтор может помочь
}TimeoutException наследует NetworkException, поэтому ловится раньше.
| Ситуация | Исключение |
|---|---|
| неверный заголовок, URI, метод; JSON не кодируется; служебная опция cURL | InvalidArgumentException — при сборке запроса |
адрес не http/https, нет базового адреса, слишком много редиректов |
RequestException — до отправки |
| DNS, отказ в соединении, TLS, обрыв | NetworkException |
| истёк таймаут или дедлайн | TimeoutException |
тело больше maxResponseSize |
TooLargeException |
| 4xx / 5xx | ответ; ClientErrorException / ServerErrorException при throw() |
sendAll(): часть запросов без ответа |
BatchException — после завершения всех |
Все исключения реализуют Psr\Http\Client\ClientExceptionInterface, поэтому
catch (ClientExceptionInterface) ловит любую ошибку клиента. Полная иерархия — в
Исключениях.
Сообщения без секретов
В сообщениях исключений адрес записан без query и без user:password@: ключи из адреса не
попадают в логи и в трекер ошибок. Сам запрос со всеми данными доступен через
$e->getRequest().
Ответ, который не JSON
$data = $response->json(); // null, если не JSON-объект или массив
$data = $response->jsonOrFail(); // CastException с кодом статуса и Content-TypeЧастый случай: балансировщик вернул HTML-страницу 502. json() даст null, а
jsonOrFail() — понятное сообщение «Expected a JSON object or array in the response
(HTTP 502, text/html)».
Повторить вместо ошибки
Временные сбои — отказ в соединении, обрыв, таймаут, 503 — часто проходят со второй попытки. Включите повторы, и до вашего кода дойдёт только окончательная ошибка: см. Таймауты и повторы.