3 Reasons Why You Should Be Using WP_DEBUG_LOG In Your WordPress Development


Like most things related to WordPress development, the best way to understand WP_DEBUG_LOG is to do a search of the WordPress core codebase.

The important bit shows up in wp-includes/load.php:

function wp_debug_mode() {
	if ( WP_DEBUG ) {
		error_reporting( E_ALL );

			ini_set( 'display_errors', 1 );
		elseif ( null !== WP_DEBUG_DISPLAY )
			ini_set( 'display_errors', 0 );

		if ( WP_DEBUG_LOG ) {
			ini_set( 'log_errors', 1 );
			ini_set( 'error_log', WP_CONTENT_DIR . '/debug.log' );
	} else {
	if ( defined( 'XMLRPC_REQUEST' ) )
		ini_set( 'display_errors', 0 );

I’ll spare you the line by line detail, but essentially if you set WP_DEBUG to true, set WP_DEBUG_DISPLAY to false, and WP_DEBUG_LOG to true, the effect will be that you will get errors logged to a debug.log file in your wp-content folder and no errors will be displayed in PHP output (i.e. in your browser).

To set these constants, you add the following to your wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'WP_DEBUG_LOG', true );

But why do this?

1. Hidden errors

So you like to read errors in your web browser eh? Are you sure you can see everything? What about divs hidden with CSS? What about AJAX requests?

The UI is not a reliable place to be catching errors. The PHP log file reveals all.

2. Missing errors

Maybe you like to use plugins like Debug Bar or Query Monitor to capture errors and are happy with that. I don’t blame you. Those plugins are awesome.

However, I’ve found that they miss some errors. I suspect this is because they are plugins and other plugins may get loaded before them. I suppose you could change the load order so they load first, but then what about errors in MU plugins and WordPress core itself? Also, last I checked, Strict Standards errors weren’t picked up by these plugins.

As great as these plugins are for other things, I think it’s a mistake to rely upon them to catch all PHP errors. PHP itself is the most reliable source of error reporting and that’s what you get in debug.log.

3. Third party plugins

It’s one thing if your code is spitting out errors. You can fix those.

But what about third party plugins you have activated? What if they’re puking out warnings and notices all over your UI? And since WP_DEBUG turns on reporting of all errors, you get warnings, notices, strict standards, everything. The kitchen sink. It can be overwhelming and nearly impossible to work with certain plugins activated.

In the past, I would just deactivate the offending plugins. Not exactly a great solution. Besides, what if it’s critical to what you’re working on and you can’t deactivate it? In the past, I would just disable WP_DEBUG and keep hacking away. Shameful, I know.

At this point I’m just going to assume I’ve won you over. You’ve already added the constants above to your wp-config.php and are logging errors to debug.log. Now you have to start monitoring and filtering your debug.log.

Monitoring and filtering debug.log

Not only do you have to start monitoring debug.log for errors, but you really want to filter out all the noise created by the third party plugins. Otherwise your legitimate errors will get lost in the noise.

Apparently some people (hat tip Paul de Wouters) use the Console app in OS X to read the log file and use it’s filtering to filter out errors from third party plugins. Sounds neat, though I haven’t tried it. I’ve solved this in a much more roundabout way.

I wrote a PHP script. It simply monitors a log file (uses tail -f) for changes and dings when there’s an error. It can also filter out whole Xdebug blocks based on regular expressions you define, allowing you to ignore third party plugin warnings and notices. I blogged about it almost a year ago and have made quite a few refinements since then.

One debug.log for all sites

I used to have a debug.log for every site I had in my development environment. When I switched to work on a different site, I had to switch to monitoring another log file. Not ideal.

Now I have all my sites configured to log to a single file. To do this, I had to use a must-use plugin. I added the following code to wp-content/mu-plugins/custom-debug-log-path.php for each of my sites:

 * Plugin Name: Custom Debug Log Path

ini_set( 'error_log', '/srv/www/all-debug.log' );

Now I only need to monitor a single log file for any errors in any of my dev sites.

This setup works exceptionally well. I’m sure there are still some refinements to be made going forward, but I’m happier than ever with my error reporting.

Do you use a similar setup for error reporting? Are there any improvements you would suggest?

About the Author

Brad Touesnard

As founder of Delicious Brains Inc, Brad has worn many hats. He now spends most of his time managing the product teams and growing the business. Before starting this company, Brad was a freelance web developer, specializing in front-end development.