PHPTime

Вывод ошибок в PHP: display_errors, error_reporting и логи

В PHP уровень диагностики, вывод ошибок и запись в журнал настраиваются отдельно. На локальном сервере удобно видеть ошибки сразу, а на рабочем сайте — собирать их в логах и возвращать клиенту обычный ответ.

Как PHP выбирает, показывает и записывает ошибки

За диагностику отвечают четыре настройки. Сначала PHP сверяется с маской error_reporting, затем решает, где показать или записать сообщение. Одна и та же ошибка может появиться и в ответе, и в журнале.

НастройкаЧто делает
error_reportingЗадаёт уровни сообщений, которые PHP обрабатывает стандартным способом. E_ALL включает все уровни.
display_errorsУправляет выводом диагностики в ответ или терминал. Значение stderr направляет вывод в стандартный поток ошибок в CLI, phpdbg и CGI.
log_errorsВключает автоматическую запись диагностических сообщений в журнал.
error_logЗадаёт файл журнала или системный журнал (syslog). При пустом значении место записи определяет среда запуска PHP.

Для разработки обычно подходят E_ALL, display_errors=On и log_errors=On. На рабочем сайте оставляйте E_ALL и логирование, а вывод отключайте. Текст ошибки может содержать пути к файлам и детали приложения. В API такой текст ещё и портит JSON-ответ.

Как включить вывод ошибок PHP через ini_set

Если нужно разобраться с локальным скриптом, поставьте настройки в начало исполняемого файла, до подключения остальных файлов. declare(strict_types=1) здесь включает строгую проверку скалярных типов для вызовов из этого файла. На уровни диагностики эта директива не влияет.

PHP
<?php
declare(strict_types=1);

// Включаем диагностику для локального запуска.
error_reporting(E_ALL);
ini_set('display_errors', '1');
ini_set('log_errors', '1');

// Проверяем, что предупреждение видно.
trigger_error('Проверка вывода ошибок', E_USER_WARNING);

ini_set() меняет настройку на время текущего запуска скрипта. При успехе функция возвращает прежнее значение строкой, при отказе — false. Если PHP-FPM закрепил директиву через php_admin_value или php_admin_flag, переопределить её из PHP-кода нельзя.

Почему display_errors не помогает при синтаксической ошибке

Если синтаксическая ошибка находится в самом запускаемом файле, PHP не успеет выполнить его ini_set(). Для такого случая настройте вывод до запуска или проверьте синтаксис отдельно. Вызов php -l проверяет указанный файл без исполнения и не обходит файлы, подключённые через require или include.

Shell
# Проверяем синтаксис файла.
php -l public/index.php

# Включаем диагностику до запуска скрипта.
php -d display_errors=stderr -d error_reporting=-1 public/index.php

Параметры -d действуют для одного CLI-запуска. Значение -1 задаёт маску со всеми установленными битами. Для ошибок на этапе запуска PHP есть отдельная настройка display_startup_errors. Её можно временно включить в локальной конфигурации для диагностики, например при сбое загрузки расширения.

Настройка php.ini, PHP-FPM и CLI

CLI и веб-приложение могут загружать разные файлы php.ini, разные дополнительные .ini и даже работать на разных версиях PHP. Команда php --ini показывает конфигурацию CLI. Для веб-запроса смотрите значения из того же окружения, в котором возникает ошибка.

PHP
<?php
declare(strict_types=1);

// Запускайте только в закрытом окружении.
var_export([
    'sapi' => PHP_SAPI,
    'ini' => php_ini_loaded_file(),
    'extra_ini' => php_ini_scanned_files(),
    'display_errors' => ini_get('display_errors'),
    'log_errors' => ini_get('log_errors'),
    'error_log' => ini_get('error_log'),
    'error_reporting' => error_reporting(),
]);

Для рабочего сайта в php.ini можно задать такой профиль. Путь к журналу приведён как пример для Linux. Подставьте путь для своего приложения и проверьте доступ на запись от имени пользователя, который исполняет PHP.

ini
; Профиль рабочего сайта.
error_reporting = E_ALL
display_errors = Off
display_startup_errors = Off
log_errors = On
error_log = /var/log/myapp/php-error.log

Для одного сайта на PHP-FPM настройки можно задать в конфигурации его пула. После изменения php.ini или конфига пула перезагрузите или перечитайте конфигурацию соответствующей службы PHP. Если хостинг разрешает .user.ini, он подходит для разрешённых директив в CGI и FastCGI. Изменения вступают в силу с учётом user_ini.cache_ttl.

Директивы php_flag в .htaccess относятся к PHP, работающему как модуль Apache. На связке Apache с PHP-FPM они могут вызвать HTTP 500. В конфигурации Nginx директивы PHP из php.ini напрямую не применяются.

error_reporting, уровни ошибок и исключения

error_reporting() без аргументов возвращает текущую маску, с аргументом — меняет её и возвращает прежнюю. Обычно достаточно error_reporting(E_ALL). Если на время миграции нужно отключить именно сообщения об устаревании, маска E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED исключает оба уровня и оставляет остальные. В PHP 8.4 изменилось числовое значение E_ALL, поэтому используйте именованную константу вместо значения, скопированного из старого конфига.

  • E_WARNING — предупреждение, после которого выполнение обычно продолжается. Например, чтение отсутствующего ключа массива.
  • E_NOTICE — уведомление. В PHP 8 ряд ситуаций, которые раньше давали notice, повышен до warning. Пример — чтение неопределённой переменной.
  • E_DEPRECATED — сигнал от PHP или его расширения об устаревшей возможности. E_USER_DEPRECATED может отправить библиотека или приложение.
  • E_PARSE и E_ERROR — ошибки, при которых обычное выполнение прерывается. Например, синтаксическая ошибка в запускаемом файле или исчерпание лимита памяти.

В PHP 8 многие ошибки типов и значений представлены объектами TypeError и ValueError. Оба реализуют Throwable, поэтому их можно перехватить через try/catch. Перехватывайте конкретный тип там, где приложение может обработать ошибку. Общий catch (Throwable $e) уместен на границе запроса или фоновой задачи, где приложение пишет в журнал и формирует ответ или завершает задачу с ошибкой.

PHP
<?php
declare(strict_types=1);

try {
    // Глубина декодирования должна быть больше нуля.
    json_decode('{}', true, 0, JSON_THROW_ON_ERROR);
} catch (ValueError $e) {
    error_log('Ошибка настройки декодирования: ' . $e->getMessage());
}

При перехвате исключения запись в журнал нужно сделать явно, если она необходима. set_error_handler() решает другую задачу — обрабатывает поддерживаемые диагностические уровни, например E_WARNING. Он может вызываться и для уровня, исключённого текущей маской. Если обработчик должен её учитывать, проверяйте (error_reporting() & $severity) !== 0. Возврат false передаёт сообщение стандартному обработчику PHP.

Где искать логи PHP и как работает error_log

У error_log два употребления. Директива задаёт назначение журнала, а функция error_log() отправляет сообщение явно. Вызов функции с одним аргументом использует настроенное назначение и работает независимо от log_errors и error_reporting. В записи полезен идентификатор запроса или задачи, по которому можно связать события. Пароли, токены и полные тела запросов в журнал не передавайте.

PHP
<?php
declare(strict_types=1);

// В рабочем приложении используйте идентификатор текущего запроса.
$requestId = bin2hex(random_bytes(8));
error_log('Проверка журнала PHP, request_id=' . $requestId);

Если задан файл, начните с него. Если директива пуста, CLI пишет в stderr, а веб-режим передаёт сообщения своему обработчику. Ищите их в журнале Apache, PHP-FPM или службы, а в контейнере проверьте вывод контейнера и настройки сбора логов. У PHP-FPM есть собственный журнал службы. Значение error_log в конфигурации FPM и ini_get('error_log') в приложении могут указывать на разные места.

Shell
# Следим за файлом журнала при повторе запроса.
tail -F /var/log/myapp/php-error.log

# Пример имени службы для PHP-FPM 8.4 под systemd.
journalctl -u php8.4-fpm -n 100 --no-pager

Если лог пуст, проверьте путь, права на каталог и файл, владельца после ротации и настройки фактического пула. Сделайте две пробы в закрытом окружении: error_log() проверит маршрут записи, а trigger_error('Проверка', E_USER_WARNING) — автоматическое логирование предупреждений. У error_log() с типом сообщения по умолчанию результат true сам по себе не подтверждает доставку. Найдите пробную строку в журнале.

Что означает PHP Deprecated в версиях 8.3–8.5

Сообщение Deprecated означает, что код использует устаревшую возможность. Обычно выполнение продолжается. При обновлении PHP или библиотеки такая возможность может исчезнуть, поэтому исправляйте причину по сообщению и месту вызова. Если оно указывает на зависимость, проверьте, есть ли совместимая версия пакета.

  • PHP 8.3. Вызов get_class() или get_parent_class() без аргумента устарел. Передайте объект или имя класса там, где соответствующая функция это допускает. Внутри класса используйте self::class, если нужно имя класса, в котором написан код, или static::class, если важен класс позднего статического связывания.
  • PHP 8.4. Устарели неявно nullable-параметры, например string $value = null. Объявляйте тип явно как ?string $value = null или string|null $value = null. Устарел и уровень E_STRICT: удалите ссылки на эту константу из масок.
  • PHP 8.5. Устарело использование оператора обратных кавычек для выполнения команды оболочки. Если вызов оболочки нужен, используйте явный shell_exec() для доверенной команды.
PHP
<?php
declare(strict_types=1);

// Явно разрешаем null в параметре.
function formatLabel(?string $value = null): string
{
    return $value ?? 'Без названия';
}

echo formatLabel();

При переходе на любую из этих версий учитывайте и изменения предыдущих выпусков PHP 8.x. Например, с PHP 8.2 создание динамического свойства у обычного класса вызывает E_DEPRECATED. Если набор свойств известен, объявите их в классе. Для произвольных ключей обычно подходит отдельный массив. Прогоняйте код с E_ALL в тестовом окружении под целевой версией PHP, чтобы увидеть предупреждения в реально используемых сценариях.

Чек-лист, если ошибка не видна

  1. Определите, где воспроизводится сбой: в веб-запросе, CLI, фоновой задаче или контейнере. Проверьте версию PHP и активную конфигурацию именно там.
  2. При пустой странице или HTTP 500 начните с журнала. Если подозреваете синтаксическую ошибку, проверьте изменённые файлы через php -l под нужной версией PHP.
  3. На локальном запуске выставьте E_ALL и включите display_errors. Для CLI-команды с машинно читаемым выводом направьте диагностику в stderr.
  4. На рабочем сайте проверьте display_errors=Off, log_errors=On и фактическое назначение error_log. Найдите тестовое сообщение в журнале и убедитесь, что ответ клиенту сохраняет ожидаемый статус и формат.
  5. Если проба проходит, а нужной записи нет, проверьте маску уровней, пользовательский обработчик и блоки catch. Для Deprecated определите, нужно ли исправить свой код или обновить зависимость.

Частые вопросы

Как быстро включить вывод ошибок PHP в локальном скрипте?

В начале файла вызовите error_reporting(E_ALL) и ini_set('display_errors', '1'). Если файл содержит синтаксическую ошибку, задайте display_errors до запуска через php.ini или параметр php -d. Для проверки синтаксиса используйте php -l.

Как узнать, куда PHP пишет error log?

Посмотрите ini_get('error_log') в том же окружении, где возникает ошибка. Если значение пустое, CLI пишет в stderr, а веб-режим использует обработчик своей среды. Для проверки отправьте уникальное сообщение через error_log() и найдите его в журнале.

Можно ли скрыть PHP Deprecated, сохранив остальные предупреждения?

Да. Маска E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED исключает сообщения об устаревании из стандартного вывода и логирования. На рабочем сайте можно скрыть всю диагностику от посетителей через display_errors=Off и оставить E_ALL для журнала.

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

Ещё в разделе «Справочник PHP»

Дата и время в PHP: date, DateTime и часовые пояса

Как получить текущую дату и время в PHP, настроить часовой пояс, разобрать строку и отформатировать дату с date(), strtotime() и DateTimeImmutable.

8 мин

Загрузка файлов на сервер в PHP: $_FILES и безопасность

Как принять файл через $_FILES, проверить размер, MIME-тип и расширение, сохранить его вне публичной папки, выдать на скачивание и обработать ZIP.

10 мин

Интерфейсы, трейты и перечисления (enum) в PHP

Как применять interface, trait и enum в PHP 8.3–8.5: рабочие примеры, правила совместимости, разрешение конфликтов и разбор типичных ошибок.

9 мин

Исключения в PHP: try, catch, finally и свои классы ошибок

Как работают исключения в PHP 8.3–8.5: try, catch, finally и throw, перехват Exception и Error, собственные классы и типичные ошибки обработки.

9 мин