Исключения в PHP: try, catch, finally и свои классы ошибок
Исключение прерывает обычное выполнение кода и передаёт управление ближайшему подходящему обработчику. В PHP блок try обозначает защищённый участок, catch обрабатывает выбранные типы исключений, а finally освобождает ресурсы при выходе из блока.
Как работает try в PHP
В try помещают операцию, которая может выбросить исключение, и код, которому нужен её успешный результат. Если внутри выброшено исключение, оставшиеся инструкции блока пропускаются. PHP проверяет блоки catch сверху вниз и выполняет первый, чей тип подходит объекту исключения. После обработки выполнение продолжается за всей конструкцией.
Если подходящего catch нет, исключение поднимается по стеку вызовов. Например, исключение из функции может обработать код, который её вызвал. Если обработчика нет во всём стеке, PHP передаёт исключение глобальному обработчику, если он установлен. Без глобального обработчика выполнение завершается с фатальной ошибкой.
<?php
declare(strict_types=1);
function parseSettings(string $json): array
{
$settings = json_decode($json, true, 512, JSON_THROW_ON_ERROR);
if (!is_array($settings)) {
throw new UnexpectedValueException('Ожидался JSON-объект или массив');
}
return $settings;
}
try {
$settings = parseSettings('{"debug":}');
var_export($settings); // Выполнится только при успешном разборе.
} catch (JsonException $e) {
echo 'Некорректный JSON: ', $e->getMessage(), PHP_EOL;
} catch (UnexpectedValueException $e) {
echo $e->getMessage(), PHP_EOL;
}Здесь JSON_THROW_ON_ERROR включает исключения при ошибках декодирования. Синтаксически корректное значение null декодируется успешно и отклоняется уже проверкой формата. Если функция должна принимать строго JSON-объект, декодируйте с аргументом false и проверяйте результат через instanceof stdClass. У try должен быть хотя бы один catch или finally.
PHP try catch: как выбрать обработчик
Тип в catch совпадает и с указанным классом, и с его подклассами. Ставьте частные типы выше общих. Например, JsonException наследуется от Exception. Если первым указать catch (Exception $e), до отдельного обработчика JsonException дело не дойдёт.
Для одинаковой реакции на разные сбои перечислите типы через |. Если объект исключения не нужен, переменную можно опустить. В примере резервные настройки подходят и при повреждённом JSON, и при выходе значения за допустимый диапазон.
<?php
declare(strict_types=1);
try {
$retries = json_decode('12', true, 512, JSON_THROW_ON_ERROR);
if (!is_int($retries) || $retries < 0 || $retries > 5) {
throw new OutOfRangeException('Допустимо от 0 до 5 повторов');
}
} catch (JsonException | OutOfRangeException) {
$retries = 2; // Значение по умолчанию для обоих случаев.
}
printf("Повторов: %d\n", $retries);Держите try достаточно узким, чтобы обработчик реагировал именно на сбой нужной операции. Если в одном блоке читать конфигурацию, декодировать запрос и разбирать ответ внешнего сервиса, один catch (JsonException) может ошибочно представить сбой любого из этих шагов как ошибку клиента.
PHP Exception, Error и Throwable
Throwable объединяет две ветви, которые PHP разрешает выбрасывать и перехватывать. Exception служит базовым классом для исключений приложения и многих библиотек. Error охватывает ошибки движка, среди которых TypeError, ValueError и DivisionByZeroError. catch (Exception $e) перехватывает первую ветвь, а catch (Throwable $e) охватывает обе.
| Тип | Что означает | Пример |
|---|---|---|
Exception | Исключение приложения или библиотеки | JsonException при разборе повреждённого JSON |
TypeError | Значение не соответствует объявленному типу | Строка передана параметру int из файла со строгой типизацией |
ValueError | Тип аргумента подходит, но значение недопустимо | Нулевая глубина в json_decode() |
Throwable | Общий тип для обеих ветвей | Обработчик верхнего уровня веб-приложения или CLI-команды |
declare(strict_types=1) действует на уровне файла. Для скалярных аргументов пользовательских функций важен файл, из которого сделан вызов. В примерах декларация стоит первой инструкцией. Данные из HTTP-запроса всё равно нужно проверять на входе. Если пользователь прислал неверный формат, верните ошибку валидации на основе этой проверки. Перехват любого TypeError с тем же ответом может скрыть дефект в самом приложении.
Предупреждения E_WARNING и уведомления E_NOTICE идут через механизм ошибок PHP. Обычный catch их не перехватывает. Например, при невозможности открыть файл fopen() обычно выдаёт предупреждение и возвращает false. Проверяйте возвращаемое значение по контракту функции. Если приложению нужно преобразовывать выбранные предупреждения в исключения, для этого есть set_error_handler() и ErrorException.
PHP throw exception: как выбросить своё исключение
Инструкция throw new ... создаёт и выбрасывает объект. Для своего типа наследуйтесь от Exception или его подходящего подкласса, например RuntimeException. Напрямую реализовать Throwable в собственном классе PHP не разрешает. Отдельный тип полезен, когда вызывающему коду нужно отличать конкретный отказ и реагировать на него без разбора текста сообщения.
<?php
declare(strict_types=1);
final class InsufficientStock extends RuntimeException
{
public function __construct(
public readonly int $requested,
public readonly int $available,
) {
parent::__construct('Недостаточно товара для резерва');
}
}
function remainingStock(int $available, int $requested): int
{
if ($available < 0 || $requested < 1) {
throw new InvalidArgumentException('Некорректное количество товара');
}
if ($requested > $available) {
throw new InsufficientStock($requested, $available);
}
return $available - $requested;
}
try {
echo remainingStock(3, 5), PHP_EOL;
} catch (InsufficientStock $e) {
// Интерфейс может предложить доступное количество.
printf("Запрошено %d, доступно %d\n", $e->requested, $e->available);
}В этом примере недопустимые аргументы нарушают контракт функции, а нехватка товара может возникнуть и при корректном вызове. Оба случая имеют свой тип. Числа доступны через свойства, поэтому формат сообщения можно менять независимо от логики обработчика. Если класс находится в пространстве имён, импортируйте встроенные типы через use или указывайте полные имена вроде \RuntimeException.
Чтобы передать пойманное исключение выше, используйте throw $e. Если на границе модуля нужно сообщить об операции на языке вызывающего кода, оберните сбой и сохраните исходный объект в previous. Например, в обработчике ошибки декодирования можно написать throw new RuntimeException('Не удалось загрузить настройки', previous: $e). Первопричина будет доступна через getPrevious().
Когда выполняется finally
finally выполняется после try и подходящего catch, если он сработал. При return внутри try или catch PHP вычисляет возвращаемое значение, выполняет finally и затем возвращает результат. При раскрутке стека из-за исключения finally выполняется до передачи ошибки вызывающему коду. Это удобно для освобождения блокировок и возвращения ресурсов в исходное состояние.
<?php
declare(strict_types=1);
function serializeJob(array $job): string
{
$previousTimezone = date_default_timezone_get();
date_default_timezone_set('UTC');
try {
$job['serialized_at'] = date(DATE_ATOM);
return json_encode($job, JSON_THROW_ON_ERROR);
} finally {
// Восстанавливаем настройку даже при сбое кодирования.
date_default_timezone_set($previousTimezone);
}
}
echo serializeJob(['id' => 42]), PHP_EOL;У try в этом примере есть только finally. Если json_encode() выбросит JsonException, часовой пояс восстановится, а исключение получит вызывающий код. Саму временную смену часового пояса пример использует, чтобы показать работу с общей настройкой. Для форматирования одной даты достаточно передать нужный DateTimeZone объекту DateTimeImmutable.
Избегайте return в finally: он заменяет ранее вычисленный результат и может подавить ожидающее исключение. Если finally выбросит новое исключение, наружу уйдёт оно, а уже ожидавшее исключение будет доступно как предыдущее. При прямом вызове exit() внутри защищённого кода finally не выполняется. Обычный выход из блока и остановка процесса подчиняются разным правилам.
Типичные ошибки обработки исключений
- Пустой catch. Без явной реакции вызывающий код может принять незавершённую операцию за успешную. Перехватывайте исключение там, где можно восстановиться, вернуть понятный ответ или добавить контекст и передать его выше.
- Catch на слишком широком участке. Резервный сценарий для одного сбоя легко скроет другой. Ограничьте блок операцией, чей отказ действительно предусмотрен, а обработчик — нужным типом.
- Предположение, что любой сбой выбрасывает исключение. Сверяйтесь с контрактом конкретной функции. Для
json_decode()включитеJSON_THROW_ON_ERROR, а для функций с результатомfalseобработайте его явно, если API не предлагает режим исключений. - Потеря причины при обёртке. Передавайте исходное исключение в
previous. Сохраняйте цепочку для диагностики, особенно если несколько библиотечных ошибок преобразуются в один тип вашего модуля. - Вывод полного исключения клиенту. Сообщение и стек вызовов могут содержать пути, параметры и детали инфраструктуры. На внешней границе верните безопасное сообщение, а диагностические подробности направьте в журнал с учётом чувствительных данных.
- Логирование одного сбоя на каждом уровне. Если слой только передаёт ошибку выше, журнал обычно достаточно пополнить там, где формируется окончательный ответ или принимается решение о повторе.
Чем отличаются версии PHP 8.x
В PHP 8.3, 8.4 и 8.5 синтаксис try, catch, finally и throw в приведённых примерах одинаков. Перехват без переменной и использование throw как выражения доступны с PHP 8.0. Например, $id = $data['id'] ?? throw new InvalidArgumentException('Нет id'); прекращает выполнение, если ключ отсутствует или его значение равно null.
При обновлении внутри ветки 8.x проверяйте контракты отдельных расширений. Например, в PHP 8.3 ошибка при передаче некорректной строки в new DateTimeImmutable($value) получила отдельный тип DateMalformedStringException. Он наследуется от Exception, поэтому прежний общий обработчик продолжает работать. В приложении с минимальной версией PHP 8.3 уже можно ловить конкретный тип вокруг разбора даты.
Чек-лист для рабочего кода
- Уточните, как операция сообщает о сбое: исключением, предупреждением или возвращаемым значением.
- Поместите в
tryвызовы, для которых предусмотрена общая реакция. Расположите частные типыcatchвыше общих. - Выделяйте собственный класс, если вызывающему коду нужно различать причины отказа. Данные для реакции храните в типизированных свойствах.
- Освобождайте ресурсы в
finallyи проверьте, как поведёт себя код, если сама очистка завершится ошибкой. - Перехватывайте
Throwableна внешней границе приложения для записи сбоя и корректного завершения запроса или команды. - Проверьте успешный сценарий, ожидаемое исключение и сбой без подходящего локального обработчика. Убедитесь, что ресурсы освобождаются, а клиент получает предусмотренный ответ.
Частые вопросы
Можно ли использовать try без catch в PHP?
Да, если у try есть finally. При исключении PHP выполнит finally, затем продолжит искать подходящий catch выше по стеку.
Перехватывает ли catch (Exception $e) ошибки TypeError?
TypeError принадлежит ветви Error. Его можно перехватить через catch (TypeError $e), catch (Error $e) или catch (Throwable $e).
Как повторно выбросить исключение и сохранить его причину?
Используйте throw $e, чтобы передать тот же объект выше. При создании нового исключения передайте $e в аргумент previous. Позже исходное исключение можно получить через getPrevious().