Technical Resources
Educational Resources
APM Integrated Experience
Connect with Us
This guide explores the basics of logging in PHP, including how to configure logging, where logs are located, and how logging can help you be more effective when troubleshooting and monitoring your PHP applications.
It’s always good to have a handle on the basics, so this article covers the error log built into PHP. If you’re setting up a new application or want to improve an existing one, we recommend you take a look at PHP Logging Libraries if you’re working on a custom stack or PHP Framework Logging if you’re using a framework like Laravel or Symfony.
With the built-in error log, there are a few different elements you’ll want to keep in mind:
Let’s start by reviewing how the PHP engine can be configured to display and log error output. These settings are useful to review if you’re setting up a new server or trying to figure out if logging is configured on a server someone else has set up.
By default, the configuration pertaining to errors is found in the following directives within the configuration file php.ini. There may be several different php.ini files on your system depending on whether you’re running PHP on the command-line interface (CLI) or behind a web server such as Apache or NGINX. Here’s where you can find your php.ini file in common distributions of Linux.
You can find a full list of directives on the PHP documentation site. Here are some of the more common directives relevant to logging.
Notes:
*Change to 0 for web-facing servers as a security measure.
**If set to syslog, it will send errors to the system log.
PHP provides several functions for reading and modifying run-time configuration directives. These can be used in an application to override settings in php.ini. The ability to modify configuration values is useful when you don’t have access to the PHP configuration files (such as in a serverless environment), when troubleshooting an application, or when running certain tasks (such as a cron job requiring extra memory). You may need to look for calls to ini_set() in your code if the application isn’t behaving as expected. For example, if you set display_errors to 1 in php.ini but still don’t see the error output, chances are it’s being overridden somewhere.
The two most common are as follows:
ini_get(string <directive name>): Retrieves current directive settingini_set(string <directive name>, mixed <setting>): Sets a directiveWhen log_errors is enabled but error_log hasn’t been defined, errors are logged to the web server error log. The default locations for Apache and NGINX are as follows:
/var/log/apache2/error.log /var/log/nginx/error.logHere are functions used to facilitate application error logging. Understanding how logging works natively in PHP has value, but you should also look into using popular PHP logging libraries because of the functionality they add.
This function sends a message to the currently configured error log. The most common usage is as follows:
error_log('Your message here');
On an Apache server, this will add a new line to /var/log/apache2/error.log.
[16-Jul-2019 17:36:01 America/New_York] Your message here
You can read more about logging in Apache in this guide.
You can also send a message to a different file. However, this isn’t recommended, as it can lead to confusion.
error_log('Invalid input on user login', 3, '/var/www/example.com/log/error.log');
You can use the E_USER_* error levels in your application to report errors with varying severity for logging. Like the core constants, there are levels for fatal errors (E_USER_ERROR), warnings (E_USER_WARNING), and notices (E_USER_NOTICE). In your code, use the trigger_error() function for custom errors. If your code encounters an error, use trigger_error() with a descriptive message to let your error handler know something went wrong instead of using the die() function to abruptly terminate everything.
This function takes two parameters—an error message string and an error level.
function foo($email) {
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
trigger_error(
'Supplied value is not a valid email',
E_USER_WARNING);
return;
}
// rest of function continues
}
Another way of logging errors is to send them directly to the system using the syslog() function. It takes the error level as the first parameter (LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG); the second parameter is the actual error message.
openlog('CrawlerApp', LOG_CONS | LOG_NDELAY | LOG_PID, LOG_USER | LOG_PERROR);
syslog(LOG_WARNING, "User #14 is logged from two different places.");
closelog();
The above will log a new message to /var/log/syslog:
Aug 3 10:45:15 vaprobash php: User #14 is logged from two different locations.
When logging data, you have to make sure you follow a meaningful formatting convention, including fields such as date/time, filename, and message. This allows you to better analyze and search your data. You can also make it a separate function to handle log formatting. The same technique is used by the Monolog package.
function logger($message, array $data, $logFile = "error.log"){
foreach ($data as $key => $val) {
$message = str_replace("%{$key}%", $val, $message);
}
$message .= PHP_EOL;
return file_put_contents($logFile, $message, FILE_APPEND);
}
logger("%file% %level% %message%", ["level" => "warning", "message" =>"This is a message", "file" =>__FILE__]);
// error.log
/var/www/html/test.php warning This is a message
You can check our Apache logging guide for more details about configuring your web server logging format.
PHP provides a variety of error log types for identifying the severity of errors encountered when your application runs. The error levels indicate if the engine couldn’t parse and compile your PHP statements, if it couldn’t access or use a resource needed by your application, and even if you had a possible typo in a variable name.
Although the error levels are integer values, there are predefined constants—such as E_ERROR and E_PARSE—for each one. Using the constants can make your code easier to read and understand and keep it forward-compatible when new error levels are introduced.
Error-level constants are used by the error_reporting() function to indicate which types of errors should be displayed or logged. Note this can also be configured in the INI file. You can also use bitwise operators to customize the verbosity of your application logs.
// report all errors except notices and strict errors
error_reporting(E_ALL & ~E_NOTICE & ~E_STRICT);
You’ve probably encountered code that prefixes a function call with the @ symbol, which is the error control operator. This suppresses any errors emitted by the function. In the end, this means if the function fails, you won’t see any errors related to it on screen or in your logs. This is a poor practice and should be avoided. Remember, you can always set a custom error handler to catch errors.
// Please don't do this.
$fh = @fopen('example.csv', 'r');
If you’re trying to fix a bug but don’t see any errors, search your code for function calls prefixed with one @. You can also install and enable the scream extension, which disables this behavior and ensures all errors are reported.
The best practice is to set the error level to E_ALL unless a specific use case is required. Notices and warnings can indicate variables aren’t being created in the way you intended.
Log messages can be generated manually by calling error_log() or automatically when notices, warnings, or errors come up during execution. By default, the error log in PHP is disabled.
You can enable the error log in one of two ways: by editing php.ini or by using ini_set. Modifying php.ini is the proper way to do this. Be sure to restart your web server after editing the configuration.
Via php.ini:
log_errors = 1
Via ini_set():
ini_set('log_errors', 1);
This run-time setting is necessary only if the log_errors directive isn’t enabled as a general configuration for a particular reason and your application code requires it.
As a best practice, you can enable error reporting and logging on web-facing servers and disable displaying errors in response. Displaying errors in response in a live environment can be a serious security mistake and must be avoided. The display_errors directive is mentioned in the following configuration due to this security concern.
Logging user actions and activities provides a valuable source of information for seeing which features get used, for knowing the steps users take to accomplish tasks, and for tracking down and recreating errors they encounter. Though you can log this activity to a local file, you’ll typically want to log this to an existing logging service to make it easier to analyze and report. Instead of inventing your own format—which would require a custom parser—use JSON as your logging format. JSON is a structured format designed to make it easy for logging services and other applications to parse events. For more on getting the most out of JSON logging, see Eight Handy Tips to Consider When Logging in JSON.
As a best practice, use JSON to log user behavior and application errors. You can do this from the beginning, so you don’t have to convert or lose older logs.
PHP arrays and objects can be converted to a JSON string using json_encode(). Likewise, JSON can be reconstituted as a native PHP construct by using json_decode().
This is an example of how to use the json_encode() function with an associative array:
$logdata = [
'msg' => 'Invalid username',
'code' => '601',
'url' => $_SERVER['REQUEST_URI'],
'username' => 'ae2ivz!',
];
$json = json_encode($logdata);
// Produces:
// {"msg":"Invalid username","code":"601","url":"https://example.com/foo","username":"ae2ivz!"}
This is an example of how to use the json_decode() function:
$jsonLogData = '{
"msg": "Invalid username",
"code": "601",
"url": "https://example.com/foo",
"username": "ae2ivz!"
}';
$logdata = json_decode($jsonLogData); // Convert to stdClass object.
$logdata = json_decode($jsonLogData, true); // Convert to associative array.
Exceptions are an elegant way to handle application errors and subsequent logging. They’re either thrown and caught within a try/catch/finally block or handled by a custom exception function.
Exceptions are used when parts of your application logic can’t continue the normal flow of execution.
PHP has a base Exception class available by default in the language. The base exception class is extensible if required.
The following example assumes directive log_errors = 1.
try{
if(true){
throw new Exception("Something failed", 900);
}
} catch (Exception $e) {
$datetime = new DateTime();
$datetime->setTimezone(new DateTimeZone('UTC'));
$logEntry = $datetime->format('Y/m/d H:i:s') . ' ' . $e;
// log to default error_log destination
error_log($logEntry);
//Email or notice someone
}
The example above would produce the following error log entry:
2015/07/30 17:20:02/Something failed/900//var/www/html/index.php/4
Let’s say you have a certain frequency of a specific type of error and would like to tailor a custom exception to handle it. In the following example, we’ll create a custom exception called TooManyLoginAttemptsException to handle incidences of too many login attempts.
Define the custom exception class:
class TooManyLoginAttemptsException extends Exception {
public function __construct($msg, $code) {
parent::__construct($msg, $code);
}
}
Define a class to throw the custom exception:
class User {
public function login(array $credentials) {
if ($this->attempts($credentials) >= 10) {
throw new TooManyLoginAttemptsException("Too many logging attempts from user {$credentials['email']} at {time()}");
}
// attempt login
}
}
Catch the user login attempt with the custom exception:
try {
User::login($credentials);
} catch (TooManyLoginAttemptsException $ex) {
// You can add details to your logs here.
error_log("Too many login attempts from user {$credentials['email']} at {".time()."}");
}
If we were to run a completed program, it would display an output similar to this:
[Tue Jul 16 10:41:35 2019] Too many login attempts from user user@example.com at {1563288095}
The PHP has a built-in code library called Standard PHP Library (SPL). The library has a number of exception classes defined and available for common code-level errors. These exceptions extend from the base PHP exception class internally. They’re different in name only and can be thrown, caught, and logged.
First, we can define a class to throw an SPL exception (BadMethodCallException). The example uses the PHP magic method __call() to catch an undefined method call.
class Adapter{
public function __call($method, $options){
if (!method_exists($this, $method)) {
throw new BadMethodCallException("Unknown method '{$method}'");
}
//code...
}
}
Attempt to use an undefined method:
try {
$adapter = new Adapter();
$adapter->getConfig();
} catch (BadMethodCallException $e) {
// Log the error.
error_log($e->getMessage());
}
PHP 7 and 8 offer a Throwable interface (implemented by the Exception and Error classes) designed to catch internal PHP exceptions like TypeError and ParseError. In earlier versions, fatal errors couldn’t be handled gracefully because they immediately terminated program execution. You can find the full predefined exception documentation here.
The Throwable interface can’t be implemented by custom exceptions directly and must extend from the base exception class for implementation.
try {
// Your code here
} catch(Throwable $ex) {
// You can catch any user or internal PHP exceptions
}
Last updated: 2022