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 wears many hats; from coding and design, to marketing and partnerships. Before starting Delicious Brains, Brad was a busy freelance web developer, specializing in front-end development.

  • Good tips Brad! I will try using the single file approach, good debugging is definitely essential. I have also been using a plugin which can help a lot “Query Monitor”. It measures performance and it will log all PHP erros/warning/notices, including AJAX ones.

    Another constant which can be very usefull is “define( ‘SAVEQUERIES’, true );”. This will save all run sql queries into $wp_query->queries. If a plugin is running too many queries, this will let you know.


  • Do. This.

    Then open up Console.app, open the debug.log file, and keep the console running to view the logs in realtime. If you’re on a linux box you could use the shell command `tail`.

    P.S. I have to admit I don’t use WP_DEBUG_LOG, instead I open up the php error log in console and make sure PHP is set to report everything (including notices people!).

  • Thanks. Do you know if having debug enabled creates a performance hit at all ?

  • raisononline

    I wonder if it is possible to have a single MU Plugins folder for multiple local installs. Asked here: http://wordpress.stackexchange.com/questions/179078/single-must-use-plugins-directory-for-local-development

  • I’m a fan of using the Console app. The option to ‘Animate the application icon’ is really useful – causing the application icon to bounce in the dock when an error occurs. I used to constantly CMD Tab to the log file to check if errors have occurred, but now it’s blatantly obvious when they have.

  • I also don’t want to have anything printed in the page. After trying different approaches, including XDebug, PhpStorm debugging functions or using logs as pointed in the article. I ended up writing a plugin for implementing a neat Chrome extension, that lets you use the javascript console for BOTH javascript and php debugging https://github.com/nekojira/wp-php-console comes as well with a separate terminal to test php functions on the fly

  • Laura Rodd

    Thank you for posting this Brad, very helpful to understand how to fix bug issues in WordPress. We’ve written an article about WordPress debugging feature which is really easy to use and can save us a lot of time, it’d be great to have your feedback and hopefuly it can add some additional info for you to use 😉 https://goo.gl/Ps4ene

  • luk

    thank you! this is what i looking for! one log file for all projects!