Пакет · cast

Обработка ошибок

В Cast два разных вида проблем. Сервер ответил ошибкой — это ответ, его можно прочитать. Ответа нет вовсе — это исключение.

Статус ошибки — это ответ

PSR-18 требует: клиент бросает исключение, только если ответа нет. 404 и 500 — ответы:

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

if ($response->getStatusCode() === 404) {
  return null;
}

Когда ошибка статуса должна прервать выполнение, есть два способа.

В вызове — throw() возвращает тот же ответ или бросает исключение:

php
$user = $client->get('users/42')->send()->throw()->json();

Для всего клиента — withThrowOnError(): каждый send() бросает на 4xx/5xx:

php
$strict = $client->withThrowOnError();
$strict->get('users/42')->send();   // HttpException на 4xx/5xx

sendRequest() — метод PSR-18 — не бросает на статус никогда, даже с withThrowOnError(). Так стороннее PSR-18 приложение получает то поведение, которого ждёт.

Что ловить

php
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

php
$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 — часто проходят со второй попытки. Включите повторы, и до вашего кода дойдёт только окончательная ошибка: см. Таймауты и повторы.