Вывод ошибок PHP: display_errors и E_ALL

Чтобы показать ошибки PHP, поставьте в начало скрипта строки ini_set('display_errors', '1'); и error_reporting(E_ALL);. Первая заставляет PHP печатать сообщения об ошибках, вторая включает сообщения обо всех видах ошибок, включая предупреждения и устаревший код.

<?php
ini_set('display_errors', '1');
ini_set('display_startup_errors', '1');
error_reporting(E_ALL);

После этого ошибка вроде чтения переменной, которой никогда не присваивали значение, выводит сообщение с файлом и номером строки, а не проходит молча:

Warning: Undefined variable $total in /home/index.php on line 7

error_reporting() без аргумента возвращает текущую настройку в виде числа. Нажмите Run, чтобы задать уровень и расшифровать его обратно в имена:

<?php
error_reporting(E_ALL & ~E_DEPRECATED);
$level = error_reporting();

echo "Current level: $level (E_ALL is " . E_ALL . ")\n";

foreach (get_defined_constants(true)['Core'] as $name => $value) {
    if (str_starts_with($name, 'E_') && $name !== 'E_ALL') {
        echo str_pad($name, 20), ($level & $value) ? "reported" : "off", "\n";
    }
}

Каждый тип ошибки занимает один бит, поэтому E_ALL & ~E_DEPRECATED означает "всё, кроме устаревшего кода". Замените первую строку на error_reporting(E_ERROR | E_WARNING); и запустите снова.

Вывод ошибок в php.ini

Настройка в скрипте начинает действовать только после того, как скрипт запустился. Чтобы показывать ошибки во всех скриптах, включая ошибки разбора, измените php.ini (найти его можно командой php --ini):

; Development
display_errors = On
display_startup_errors = On
error_reporting = E_ALL

После правки перезапустите Apache или PHP-FPM. Встроенный сервер php -S и командная строка читают файл при каждом запуске. На виртуальном хостинге без доступа к php.ini Apache с mod_php принимает и строки в .htaccess:

php_flag display_errors on
php_value error_reporting -1

-1 устанавливает все биты, это то же самое, что E_ALL.

Уровни ошибок

PHP 8.0 превратил многие старые предупреждения в исключения: деление на ноль через / и передача неверного типа во встроенную функцию теперь выбрасывают подкласс Error, как и вызов неопределённой функции начиная с PHP 7. Все три можно перехватить:

<?php
$attempts = [
    fn() => 10 / 0,
    fn() => strlen([]),
    fn() => undefinedFunction(),
];

foreach ($attempts as $attempt) {
    try {
        $attempt();
    } catch (Throwable $e) {
        echo get_class($e), ": ", $e->getMessage(), "\n";
    }
}

Исключения описаны в try и catch. Предупреждения, notice и сообщения об устаревшем коде по-прежнему проходят через систему вывода ошибок, описанную здесь.

Запись ошибок в лог вместо вывода

На рабочем сайте посетители никогда не должны видеть сообщения об ошибках: они раскрывают пути, SQL и код. Записывайте их в лог-файл:

; Production
display_errors = Off
log_errors = On
error_log = /var/log/php/app-errors.log
error_reporting = E_ALL

Оставляйте error_reporting = E_ALL в продакшене. Если понизить уровень, ошибки никуда не денутся, вы просто перестанете о них узнавать. Свои сообщения можно писать в тот же лог через error_log():

<?php
error_log("Payment failed for order 1042");

Затем следите за файлом во время тестирования: tail -f /var/log/php/app-errors.log.

Предупреждения как исключения через set_error_handler

set_error_handler заменяет стандартную обработку предупреждений, notice и сообщений об устаревшем коде вашей функцией. Частый приём превращает каждое из них в ErrorException, и тогда забытый ключ массива останавливает код, как любое другое исключение, и его можно перехватить:

<?php
set_error_handler(function (int $severity, string $message, string $file, int $line): bool {
    throw new ErrorException($message, 0, $severity, $file, $line);
});

$prices = ['bread' => 4.5, 'milk' => 1.2];

try {
    echo "Bread costs {$prices['bread']}\n";
    echo "Cheese costs {$prices['cheese']}\n";
} catch (ErrorException $e) {
    echo "Caught: ", $e->getMessage(), " on line ", $e->getLine(), "\n";
}

restore_error_handler();

Обработчик получает уровень ошибки первым аргументом, поэтому может обрабатывать уровни по-разному. Этот только записывает в лог устаревший код, а всё остальное превращает в исключение:

<?php
set_error_handler(function (int $severity, string $message): bool {
    if ($severity === E_DEPRECATED || $severity === E_USER_DEPRECATED) {
        echo "[log] deprecated: $message\n";
        return true; // handled, PHP does nothing more
    }
    throw new ErrorException($message, 0, $severity);
});

trigger_error("oldFunction() is deprecated, use newFunction()", E_USER_DEPRECATED);

try {
    trigger_error("Config value 'timeout' is missing", E_USER_WARNING);
} catch (ErrorException $e) {
    echo "Exception: ", $e->getMessage(), "\n";
}

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

Последняя ошибка через error_get_last

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

<?php
$content = @file_get_contents('missing-config.json');

if ($content === false) {
    $error = error_get_last();
    echo "Could not read the file.\n";
    echo "Type: ", $error['type'] === E_WARNING ? 'E_WARNING' : $error['type'], "\n";
    echo "Message: ", $error['message'], "\n";
}

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

Частая ошибка: вывод ошибок включён, а страница всё равно пустая

Если вы добавили ini_set('display_errors', '1') и всё равно видите белую страницу, скорее всего, это ошибка разбора. PHP разбирает весь файл до выполнения первой строки, поэтому пропущенная ; или } останавливает всё ещё до того, как сработает ini_set. Проверьте файл из терминала, он всегда печатает сообщение:

php -l index.php

Errors parsing index.php
PHP Parse error:  syntax error, unexpected token "," in index.php on line 2

Номер строки указывает, где PHP сдался, а это часто строка после настоящей ошибки. Исправьте её, запускайте php -l снова, пока не увидите No syntax errors detected, и перезагрузите страницу.