NEWJoin our webinar on Sep 13th on Continuous Delivery: a pragmatic approach to mitigating risks Register now →
So when we encounter errors in our code, where exactly can we find them? At a high level, there are really only three places where PHP errors can be found: inline with program execution, in the system log, or in error monitoring tools like Rollbar.
By default, whenever an error or exception is thrown, PHP sends the error message directly to the user via STDOUT. In a command-line environment, this means that errors are rendered in the terminal. In a web environment, errors and exceptions get displayed directly in the browser.
While this behavior is useful for debugging problems in a development environment, it should be disabled in a production environment for security reasons. To do this, open up the PHP configuration file for the environment you are working in—typically found in a path that looks like /etc/php/:environment:/php.ini—and change the display_errors directive to Off.
; This directive controls whether or not and where PHP will output errors, ; notices and warnings too. Error output is very useful during development, but ; it could be very dangerous in production environments. Depending on the code ; which is triggering the error, sensitive information could potentially leak ; out of your application such as database usernames and passwords or worse. ; For production environments, we recommend logging errors rather than ; sending them to STDOUT. ; Possible Values: ; Off = Do not display any errors ; stderr = Display errors to STDERR (affects only CGI/CLI binaries!) ; On or stdout = Display errors to STDOUT ; Default Value: On ; Development Value: On ; Production Value: Off ; http://php.net/display-errors display_errors = On
While rendering errors to STDOUT is great for debugging issues in a development environment as they happen, it isn't very useful in a production environment. This is where the error log comes into play. By default, PHP doesn't log any errors, which means that this value must be explicitly set. To do so, open up the same PHP configuration file referenced above in your favorite editor and find the error_log directive.
; Log errors to specified file. PHP's default behavior is to leave this value ; empty. ; http://php.net/error-log ; Example: ;error_log = php_errors.log ; Log errors to syslog (Event Log on Windows). error_log = syslog
There are two possible values for error_log: a custom log file and the syslog. If the syslog is used, then all PHP errors will be sent directly to the default system log file—in Linux, this is typically /var/log/syslog. The more manageable method is to use a custom log file. By doing this, you can isolate your PHP application's logs from the rest of the system logs, which can make debugging issues significantly easier.
While PHP's default system logger is useful for bespoke applications, it is important to note that many application frameworks provide their own built-in logging mechanisms. A great example of this is the Laravel framework. In Laravel, the logging method can be changed within the log option of the application configuration file—found in config/app.php.
/* |-------------------------------------------------------------------------- | Logging Configuration |-------------------------------------------------------------------------- | | Here you may configure the log settings for your application. Out of | the box, Laravel uses the Monolog PHP logging library. This gives | you a variety of powerful log handlers / formatters to utilize. | | Available Settings: "single", "daily", "syslog", "errorlog" | */ 'log' => env('APP_LOG', 'single'),
By default, Laravel maintains a single log file at storage/logs/laravel.log within the project directory, rather than the defined error_log option from the global PHP configuration.
Because Laravel is built on top of Symfony, they share the same core logging mechanism—although the configuration differs between the two frameworks. Logging in Symfony and Laravel are both done using Monolog, a third-party PHP logging library that can be used to create and store logs in a large number of ways.
By default, Symfony logs are stored in var/log/dev.log and var/log/prod.log within the project directory, depending on the environment, but these defaults can be changed in the Monolog package configuration file found at config/packages/monolog.php.
$container->loadFromExtension('monolog', array( 'handlers' => array( 'file_log' => array( 'type' => 'stream', 'path' => '%kernel.logs_dir%/%kernel.environment%.log', 'level' => 'debug', ), 'syslog_handler' => array( 'type' => 'syslog', 'level' => 'error', ), ), ));
So, what exactly do PHP logs look like? In most instances, PHP logs follow a fairly predictable format:
Dec 10 04:04:38 scotchbox apache2: PHP Parse error: syntax error, unexpected end of file in /var/www/public/index2.php on line 4
In a nutshell, the log line above can be broken up into four parts: the date, the hostname, the process, and the error message. Whenever an error is encountered or an uncaught exception is thrown, the error message is printed along with the date, hostname, and process metadata to help pinpoint what happened, where it happened, and when it happened.
It is important to note that, in PHP, there are a handful of log levels that can be squashed or raised. While these log levels are determined by PHP itself, understanding what they are and mean is a crucial step towards being able to diagnose problems as they happen.
When displayerrors is set to On, it can be useful to explicitly hide and show specific log levels so you can focus on one task at a time, such as critical errors, or cleaning up warnings. This can be accomplished using the built-in errorreporting method.
// Report simple running errors error_reporting(E_ERROR | E_WARNING | E_PARSE); // Report all errors except E_NOTICE error_reporting(E_ALL & ~E_NOTICE);
This method accepts an integer value that tells PHP which errors to display, and which ones to ignore. Through the use of bitwise operators (| meaning OR, & meaning AND, and ~ meaning NOT), we can clearly and easily define which errors we want to see.
Here are a few of the most common log levels. For more information about log levels (there are quite a few of them), take a look at PHP's official documentation.
Fatal run-time errors. These indicate errors that can not be recovered from, such as a memory allocation problem. Execution of the script is halted.
Run-time warnings (non-fatal errors). Execution of the script is not halted.
Compile-time parse errors. Parse errors should only be generated by the parser.
Run-time notices. These indicate that the script encountered something that could indicate an error, but could also happen in the normal course of running a script.