Вывод ошибок в 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
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.
# Проверяем синтаксис файла.
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
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.
; Профиль рабочего сайта.
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
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
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') в приложении могут указывать на разные места.
# Следим за файлом журнала при повторе запроса.
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
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, чтобы увидеть предупреждения в реально используемых сценариях.
Чек-лист, если ошибка не видна
- Определите, где воспроизводится сбой: в веб-запросе, CLI, фоновой задаче или контейнере. Проверьте версию PHP и активную конфигурацию именно там.
- При пустой странице или HTTP 500 начните с журнала. Если подозреваете синтаксическую ошибку, проверьте изменённые файлы через
php -lпод нужной версией PHP. - На локальном запуске выставьте
E_ALLи включитеdisplay_errors. Для CLI-команды с машинно читаемым выводом направьте диагностику вstderr. - На рабочем сайте проверьте
display_errors=Off,log_errors=Onи фактическое назначениеerror_log. Найдите тестовое сообщение в журнале и убедитесь, что ответ клиенту сохраняет ожидаемый статус и формат. - Если проба проходит, а нужной записи нет, проверьте маску уровней, пользовательский обработчик и блоки
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 для журнала.