trigger_error()

Введение

trigger_error() позволяет вашему коду вызывать сообщения об ошибках PHP так же, как это делает сам движок для встроенных ошибок. Это стандартный способ сообщить о некорректном вызове функции — отсутствующий аргумент, значение вне допустимого диапазона, устаревший вызов — без выброса исключения и без использования произвольного echo. Поскольку сообщение проходит через обычный конвейер ошибок PHP, оно учитывает error_reporting, может автоматически записываться в журнал и может быть перехвачено пользовательским обработчиком ошибок.

На этой странице объясняется, что делает trigger_error(), её синтаксис и уровни ошибок, а также приведены примеры для каждого уровня и практический пример проверки входных данных.

Что такое функция trigger_error()?

trigger_error() генерирует ошибку пользовательского уровня — ошибку, которую программа создаёт намеренно, в отличие от ошибок, генерируемых самим движком PHP. При её вызове PHP ведёт себя так же, как если бы сам столкнулся с этой ошибкой: применяет текущую маску error_reporting, передаёт сообщение активному обработчику ошибок (или обработчику по умолчанию) и, в зависимости от уровня, может остановить скрипт.

Два распространённых заблуждения:

• trigger_error() генерирует ошибку, а не исключение. Она не будет перехвачена блоком try/catch, если только пользовательский обработчик не преобразует её в исключение (распространённый паттерн показан ниже).
• Функция всегда возвращает false, поэтому return trigger_error(...) почти никогда не является тем, что нужно.

Синтаксис trigger_error()

trigger_error(string $message, int $error_level = E_USER_NOTICE): bool

Уровень ошибки должен быть одним из следующих:

• E_USER_ERROR — фатальная ошибка. При использовании обработчика по умолчанию скрипт немедленно останавливается. При наличии пользовательского обработчика скрипт продолжает работу, если обработчик не останавливает его (возвращает false и передаёт управление PHP, или вызывает exit()).
• E_USER_WARNING — нефатальное предупреждение. Скрипт продолжает выполнение.
• E_USER_NOTICE — информационное сообщение. Скрипт продолжает выполнение. Это значение по умолчанию.

При передаче любой другой константы (например E_WARNING) будет сгенерировано собственное предупреждение E_USER_WARNING, а переданное значение будет проигнорировано.

trigger_error() учитывает текущий уровень error_reporting: если сгенерированный уровень замаскирован, ничего не сообщается. Так, если установлен error_reporting(E_ALL & ~E_USER_NOTICE), сгенерированное уведомление будет молча отброшено.

Важно для PHP 8.4+: генерация E_USER_ERROR устарела. Теперь рекомендуемым способом сигнализировать о фатальном условии пользовательского уровня является выброс исключения. Два других уровня остаются полностью поддерживаемыми.

Простое уведомление с обработчиком по умолчанию

Минимальное использование trigger_error() — один вызов. При обработчике ошибок PHP по умолчанию и включённом отображении ошибок функция выводит отформатированную строку, и выполнение продолжается (уведомления не являются фатальными):

<?php
echo "Before\n";
trigger_error("Something worth noting", E_USER_NOTICE);
echo "After\n";

Вывод (при включённом display_errors):

Before

Notice: Something worth noting in /path/to/script.php on line 3
After

Скрипт доходит до последнего echo, поскольку уведомление не останавливает выполнение.

Различение уровней с помощью пользовательского обработчика

Пользовательский обработчик ошибок даёт полный контроль над тем, как отображается каждый уровень. Обработчик получает числовое значение уровня в параметре $errno, что позволяет сопоставить его с меткой и принять решение о дальнейших действиях.

<?php
function custom_error_handler($errno, $errstr, $errfile, $errline) {
  $label = match ($errno) {
    E_USER_ERROR   => 'ERROR',
    E_USER_WARNING => 'WARNING',
    E_USER_NOTICE  => 'NOTICE',
    default        => 'UNKNOWN',
  };
  echo "[$label] $errstr (line $errline)\n";
  // Returning true tells PHP we handled it, so the default handler is skipped.
  return true;
}

set_error_handler("custom_error_handler");

trigger_error("Disk is almost full", E_USER_NOTICE);
trigger_error("Cache miss, falling back to DB", E_USER_WARNING);

echo "Script finished\n";

Вывод:

[NOTICE] Disk is almost full (line 16)
[WARNING] Cache miss, falling back to DB (line 17)
Script finished

Обработчик возвращает true, сообщая PHP о том, что ошибка была обработана, поэтому обработчик по умолчанию пропускается и скрипт продолжает выполнение. Ветка E_USER_ERROR в match оставлена для полноты, но учтите, что при использовании обработчика по умолчанию E_USER_ERROR остановит скрипт до вывода "Script finished" — а в PHP 8.4+ генерация этого уровня устарела.

Практическое применение: проверка аргументов функции

Наиболее распространённое реальное применение trigger_error() — защита функции от некорректных входных данных: генерация предупреждения, если вызывающий код передаёт недопустимое значение, с последующим возвратом безопасного значения по умолчанию:

<?php
function divide($a, $b) {
  if ($b == 0) {
    trigger_error("divide(): division by zero, returning 0", E_USER_WARNING);
    return 0;
  }
  return $a / $b;
}

echo divide(10, 2), "\n";   // 5
echo divide(10, 0), "\n";   // warning + 0

Вывод (при включённом display_errors):

5

Warning: divide(): division by zero, returning 0 in /path/to/script.php on line 4
0

Этот паттерн сохраняет трассировку стека вызывающего кода и номер строки в сообщении, что значительно упрощает поиск проблемного вызова по сравнению с простым echo.

Преобразование ошибок в исключения

Если вы предпочитаете обрабатывать проблемы с помощью try/catch, пользовательский обработчик может преобразовать сгенерированную ошибку в ErrorException. Это мост между системой ошибок PHP и её системой исключений:

<?php
set_error_handler(function ($errno, $errstr, $errfile, $errline) {
  throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
});

try {
  trigger_error("Recoverable problem", E_USER_WARNING);
} catch (ErrorException $e) {
  echo "Caught: " . $e->getMessage() . "\n";
}

Вывод:

Caught: Recoverable problem

Поскольку обработчик выбрасывает исключение, предупреждение никогда не попадает в стандартный вывод ошибок — оно передаётся в блок catch.

Распространённые ошибки

• Это не исключение. Без обработчика, который выбрасывает исключение, блок try/catch не перехватит сгенерированную ошибку.
• error_reporting может скрыть её. Если уровень замаскирован, сообщение исчезнет без каких-либо признаков. Проверьте текущий уровень с помощью error_reporting().
• E_USER_ERROR устарел в PHP 8.4+. Вместо этого для фатальных условий пользовательского уровня выбрасывайте исключение (или вызывайте die()).
• Сообщение обрезается на 1024 байтах — формулируйте кратко.

Заключение

trigger_error() — идиоматический способ генерации пользовательских уровней E_USER_NOTICE, E_USER_WARNING или (устаревшего) E_USER_ERROR. Функция включает ваши сообщения в стандартный конвейер PHP, чтобы они учитывали error_reporting, могли записываться в журнал и перехватываться пользовательским обработчиком ошибок — или преобразовываться в исключения, когда нужна семантика try/catch. Для нового кода с фатальными условиями предпочтительнее выбрасывать исключения вместо использования E_USER_ERROR.

Практика