set_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

set_error_handler — Устанавливает пользовательский обработчик ошибок

Описание

set_error_handler(?callable $callback, int $error_levels = E_ALL): ?callable

Функция устанавливает пользовательскую callback-функцию обработки ошибок, которые возникают в скрипте.

Функция определяет пользовательские обработчики ошибок, которые возникают во время выполнения кода. Обработчики устанавливают в приложениях, которым требуется очистить файлы или данные при критичной для приложения ошибке или при ошибке, которую сгенерировали функцией trigger_error() в ответ на конкретные условия.

Важно помнить: PHP-движок передаст ошибки, типы которых указали в параметре error_levels, в стандартный обработчик ошибок, только если callback-функция вернёт значение false. Движок вызовет пользовательский обработчик ошибок, даже если уровень ошибки не соответствует настройкам, которые установили функцией error_reporting(). При этом текущее значение директивы error_reporting остаётся доступным для чтения, чтобы выполнить операции, которые соответствуют ситуации.

Обратите также внимание, за остановку выполнения скрипта функцией exit(), когда требуется, отвечает пользовательский обработчик. Выполнение скрипта продолжится со следующей инструкции после той, которая вызвала ошибку, если функция обработки ошибок вернёт управление.

Пользовательской функцией невозможно обработать ошибки следующих типов: E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING независимо от места, в котором возникла ошибка, и бо́льшую часть ошибок уровня E_STRICT, которые возникли в файле вызова функции set_error_handler().

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

Список параметров

callback

При передаче значения null обработчик сбрасывается в состояние по умолчанию, иначе обработчиком становится callback-функция со следующей сигнатурой:

handler(
    int $errno,
    string $errstr,
    string $errfile = ?,
    int $errline = ?,
    array $errcontext = ?
): bool

errno: В первый параметр — errno передаётся целое число, которое указывает на уровень ошибки.
errstr: Во второй параметр — errstr передаётся строка с сообщением об ошибке.
errfile: В третий параметр — errfile передаётся строка с названием файла, в котором возникла ошибка, если параметр определили в функции обратного вызова.
errline: В четвёртный параметр — errline передаётся целочисленный номер строки, в которой возникла ошибка, если параметр определили в функции обратного вызова.
errcontext: В пятый параметр — errcontext передаётся массив, который указывает на активную таблицу символов в точке, в которой возникла ошибка, если параметр определили в функции обратного вызова. Другими словами, параметр errcontext будет содержать массив переменных той области действия, в которой возникла ошибка. Контекст ошибки не модифицируют в пользовательском обработчике ошибок, чтобы при возврате управления сохранить согласованность данных.
Внимание
С PHP 7.2.0 параметр УСТАРЕЛ, а в PHP 8.0.0 параметр УДАЛИЛИ. Обработчик выдаст ошибку "too few arguments", если в callback-функции параметр определили, но не установили значение по умолчанию.

При возврате из функции значения false управление передаётся стандартному обработчику ошибок.

error_levels

Параметр устанавливает маску уровней ошибок, при которых сработает callback-функция. Параметр управляет срабатыванием пользовательского обработчика ошибок так же, как ini-настройка error_reporting управляет отображением ошибок. Без установки маски движок вызывает callback-функцию для каждой ошибки и игнорирует настройку директивы error_reporting.

Возвращаемые значения

Функция возвращает предыдущий обработчик ошибок как значение с типом callable, если такой обработчик определили, или значение null, если за текущую обработку ошибок отвечает встроенный обработчик.

Список изменений

Версия Описание

8.0.0 Параметр errcontext удалили. Контекст ошибки больше не передаётся в пользовательскую callback-функцию.

7.2.0 Параметр errcontext устарел. При определении параметра в пользовательском обработчике функция выдаст ошибку уровня E_DEPRECATED.

Версия	Описание
8.0.0	Параметр `errcontext` удалили. Контекст ошибки больше не передаётся в пользовательскую callback-функцию.
7.2.0	Параметр `errcontext` устарел. При определении параметра в пользовательском обработчике функция выдаст ошибку уровня `E_DEPRECATED`.

Примеры

Пример #1 Обработка ошибок функциями set_error_handler() и trigger_error()

Пример ниже демонстрирует обработку внутренних исключений путём вызова ошибок разных типов и их обработки пользовательской функцией:

<?php

// Функция обработки ошибок
function myErrorHandler($errno, $errstr, $errfile, $errline)
{
    if (!(error_reporting() & $errno)) {
        // Директива error_reporting не включает этот код ошибки,
        // поэтому пусть ошибку обрабатывает стандартный обработчик ошибок PHP
        return false;
    }

    // Переменной $errstr требуется экранирование:
    $errstr = htmlspecialchars($errstr);

    switch ($errno) {
        case E_USER_ERROR:
            echo "<b>Пользовательская ОШИБКА</b> [$errno] $errstr<br />\n";
            echo "  Фатальная ошибка в строке $errline файла $errfile";
            echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
            echo "Завершение работы...<br />\n";
            exit(1);

        case E_USER_WARNING:
            echo "<b>Пользовательское ПРЕДУПРЕЖДЕНИЕ</b> [$errno] $errstr<br />\n";
            break;

        case E_USER_NOTICE:
            echo "<b>Пользовательское УВЕДОМЛЕНИЕ</b> [$errno] $errstr<br />\n";
            break;

        default:
            echo "Неизвестная ошибка: [$errno] $errstr<br />\n";
            break;
    }

    /* Не запускаем внутренний обработчик ошибок PHP */
    return true;
}

// Функция тестирования обработчика ошибок
function scale_by_log($vect, $scale)
{
    if (!is_numeric($scale) || $scale <= 0) {
        trigger_error("log(x) для x <= 0 не определён, вы используете: scale = $scale", E_USER_ERROR);
    }

    if (!is_array($vect)) {
        trigger_error("Некорректный входной вектор, пропущен массив значений", E_USER_WARNING);
        return null;
    }

    $temp = array();
    foreach ($vect as $pos => $value) {
        if (!is_numeric($value)) {
            trigger_error("Значение на позиции $pos не относится к числу, присваиваем значение 0 (ноль)", E_USER_NOTICE);
            $value = 0;
        }
        $temp[$pos] = log($scale) * $value;
    }

    return $temp;
}

// Переключаемся на пользовательский обработчик
$old_error_handler = set_error_handler("myErrorHandler");

// Вызовем ряд ошибок, и вначале определим смешанный массив с нечисловым элементом
echo "vector a\n";
$a = array(2, 3, "foo", 5.5, 43.3, 21.11);
print_r($a);

// Теперь создадим ещё один массив
echo "----\nvector b - a notice (b = log(PI) * a)\n";
/* Значение на позиции $pos не относится к числу, присваиваем 0 (ноль)*/
$b = scale_by_log($a, M_PI);
print_r($b);

// Проблема, вместо массива передали строку
echo "----\nvector c - a warning\n";
/* Некорректный входной вектор, ожидается массив значений */
$c = scale_by_log("not array", 2.3);
var_dump($c); // NULL

// Критическая ошибка, логарифм нуля или отрицательного числа не определён
echo "----\nvector d - fatal error\n";
/* log(x) для x <= 0 не определён, передали: scale = $scale */
$d = scale_by_log($a, -2.5);

var_dump($d); // До этого места никогда не дойдём

?>

Вывод приведённого примера будет похож на:

vector a
Array
(
    [0] => 2
    [1] => 3
    [2] => foo
    [3] => 5.5
    [4] => 43.3
    [5] => 21.11
)
----
vector b - a notice (b = log(PI) * a)
<b>Пользовательское УВЕДОМЛЕНИЕ</b> [1024] Значение на позиции 2 не относится к числу, присваиваем значение 0 (ноль)<br />
Array
(
    [0] => 2.2894597716988
    [1] => 3.4341896575482
    [2] => 0
    [3] => 6.2960143721717
    [4] => 49.566804057279
    [5] => 24.165247890281
)
----
vector c - a warning
<b>Пользовательское ПРЕДУПРЕЖДЕНИЕ</b> [512] Некорректный входной вектор, пропущен массив значений<br />
NULL
----
vector d - fatal error
<b>Пользовательская ОШИБКА</b> [256] log(x) для x &lt;= 0 не определён, вы используете: scale = -2.5<br />
  Фатальная ошибка в строке 44 файла /in/IYIBO, PHP 7.4.33 (Linux)<br />
Завершение работы...<br />

Смотрите также

ErrorException
error_reporting() - Определяет, о каких PHP-ошибках сообщать
restore_error_handler() - Восстанавливает предыдущую функцию обработчика ошибок
get_error_handler() - Получает пользовательскую функцию обработчика ошибок
trigger_error() - Генерирует предупреждение, уведомление или сообщение об ошибке на уровне пользователя
Константы уровней ошибок