Настройка во время выполнения
Поведение этих функций зависит от установок в php.ini.
Имя | По умолчанию | Место изменения | Список изменений |
---|---|---|---|
error_reporting | NULL | PHP_INI_ALL | |
display_errors | «1» | PHP_INI_ALL | |
display_startup_errors | «1» | PHP_INI_ALL |
До PHP 8.0.0 значение по умолчанию было "0" .
|
log_errors | «0» | PHP_INI_ALL | |
log_errors_max_len | «1024» | PHP_INI_ALL | |
ignore_repeated_errors | «0» | PHP_INI_ALL | |
ignore_repeated_source | «0» | PHP_INI_ALL | |
report_memleaks | «1» | PHP_INI_ALL | |
track_errors | «0» | PHP_INI_ALL | Объявлено устаревшим в PHP 7.2.0, удалено в PHP 8.0.0. |
html_errors | «1» | PHP_INI_ALL | |
xmlrpc_errors | «0» | PHP_INI_SYSTEM | |
xmlrpc_error_number | «0» | PHP_INI_ALL | |
docref_root | «» | PHP_INI_ALL | |
docref_ext | «» | PHP_INI_ALL | |
error_prepend_string | NULL | PHP_INI_ALL | |
error_append_string | NULL | PHP_INI_ALL | |
error_log | NULL | PHP_INI_ALL | |
error_log_mode | 0o644 | PHP_INI_ALL | Доступно, начиная с PHP 8.2.0 |
syslog.facility | «LOG_USER» | PHP_INI_SYSTEM | Доступно, начиная с PHP 7.3.0. |
syslog.filter | «no-ctrl» | PHP_INI_ALL | Доступно, начиная с PHP 7.3.0. |
syslog.ident | «php» | PHP_INI_SYSTEM | Доступно, начиная с PHP 7.3.0. |
Для подробного описания констант
PHP_INI_*, обратитесь к разделу Где могут быть установлены параметры конфигурации.
Краткое разъяснение конфигурационных
директив.
-
error_reporting
int -
Задаёт уровень протоколирования ошибки. Параметр может быть либо числом,
представляющим битовое поле, либо именованной константой.
Соответствующие уровни и константы приведены в разделе
Предопределённые константы,
а также в php.ini. Для установки настройки во время выполнения используйте функцию
error_reporting(). Смотрите также описание директивы
display_errors.Значение по умолчанию равно
E_ALL
.До PHP 8.0.0 значение по умолчанию было:
.E_ALL
&
~E_NOTICE
&
~E_STRICT
&
~E_DEPRECATED
При этой настройке не отображаются уровни ошибокE_NOTICE
,
E_STRICT
иE_DEPRECATED
.Замечание:
PHP-константы за пределами PHPИспользование PHP-констант за пределами PHP, например в файле
httpd.conf, не имеет смысла, так как в таких случаях требуются
целочисленные значения (int). Более того, с течением времени будут
добавляться новые уровни ошибок, а максимальное значение константы
E_ALL
соответственно будет расти. Поэтому в месте, где
предполагается указатьE_ALL
, лучше задать большое целое число,
чтобы перекрыть все возможные битовые поля. Таким числом может быть, например,
2147483647
(оно включит все возможные ошибки, не
толькоE_ALL
). -
display_errors
string -
Эта настройка определяет, требуется ли выводить ошибки на экран вместе
с остальным выводом, либо ошибки должны быть скрыты от пользователя.Значение
"stderr"
посылает ошибки в потокstderr
вместоstdout
.Замечание:
Эта функциональность предназначена только для разработки и не должен использоваться в
готовых производственных системах (например, системах, имеющих доступ в интернет).Замечание:
Несмотря на то, что display_errors может быть установлена во время выполнения
(функцией ini_set()), это ни на что не повлияет, если в скрипте есть
фатальные ошибки. Это обусловлено тем, что ожидаемые действия программы во время
выполнения не получат управления (не будут выполняться). -
display_startup_errors
bool -
Даже если display_errors включена, ошибки, возникающие во время запуска PHP, не будут
отображаться. Настойчиво рекомендуем включать директиву display_startup_errors только
для отладки. -
log_errors
bool -
Отвечает за выбор журнала, в котором будут сохраняться сообщения об ошибках. Это
может быть журнал сервера или error_log.
Применимость этой настройки зависит от конкретного сервера.Замечание:
Настоятельно рекомендуем при работе на готовых работающих
web сайтах протоколировать ошибки там, где они отображаются. -
log_errors_max_len
int -
Задание максимальной длины log_errors в байтах. В
error_log добавляется информация
об источнике. Значение по умолчанию 1024. Установка значения в 0
позволяет снять ограничение на длину log_errors. Это ограничение
распространяется на записываемые в журнал ошибки, на отображаемые ошибки,
а также на $php_errormsg, но не на явно вызываемые функции,
такие как error_log().Если используется int, значение измеряется байтами. Вы также можете использовать сокращённую запись, которая описана в этом разделе FAQ.
-
ignore_repeated_errors
bool -
Не заносить в журнал повторяющиеся ошибки. Ошибка считается
повторяющейся, если происходит в том же файле и в той же строке, и если настройка
ignore_repeated_source выключена. -
ignore_repeated_source
bool -
Игнорировать источник ошибок при пропуске повторяющихся сообщений. Когда
эта настройка включена, повторяющиеся сообщения об ошибках не будут
заноситься в журнал вне зависимости от того, в каких файлах и строках они происходят. -
report_memleaks
bool -
Если настройка включена (по умолчанию), будет формироваться отчёт об утечках памяти,
зафиксированных менеджером памяти Zend. На POSIX платформах этот отчёт будет
направляться в поток stderr. На Windows платформах он будет посылаться в отладчик
функцией OutputDebugString(), просмотреть отчёт в этом случае можно с помощью утилит,
вроде » DbgView. Эта настройка имеет
смысл в сборках, предназначенных для отладки. При этом
E_WARNING
должна быть включена в список error_reporting. -
track_errors
bool -
Если включена, последняя произошедшая ошибка будет первой в переменной
$php_errormsg. -
html_errors
bool -
Если разрешена, сообщения об ошибках будут включать теги HTML. Формат для
HTML-ошибок производит нажимаемые ссылки, ведущие на описание ошибки, либо
функии, в которой она произошла. За такие ссылки ответственны
docref_root и
docref_ext.Если запрещена, то ошибки будут выдаваться простым текстом, без форматирования.
-
xmlrpc_errors
bool -
Если включена, то нормальное оповещение об ошибках отключается и, вместо него,
ошибки выводятся в формате XML-RPC. -
xmlrpc_error_number
int -
Используется в качестве значения XML-RPC элемента faultCode.
-
docref_root
string -
Новый формат ошибок содержит ссылку на страницу с описанием ошибки или
функции, вызвавшей эту ошибку. Можно разместить копию
описаний ошибок и функций локально и задать ini директиве значение
URL этой копии. Если, например, локальная копия описаний доступна по
адресу"/manual/"
, достаточно прописать
docref_root=/manual/
. Дополнительно, необходимо
задать значение директиве docref_ext, отвечающей за соответствие
расширений файлов файлам описаний вашей локальной копии,
docref_ext=.html
. Также возможно использование
внешних ссылок. Например,
docref_root=http://manual/en/
или
docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon
&url=http%3A%2F%2Fwww.php.net%2F"В большинстве случаев вам потребуется, чтобы значение docref_root оканчивалось
слешем"/"
. Тем не менее, бывают случаи, когда
это не требуется (смотрите выше, второй пример).Замечание:
Эта функциональность предназначена только для разработки, так как он облегчает
поиск описаний функций и ошибок. Не используйте его в готовых
производственных системах (например, имеющих доступ в интернет). -
docref_ext
string -
Смотрите docref_root.
Замечание:
Значение docref_ext должно начинаться с точки
"."
. -
error_prepend_string
string -
Строка, которая будет выводиться непосредственно перед сообщением об ошибке.
Используется только тогда, когда на экране отображается сообщение об ошибке.
Основная цель — добавить дополнительную HTML-разметку к сообщению об ошибке. -
error_append_string
string -
Строка, которая будет выводиться после сообщения об ошибке.
Используется только тогда, когда на экране отображается сообщение об ошибке.
Основная цель — добавить дополнительную HTML-разметку к сообщению об ошибке. -
error_log
string -
Имя файла, в который будут добавляться сообщения об ошибках. Файл
должен быть открыт для записи пользователем веб-сервера. Если
используется специальное значениеsyslog
, то
сообщения будут посылаться в системный журнал. На Unix-системах это
syslog(3), на Windows NT — журнал событий. Смотрите также: syslog().
Если директива не задана, ошибки будут направляться в SAPI журналы.
Например, это могут быть журналы ошибок Apache или поток
stderr
командной строки CLI.
Смотрите также функцию error_log(). -
error_log_mode
int -
Режим файла, описанного в error_log.
-
syslog.facility
string -
Указывает, какой тип программы регистрирует сообщение.
Действует только в том случае, если опция error_log установлена в «syslog». -
syslog.filter
string -
Указывает тип фильтра для фильтрации регистрируемых сообщений.
Разрешённые символы передаются без изменений; все остальные записываются в шестнадцатеричном представлении с префиксомx
.-
all
– строка будет разделена
на символы новой строки и все символы будут переданы без изменений
-
ascii
– строка будет разделена
на символы новой строки, а любые непечатаемые 7-битные символы ASCII будут экранированы
-
no-ctrl
– строка будет разделена
на символы новой строки, а любые непечатаемые символы будут экранированы
-
raw
– все символы передаются в системный
журнал без изменений, без разделения на новые строки (идентично PHP до 7.3)
Параметр влияет на ведение журнала через error_log установленного в «syslog» и вызовы syslog().
Замечание:
Тип фильтра
raw
доступен начиная с PHP 7.3.8 и PHP 7.4.0.
Директива не поддерживается в Windows.
-
-
syslog.ident
string -
Определяет строку идентификатора, которая добавляется к каждому сообщению.
Действует только в том случае, если опция error_log установлена в «syslog».
cjakeman at bcs dot org ¶
13 years ago
Using
<?php ini_set('display_errors', 1); ?>
at the top of your script will not catch any parse errors. A missing ")" or ";" will still lead to a blank page.
This is because the entire script is parsed before any of it is executed. If you are unable to change php.ini and set
display_errors On
then there is a possible solution suggested under error_reporting:
<?php
error_reporting(E_ALL);
ini_set("display_errors", 1);
include("file_with_errors.php");
?>
[Modified by moderator]
You should also consider setting error_reporting = -1 in your php.ini and display_errors = On if you are in development mode to see all fatal/parse errors or set error_log to your desired file to log errors instead of display_errors in production (this requires log_errors to be turned on).
ohcc at 163 dot com ¶
6 years ago
If you set the error_log directive to a relative path, it is a path relative to the document root rather than php's containing folder.
iio7 at protonmail dot com ¶
1 year ago
It's important to note that when display_errors is "on", PHP will send a HTTP 200 OK status code even when there is an error. This is not a mistake or a wrong behavior, but is because you're asking PHP to output normal HTML, i.e. the error message, to the browser.
When display_errors is set to "off", PHP will send a HTTP 500 Internal Server Error, and let the web server handle it from there. If the web server is setup to intercept FastCGI errors (in case of NGINX), it will display the 500 error page it has setup. If the web server cannot intercept FastCGI errors, or it isn't setup to do it, an empty screen will be displayed in the browser (the famous white screen of death).
If you need a custom error page but cannot intercept PHP errors on the web server you're using, you can use PHPs custom error and exception handling mechanism. If you combine that with output buffering you can prevent any output to reach the client before the error/exception occurs. Just remember that parse errors are compile time errors that cannot be handled by a custom handler, use "php -l foo.php" from the terminal to check for parse errors before putting your files on production.
Roger ¶
3 years ago
When `error_log` is set to a file path, log messages will automatically be prefixed with timestamp [DD-MMM-YYYY HH:MM:SS UTC]. This appears to be hard-coded, with no formatting options.
php dot net at sp-in dot dk ¶
8 years ago
There does not appear to be a way to set a tag / ident / program for log entries in the ini file when using error_log=syslog. When I test locally, "apache2" is used.
However, calling openlog() with an ident parameter early in your script (or using an auto_prepend_file) will make PHP use that value for all subsequent log entries. closelog() will restore the original tag.
This can be done for setting facility as well, although the original value does not seem to be restored by closelog().
jaymore at gmail dot com ¶
6 years ago
Document says
So in place of E_ALL consider using a larger value to cover all bit fields from now and well into the future, a numeric value like 2147483647 (includes all errors, not just E_ALL).
But it is better to set "-1" as the E_ALL value.
For example, in httpd.conf or .htaccess, use
php_value error_reporting -1
to report all kind of error without be worried by the PHP version.
В этом руководстве мы расскажем о различных способах того, как в PHP включить вывод ошибок. Мы также обсудим, как записывать ошибки в журнал (лог).
Как быстро показать все ошибки PHP
Самый быстрый способ отобразить все ошибки и предупреждения php — добавить эти строки в файл PHP:
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);
Что именно делают эти строки?
Функция ini_set попытается переопределить конфигурацию, найденную в вашем ini-файле PHP.
Display_errors и display_startup_errors — это только две из доступных директив. Директива display_errors определяет, будут ли ошибки отображаться для пользователя. Обычно директива dispay_errors не должна использоваться для “боевого” режима работы сайта, а должна использоваться только для разработки.
display_startup_errors — это отдельная директива, потому что display_errors не обрабатывает ошибки, которые будут встречаться во время запуска PHP. Список директив, которые могут быть переопределены функцией ini_set, находится в официальной документации .
К сожалению, эти две директивы не смогут отображать синтаксические ошибки, такие как пропущенные точки с запятой или отсутствующие фигурные скобки.
Отображение ошибок PHP через настройки в php.ini
Если ошибки в браузере по-прежнему не отображаются, то добавьте директиву:
display_errors = on
Директиву display_errors следует добавить в ini-файл PHP. Она отобразит все ошибки, включая синтаксические ошибки, которые невозможно отобразить, просто вызвав функцию ini_set в коде PHP.
Актуальный INI-файл можно найти в выводе функции phpinfo (). Он помечен как “загруженный файл конфигурации” (“loaded configuration file”).
Отображать ошибки PHP через настройки в .htaccess
Включить или выключить отображение ошибок можно и с помощью файла .htaccess, расположенного в каталоге сайта.
php_flag display_startup_errors on
php_flag display_errors on
.htaccess также имеет директивы для display_startup_errors и display_errors.
Вы можете настроить display_errors в .htaccess или в вашем файле PHP.ini. Однако многие хостинг-провайдеры не разрешают вам изменять ваш файл PHP.ini для включения display_errors.
В файле .htaccess также можно включить настраиваемый журнал ошибок, если папка журнала или файл журнала доступны для записи. Файл журнала может быть относительным путем к месту расположения .htaccess или абсолютным путем, например /var/www/html/website/public/logs
.
php_value error_log logs/all_errors.log
Включить подробные предупреждения и уведомления
Иногда предупреждения приводят к некоторым фатальным ошибкам в определенных условиях. Скрыть ошибки, но отображать только предупреждающие (warning) сообщения можно вот так:
error_reporting(E_WARNING);
Для отображения предупреждений и уведомлений укажите «E_WARNING | E_NOTICE».
Также можно указать E_ERROR, E_WARNING, E_PARSE и E_NOTICE в качестве аргументов. Чтобы сообщить обо всех ошибках, кроме уведомлений, укажите «E_ALL & ~ E_NOTICE», где E_ALL обозначает все возможные параметры функции error_reporting.
Более подробно о функции error_reporting ()
Функция сообщения об ошибках — это встроенная функция PHP, которая позволяет разработчикам контролировать, какие ошибки будут отображаться. Помните, что в PHP ini есть директива error_reporting, которая будет задана этой функцией во время выполнения.
error_reporting(0);
Для удаления всех ошибок, предупреждений, сообщений и уведомлений передайте в функцию error_reporting ноль. Можно сразу отключить сообщения отчетов в ini-файле PHP или в .htaccess:
error_reporting(E_NOTICE);
PHP позволяет использовать переменные, даже если они не объявлены. Это не стандартная практика, поскольку необъявленные переменные будут вызывать проблемы для приложения, если они используются в циклах и условиях.
Иногда это также происходит потому, что объявленная переменная имеет другое написание, чем переменная, используемая для условий или циклов. Когда E_NOTICE передается в функцию error_reporting, эти необъявленные переменные будут отображаться.
error_reporting(E_ALL & ~E_NOTICE);
Функция сообщения об ошибках позволяет вам фильтровать, какие ошибки могут отображаться. Символ «~» означает «нет», поэтому параметр ~ E_NOTICE означает не показывать уведомления. Обратите внимание на символы «&» и «|» между возможными параметрами. Символ «&» означает «верно для всех», в то время как символ «|» представляет любой из них, если он истинен. Эти два символа имеют одинаковое значение в условиях PHP OR и AND.
error_reporting(E_ALL);
error_reporting(-1);
ini_set('error_reporting', E_ALL);
Эти три строки кода делают одно и то же, они будут отображать все ошибки PHP. Error_reporting(E_ALL) наиболее широко используется разработчиками для отображения ошибок, потому что он более читабелен и понятен.
Включить ошибки php в файл с помощью функции error_log ()
У сайта на хостинге сообщения об ошибках не должны показываться конечным пользователям, но эта информация все равно должна быть записана в журнал (лог).
Простой способ использовать файлы журналов — использовать функцию error_log, которая принимает четыре параметра. Единственный обязательный параметр — это первый параметр, который содержит подробную информацию об ошибке или о том, что нужно регистрировать. Тип, назначение и заголовок являются необязательными параметрами.
error_log("There is something wrong!", 0);
Параметр type, если он не определен, будет по умолчанию равен 0, что означает, что эта информация журнала будет добавлена к любому файлу журнала, определенному на веб-сервере.
error_log("Email this error to someone!", 1, "someone@mydomain.com");
Параметр 1 отправит журнал ошибок на почтовый ящик, указанный в третьем параметре. Чтобы эта функция работала, PHP ini должен иметь правильную конфигурацию SMTP, чтобы иметь возможность отправлять электронные письма. Эти SMTP-директивы ini включают хост, тип шифрования, имя пользователя, пароль и порт. Этот вид отчетов рекомендуется использовать для самых критичных ошибок.
error_log("Write this error down to a file!", 3, "logs/my-errors.log");
Для записи сообщений в отдельный файл необходимо использовать тип 3. Третий параметр будет служить местоположением файла журнала и должен быть доступен для записи веб-сервером. Расположение файла журнала может быть относительным путем к тому, где этот код вызывается, или абсолютным путем.
Журнал ошибок PHP через конфигурацию веб-сервера
Лучший способ регистрировать ошибки — это определить их в файле конфигурации веб-сервера.
Однако в этом случае вам нужно попросить администратора сервера добавить следующие строки в конфигурацию.
Пример для Apache:
ErrorLog "/var/log/apache2/my-website-error.log"
В nginx директива называется error_log.
error_log /var/log/nginx/my-website-error.log;
Теперь вы знаете, как в PHP включить отображение ошибок. Надеемся, что эта информация была вам полезна.
Logging is an essential and underutilized practice in software development. It’s
obvious value is for debugging, but it can also be a resource for deriving
various analytics and usage information. When you learn how to log properly, you
will be able to adequately track the inner workings of your application so that
troubleshooting becomes much more effortless.
In this article, we will discuss the basics of logging in PHP and explore all
the logging-related configurations you should know. We will begin by discussing
the native logging functions in the language before branching out to examine the
logging solutions developed by other PHP users. Here are some of the other
things you stand to learn by following through with this article:
- What is logging and examples of what to log.
- Understanding PHP logging configurations.
- Using native logging functions like error_log().
- Why you should opt for a logging framework
- An introduction to the Monolog framework for logging.
Prerequisites
Ensure to have
the latest version of PHP installed
on your machine before proceeding with this article. The code snippets and
command output included in the sections below were all tested and confirmed to
be accurate as at PHP v8.x, but they should continue to work with later
versions.
🔭 Want to centralize and monitor your PHP application logs?
Head over to Logtail and start ingesting your logs in 5 minutes.
What should you log?
Before we discuss how logging works in PHP, let’s briefly examine what you
should consider logging when developing your application. Some typical
candidates for what to log include the following:
-
Errors and exceptions. Ensure to log every error and exception that occurs in
your application so that you can find the root cause of an issue and fix them
quickly. -
Incoming requests. When a request is made to an endpoint in your application,
you should log that event and include details such as a timestamp, user ID (if
any), the endpoint and HTTP method, etc. It is also a good idea to generate a
correlation ID at this point such that all other logging calls following from
the request will include this ID, making it easier to trace the path of a
specific client request in the application. -
Any changes to your database, including inserting new data and updating and
deleting existing data. You should record what data was changed, who changed
it, and when it occurred. -
Accessing sensitive information. Whenever sensitive or restricted information
is being accessed on the system, a corresponding log entry should be recorded
describing who accessed the resource and when.
Logging as much as possible does not mean you should record just anything as
irrelevant entries will create noise and make your logs much less helpful. You
should also take care never to log anything that would compromise user privacy
such as passwords, credit card information, home addresses, phone numbers, or
other Personally Identifiable Information (PII).
Understanding logging configurations in PHP
PHP saves all its configuration in a php.ini
file whose location depends on
your operating system and how you installed PHP. Luckily, there is an easy way
to locate the configuration file. Open a new terminal window and run the
following command:
Output
Configuration File (php.ini) Path: /opt/homebrew/etc/php/8.1
Loaded Configuration File: /opt/homebrew/etc/php/8.1/php.ini
Scan for additional .ini files in: /opt/homebrew/etc/php/8.1/conf.d
Additional .ini files parsed: /opt/homebrew/etc/php/8.1/conf.d/ext-opcache.ini
The highlighted line above describes where to find the relevant php.ini
file
you need to edit. Copy the path to the file and open it in your text editor:
code <path/to/your/php.ini>
This configuration file is enormous, but we only care about a small section.
Scroll down to the «Error handling and logging» section or use your text
editor’s search function.
php.ini
. . .
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Error handling and logging ;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
. . .
Let’s look at some of the common directives in this section that you need to
note. You can find a complete list of all available directives in the
official documentation. Note that
you’ll need to restart your web server after making changes to your php.ini file
for the changes to take effect.
error_reporting
: this directive configures
the level of diagnostics that should be recorded, and its value should be an
error level constant.
For example, a value ofE_ALL
(the default) indicates that all diagnostic
messages will be recorded regardless of their level, while a value of
E_ALL & ~E_NOTICE
means that all notice-level messages will be omitted.
-
display_errors
: controls whether PHP should output errors to the screen as
part of the program’s output or if they should be hidden from view. Keeping
this valueOn
is fine in development settings, but it should always be
turnedOff
in production, or end users may see ugly stack traces on your
website when an error occurs (see above screenshot). -
display_startup_errors
: determines whether PHP will output errors that occur
during its startup sequence. These errors are hidden by default, but you can
turn them on when debugging. -
log_errors
: this option configures PHP to log errors to the location
specified by theerror_log
directive. Setting this toOff
will disable
such behavior, but we recommend keeping this optionOn
. -
log_errors_max_len
: restricts the maximum length of each log record to the
specified value in bytes. The default is1024
bytes, but setting this option
to0
removes the restriction. -
error_log
: this defines the path to a file where script errors should be
logged. If this file does not exist, it will be automatically created. You can
also forward log records to the system log by setting its value tosyslog
.
Aside from configuring these options directly in the php.ini
file, PHP also
offers a way override them at runtime. This can be useful in a serverless
environment where you don’t have access to the configuration file, or when you
are troubleshooting an issue.
You can retrieve the current configuration using the ini_get()
function as
shown below:
<?php
echo 'log_errors = ' . ini_get('log_errors') . "n";
?>
If you wish to override an existing configuration, you can provide a new value
using the ini_set()
function:
<?php
ini_set('log_errors', 1); // enable error logging
ini_set('error_log', 'app-errors.log' // specify error log file path
?>
Error levels and constants in PHP
In this section, we’ll examine one of the more obtuse aspects of PHP logging:
error level constants. They are conceptually similar to log
levels and are used to distinguish the different types of
diagnostic messages produced when executing a program.
PHP has an unnecessarily complicated system when it comes to log levels. It uses
many different constants to indicate different log levels, and these constants
can be roughly classified into three families:
1. E_
for internal PHP errors
These include the following:
E_ERROR
: a fatal error that causes script termination (e.g., calling a
non-existent function, out of memory, etc.).E_WARNING
: a runtime warning that doesn’t terminate script execution (e.g.,
using an undefined variable in an expression).E_PARSE
: compile-time parse errors, usually syntax errors.E_NOTICE
: runtime notices, meaning PHP encountered something that it thinks
could be a mistake, but could also be intentional. For instance, using
unassigned values in your code.
The constants above are used to indicate the severity of any event in your
application, and they are not user-customizable. When something happens, PHP
will automatically create a log record and decide if it is E_ERROR
,
E_WARNING
, or E_NOTICE
. The only thing we can do with these constants is to
use them in the error_reporting
directive to tell PHP whether or not to log
these errors.
2. E_USER
for application-specific logs
E_USER_ERROR
: something went seriously wrong with your project, causing
services to stop working.E_USER_WARNING
: something abnormal happened, but it doesn’t affect the core
functionalities of your applications, though the situation may need to be
addressed soon to prevent it from escalating further.E_USER_NOTICE
: informative messages that describe the normal operation of
the program.
3. LOG_
for system logs
The LOG_
family conforms to the standard
syslog severity levels:
LOG_EMERG
: the entire application is unusable.LOG_ALERT
: something serious happened that needs to be addressed
immediately.LOG_CRIT
— a critical function is no longer working.LOG_ERR
— an error occurred, but the application can continue working.LOG_WARNING
: abnormal situations that may later become an error if not
addressed.LOG_NOTICE
: unusual events but not error conditions.LOG_INFO
— informative messages.LOG_DEBUG
: used to indicate messages helpful for debugging.
Exploring logging functions in PHP
Now that we’ve examined the PHP logging configuration and its error constants,
let’s get into the nitty-gritty of logging in a PHP project. Several logging
functions ship with PHP, and they all depend on the configurations discussed in
the earlier sections.
To guarantee that you get results consistent with what is described in the
sections below, ensure that your logging configuration matches the following
values:
php.ini
. . .
error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT
display_errors = On
log_errors = On
error_log = error.log
. . .
Go to your working directory and create a new logging.php
file using the
command below. This is where we are going to explore PHP’s logging functions
throughout this tutorial.
The most basic form of logging involves sending messages to the console. In PHP,
we can easily print to the console using echo
or print
statements like this:
logging.php
<?php
echo "This is a log message.n";
print "This is also a log message.";
?>
Output
This is a log message.
This is also a log message.
While echo
and print
statements are valuable ways to print some text to the
console, you shouldn’t use them for logging as there are much better facilities
for doing so. We will explore some of these functions in detail here.
The error_log() function
PHP’s error_log()
function pushes a log message to the file path defined in
error_log
config option. You can also specify a different file path directly
in the function, if you prefer. It can take up to four arguments but only the
first one is required:
error_log(
string $message,
int $message_type = 0,
?string $destination = null,
?string $additional_headers = null
): bool
- The
$message
argument is the log message you wish to record. - The
$message_type
argument has a confusing name but it specifies where you
want PHP to push the message. It has four possible values:0
: the message is sent to the location specified in theerror_log
directive.1
: the message is pushed through email, which is specified by the
$destination
parameter.3
: the message is appended to the file specified by the$destination
parameter.4
: the message is sent directly to the Server API (SAPI) logging handler,
which depends on your platform. For example,
Apache’s error log
will be used for LAMP (Linux Apache, MySQL, PHP) setups.
- The
$destination
parameter specifies where the log message should be sent,
and it could be an email address or a local file, depending on the value of
$message_type
. - The
$additional_headers
parameter is only used when$message_type
is set
to1
. It is the same as the$additional_headers
used in PHP’s
mail()
function.
Let’s go ahead and use the error_log()
function to create a log record like
this:
logging.php
<?php
error_log("database not available!");
?>
Once you execute this script, you will notice an error.log
file in the current
directory:
Examine the contents of the error.log
file through the cat
command as shown
below:
Output
[27-Jul-2022 16:05:49 America/New_York] database not available!
As you can see, the error_log()
function automatically includes a timestamp
which is one reason why using a dedicated logging function is better than echo
and print
statements.
You can also record a log entry into a different file by changing the
$message_type
and $destination
parameters as shown below:
logging.php
. . .
error_log("database not available!", 3, "my-errors.log");
Save the changes and execute the logging.php
file again.
This time, the log entry will be sent to the my-errors.log
file:
Notice that a timestamp is not included in the above entry! This is because the
method bypasses the operating system’s logging mechanism leading to less
detailed logs. A better way to log to a different file is by using the
ini_set()
function discussed earlier:
logging.php
<?php
. . .
ini_set("error_log", "my-errors.log");
error_log("database not available!");
?>
This example will produce the same result, but with the timestamp included:
my-errors.log
[27-Jul-2022 17:38:04 America/New_York] database not available!
The trigger_error() function
The trigger_error()
function is used to record application-specific errors,
warnings and notices. It takes two parameters: the first one is the log message,
and the second one defines its error level (one of E_USER_ERROR
,
E_USER_WARNING
, E_USER_NOTICE
, or E_USER_DEPRECATED
):
logging.php
<?php
trigger_error("A user requested a resource.", E_USER_NOTICE);
trigger_error("The image failed to load!", E_USER_WARNING);
trigger_error("User requested a profile that doesn't exist!", E_USER_ERROR);
?>
When you execute the script above, you will observe the following console
output:
Output
Notice: A user requested a resource. in /home/eric/test/logging.php on line 2
Warning: The image failed to load! in /home/eric/test/logging.php on line 3
Fatal error: User requested a profile that doesn't exist! in /home/eric/test/logging.php on line 4
The above logs are also recorded to the error.log
file in a slightly different
format:
Output
[8-Jul-2022 22:11:43 America/New_York] PHP Notice: A user requested a service. in /home/eric/test/logging.php on line 3
[8-Jul-2022 22:11:43 America/New_York] PHP Warning: The image failed to load! in /home/eric/test/logging.php on line 4
[8-Jul-2022 22:11:43 America/New_York] PHP Fatal error: User requested a profile that doesn't exist! in /home/eric/test/logging.php on line 5
Each log entry specifies the corresponding log level and the location of the log
message. If you don’t use a user-assigned error level constant (prefixed with
E_USER_
), an error will be thrown.
<?php
trigger_error("A user requested a service.", E_ERROR);
?>
Output
Fatal error: Uncaught ValueError: trigger_error(): Argument #2 ($error_level) must be one of E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE, or E_USER_DEPRECATED in /home/ayo/dev/betterstack/betterstack-community/demo/logging-php/logging.php:2
Stack trace:
#0 /home/ayo/dev/betterstack/betterstack-community/demo/logging-php/logging.php(2): trigger_error()
#1 {main}
thrown in /home/ayo/dev/betterstack/betterstack-community/demo/logging-php/logging.php on line 2
Logging to the system log
A third way to log messages in PHP is using the syslog()
function. It sends
the log message to the default system log like this:
syslog(LOG_ERR, "Custom error message");
The first argument to syslog()
is the appropriate log level constant, and the
second is the log message to be recorded. Notice that when specifying the log
level, the third group of constants (those prefixed with LOG_
) are utilized.
These constants are unique to the syslog()
function, and they are all listed
in its documentation.
Here are a few ways to view your system log:
- On Linux, use one of the following commands to access the system log
(depending on the specific OS):
tail -f /var/log/messages
- On macOS, run
tail -f /var/log/system.log
in your terminal. - On Windows, use the
Windows Event Viewer.
Here’s some sample output from the system log on a Linux-based OS after
executing the previous code snippet:
Output
Jul 27 20:58:28 fedora php[485047]: Custom error message
You can customize the output above through the openlog()
function. It opens a
connection to the system logger and takes up to three arguments: a string prefix
to be added to each message, the logging options, and the logging facility.
After calling openlog()
, you should call closelog()
to close the connection.
openlog("MyAppPrefix", LOG_PID | LOG_PERROR,LOG_USER);
syslog(LOG_ERR, "Custom error message");
closelog();
Here’s the output after executing the script above:
Output
Jul 28 09:20:04 fedora MyAppPrefix[596277]: Custom error message
You can learn more about system logs on
Linux by reading our
detailed tutorial on the subject.
Why you should use a logging framework
Using PHP’s built-in logging functions is an easy way to get started with
logging in simple projects, but they are insufficient for creating a robust
logging strategy in serious applications due to their lack of features and
flexibility, such as customizing the formatting of your logs, or determining how
they are recorded. They also cannot capture a wide variety of data types since
everything fed into them must be a string, which means you have to do extra work
to capture contextual data in a log entry.
These limitations are why third-party logging frameworks
are prevalent in the PHP ecosystem. Here are some of the most popular logging
libraries for PHP that are worth exploring for production-grade applications:
- Monolog: Monolog is the most popular PHP
logging framework out there. It has dozens of handlers that can send your log
records to files, emails, databases, Slack, etc. It is also packed with
multiple formatters that allow you to customize your logs however you want. - Analog: Analog is a minimal logging
library. It also has several handlers that can send your logs to different
destinations. However, it does not have optional features such as formatters
and processors. - KLogger: Unlike Analog, KLogger goes in
a different direction. It can only push your logs to a file, but it has many
different formatters that you can use to customize the timestamp, file name,
file extension, context information, etc.
In the next section, we will briefly examine how to implement logging using the
Monolog library as it’s the most popular and satisfactorily meets all our
criteria for a good logging framework.
Getting started with Monolog
To use Monolog in your PHP application, you need to install the library through
PHP Composer:
composer require monolog/monolog
Output
. . .
Package operations: 2 installs, 0 updates, 0 removals
- Installing psr/log (3.0.0): Extracting archive
- Installing monolog/monolog (3.1.0): Extracting archive
11 package suggestions were added by new dependencies, use `composer suggest` to see details.
Generating autoload files
1 package you are using is looking for funding.
Use the `composer fund` command to find out more!
This command will install Monolog into the vendor
directory, and you can
import the package into your project like this:
logging.php
<?php
require __DIR__."/vendor/autoload.php"; // This tells PHP where to find the autoload file so that PHP can load the installed packages
use MonologLogger; // The Logger instance
use MonologHandlerStreamHandler; // The StreamHandler sends log messages to a file on your disk
use MonologLevel; // Log levels
?>
The three classes we imported into the file above represent Monolog’s most
important concepts. First, logging in Monolog is channel-based, and the Logger
instance is used to initialize a new log channel which provides a mechanism for
grouping different logs. For example, you can have an errors
channel that
records errors, a performance
channel that logs performance-related messages,
and so on. You can organize this system however you like depending on what kind
of application you are building.
Each log channel can be assigned multiple handlers, and they are responsible for
sending log messages to various destinations. For example, the StreamHandler
above can push your messages to the console or a local file.
Finally, each handler needs to have a minimum log level, which defines the
minimum level a message must have to be logged by the handler. Monolog provides
a more standard way of dealing with log levels than PHP’s error level constants.
There are eight different levels available in Monolog, and they are modeled
after the
Syslog severity levels
discussed earlier:
- EMERGENCY
- ALERT
- CRITICAL
- ERROR
- WARNING
- NOTICE
- INFO
- DEBUG
Logging in PHP with Monolog
Let’s look at an example of how to log messages to the console with Monolog:
logging.php
<?php
. . .
// New Logger instance. Create a new channel called "my_logger".
$logger = new Logger("my_logger");
// Create a new handler. In this case, it is the StreamHandler, which will send the log messages to the console.
$stream_handler = new StreamHandler("php://stdout", Level::Debug);
// Push the handler to the log channel
$logger->pushHandler($stream_handler);
// Log the message
$logger->debug("This is a debug message.");
$logger->info("This is an info message.");
$logger->error("This is an error message.");
$logger->critical("This is a critical message.");
?>
Execute the logging.php
file, and observe the following output:
Output
[2022-07-11T03:32:57.111007+02:00] my_logger.DEBUG: This is a debug message. [] []
[2022-07-11T03:32:57.111750+02:00] my_logger.INFO: This is an info message. [] []
[2022-07-11T03:32:57.111941+02:00] my_logger.ERROR: This is an error message. [] []
[2022-07-11T03:32:57.112127+02:00] my_logger.CRITICAL: This is a critical message. [] []
In this example, a new log channel called my_logger
was initialized using the
Logger
instance, and then a StreamHandler()
instance was assigned to it.
This handler was setup to log debug-level messages or higher to the standard
output (represented by php://stdout
).
Lastly, several log messages are recorded by using the debug()
, info()
,
error()
, and critical()
methods which give the message the corresponding log
level that is observed in the output. Notice that a timestamp is also included
with each entry.
Instead of logging to the terminal console, we can also push the log record to a
local file using the StreamHandler()
. All we need to do is change the
destination parameter like this:
logging.php
<?php
. . .
$logger = new Logger("my_logger");
$stream_handler = new StreamHandler(__DIR__ . "/log/debug.log", Level::Debug);
$logger->pushHandler($stream_handler);
$logger->debug("This is a debug message.");
?>
This causes log messages using the $logger
channel to be sent to a
/log/debug.log
file. You can examine its contents with the following command:
Output
[2022-07-10T01:53:24.848775+02:00] my_logger.DEBUG: This is a debug message. [] []
There are many other handlers other than the StreamHandler
demonstrated above,
so ensure to read our detailed guide on
Monolog to learn more about them and how to
create a custom handler.
Formatting your logs
From the examples above, you will observe that all the log records follow a
predefined format. They all start with a timestamp, followed by the log level,
message, context and extra information. This format might not fit your needs
when creating a logging system, so Monolog provides several formatters that you
can use to customize the log records.
One of the useful formatters to look at is the LineFormatter
. It takes a log
record as input, and subsequently outputs a formatted string of the record.
Let’s take a look at an example:
logging.php
. . .
use MonologLevel;
use MonologLogger;
use MonologHandlerStreamHandler;
use MonologFormatterLineFormatter;
$logger = new Logger("my_logger");
$stream_handler = new StreamHandler("php://stdout", Level::Debug);
$output = "%level_name% | %datetime% > %message% | %context% %extra%n";
$stream_handler->setFormatter(new LineFormatter($output));
$logger->pushHandler($stream_handler);
$logger->debug("This file has been executed.");
?>
In this case, we are making Monolog return a log record that starts with the log
level, then the date, message, and context information.
Output
DEBUG | 2022-07-10T21:33:51.345896+02:00 > This file has been executed. | [] []
Besides rearranging the different segments, it is also possible for us to
customize the timestamp output, since the default format isn’t very human
readable.
logging.php
<?php
. . .
$dateFormat = "Y-n-j, g:i a";
$output = "%level_name% | %datetime% > %message% | %context% %extra%n";
$stream_handler->setFormatter(new LineFormatter($output, $dateFormat));
. . .
?>
Output
DEBUG | 2022-7-10, 10:24 pm > This file has been executed. | [] []
In a production environment, your application will probably generate tons of
logs, and in this case, it is best to use a structured logging
format
that is better suited to parsing by automated logging tools. Using Monolog’s
JsonFormatter
, you are able to log in JSON format, making it easier for
machines to read.
logging.php
<?php
require __DIR__ . "/vendor/autoload.php";
use MonologLevel;
use MonologLogger;
use MonologHandlerStreamHandler;
use MonologFormatterJsonFormatter;
$logger = new Logger("daily");
$stream_handler = new StreamHandler("php://stdout", Level::Debug);
$logger->pushHandler($stream_handler);
$stream_handler->setFormatter(new JsonFormatter());
$logger->debug("This is a debug message.");
Output
{"message":"This is a debug message.","context":{},"level":100,"level_name":"DEBUG","channel":"daily","datetime":"2022-07-29T21:43:30.910327+02:00","extra":{}}
Notice that the log message, the log level, the timestamp, and so on have all
been turned into JSON data.
You can learn more about formatters in Monolog and their available options by
reading their
documentation.
Final thoughts
We covered a lot of ground in this article, beginning with PHP’s native logging
functions and their quirks and features before briefly discussing logging
frameworks and why you need one. We also introduced Monolog, a logging library
for PHP application and demonstrated some of its basic features that help you
create a more useful logging system. There’s a lot more about Monolog that can’t
be covered here so we recommend diving into our detailed guide to logging with
Monolog to get a full picture of what you
can do with it.
Thanks for reading, and happy logging!
Centralize all your logs into one place.
Analyze, correlate and filter logs with SQL.
Create actionable
dashboards.
Share and comment with built-in collaboration.
Got an article suggestion?
Let us know
Next article
How to Get Started with Monolog Logging in PHP
Monolog is among the most popular pieces of open source software, providing logging capabilities for PHP applications.
→
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
PHP предлагает гибкие настройки вывода ошибок, среди которых функия error_reporting($level)
– задает, какие ошибки PHP попадут в отчет, могут быть значения:
E_ALL
– все ошибки,E_ERROR
– критические ошибки,E_WARNING
– предупреждения,E_PARSE
– ошибки синтаксиса,E_NOTICE
– замечания,E_CORE_ERROR
– ошибки обработчика,E_CORE_WARNING
– предупреждения обработчика,E_COMPILE_ERROR
– ошибки компилятора,E_COMPILE_WARNING
– предупреждения компилятора,E_USER_ERROR
– ошибки пользователей,E_USER_WARNING
– предупреждения пользователей,E_USER_NOTICE
– уведомления пользователей.
1
Вывод ошибок в браузере
error_reporting(E_ALL);
ini_set('display_errors', 'On');
PHP
В htaccess
php_value error_reporting "E_ALL"
php_flag display_errors On
htaccess
На рабочем проекте вывод ошибок лучше сделать только у авторизированного пользователя или в крайнем случаи по IP.
2
Запись ошибок в лог файл
error_reporting(E_ALL);
ini_set('display_errors', 'Off');
ini_set('log_errors', 'On');
ini_set('error_log', $_SERVER['DOCUMENT_ROOT'] . '/logs/php-errors.log');
PHP
Файлы логов также не должны быть доступны из браузера, храните их в закрытой директории с файлом .htaccess:
Order Allow,Deny
Deny from all
htaccess
Или запретить доступ к файлам по расширению .log (заодно и другие системные файлы и исходники):
<FilesMatch ".(htaccess|htpasswd|bak|ini|log|sh|inc|config|psd|fla|ai)$">
Order Allow,Deny
Deny from all
</FilesMatch>
htaccess
3
Отправка ошибок на e-mail
Ошибки можно отправлять на е-mail разработчика, но приведенные методы не работает при критических ошибках.
Первый – register_shutdown_function()
регистрирует функцию, которая выполнится при завершении работы скрипта, error_get_last()
получает последнюю ошибку.
register_shutdown_function('error_alert');
function error_alert()
{
$error = error_get_last();
if (!empty($error)) {
mail('mail@example.com', 'Ошибка на сайте example.com', print_r($error, true));
}
}
PHP
Стоит учесть что оператор управления ошибками (знак @) работать в данном случаи не будет и письмо будет отправляться при каждой ошибке.
Второй метод использует «пользовательский обработчик ошибок», поэтому в браузер ошибки выводится не будут.
function error_alert($type, $message, $file, $line, $vars)
{
$error = array(
'type' => $type,
'message' => $message,
'file' => $file,
'line' => $line
);
error_log(print_r($error, true), 1, 'mail@example.com', 'From: mail@example.com');
}
set_error_handler('error_alert');
PHP
4
Пользовательские ошибки
PHP позволяет разработчику самому объявлять ошибки, которые выведутся в браузере или в логе. Для создания ошибки используется функция trigger_error()
:
trigger_error('Пользовательская ошибка', E_USER_ERROR);
PHP
Результат:
Fatal error: Пользовательская ошибка in /public_html/script.php on line 2
E_USER_ERROR
– критическая ошибка,E_USER_WARNING
– не критическая,E_USER_NOTICE
– сообщения которые не являются ошибками,E_USER_DEPRECATED
– сообщения о устаревшем коде.
10.10.2019, обновлено 09.10.2021
Другие публикации
Список основных кодов состояния HTTP, без WebDAV.
Изображения нужно сжимать для ускорения скорости загрузки сайта, но как это сделать? На многих хостингах нет…
JSON (JavaScript Object Notation) – текстовый формат обмена данными, основанный на JavaScript, который представляет собой набор пар {ключ: значение}. Значение может быть массивом, числом, строкой и…
phpQuery – это удобный HTML парсер взявший за основу селекторы, фильтры и методы jQuery, которые позволяют…
AJAX позволяет отправить и получить данные без перезагрузки страницы. Например, делать проверку форм, подгружать контент и т.д. А функции JQuery значительно упрощают работу.
После регистрации в системе эквайринга Сбербанка и получив доступ к тестовой среде, можно приступить к интеграции с…
Home / Log PHP errors with log_errors and error_log
PHP errors are by default logged to the web server’s error log file (at least they are with the default setup on most Linux distros) but it is also possible to instead log PHP errors to a file of your choice. This is useful on production websites so you can periodically check for errors and fix them in a location other than the default webserver error log file.
The log_errors configuration option is a boolean option. To log to an error log file specified with the error_log configuration option set this to 1.
error_log
The error_log configuration option is a string and is the filename of where to log errors. It can contain either a relative path or an absolute path as part of the filename. If «syslog» is used it is logged to to the system logger (syslog on *nix and the Event Log on Windows).
Set error logging with ini_set()
Although this is not ideal you can use the ini_set() function to set the above configuration options to log errors. It is not an ideal solution because it will not log any errors if the script has parse errors and cannot be run at all. For example:
ini_set("log_errors", 1); ini_set("error_log", "/path/to/php-error.log");
Set error logging in .htaccess and virtualhost directives
This is a better option because it will log the errors even if there’s a parsing error in your script.
php_value log_errors 1 php_value error_log /path/to/php-error.log
Example error log data
A couple of example lines from an error log are as follows:
[13-May-2009 21:54:04] PHP Notice: Undefined variable: x in /common/websites/test/error-log.php on line 6 [13-May-2009 21:54:09] PHP Parse error: syntax error, unexpected '}' in /common/websites/test/error-log.php on line 5
Error log must be writable by the web server
The error log will be written to as the user the web server runs as so it must be writeable by that user. In most cases you’ll probably need to make it world-writeable to be able to do this. On a *nix server this is 0666 file permissions.
Conclusion
It’s easy to set up a PHP error log using the log_errors and error_log configuration options. This can be set up on a website by website basis and you could potential combine it with a daily process to email errors to the webmaster (if there are any) on a daily basis. I’ll cover doing this in a later post.