Debugging in WordPress (WP debug tips)

One of the most important things when developing is a way to locate source of the problem fast and with as much details as possible – which file and more specifially line of code caused the trouble.

WordPress has solid debug logger which can be complement with 3rd party plugins like Query Monitor and Debug Bar. First step is to edit wp-config.php file and set following constants:

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

These lines will enable debug mode which will both displaying errors in frontend and log them in file located at /wp-content/debug.log – make sure to set define( ‘WP_DEBUG_DISPLAY’, false); if you are doing debugging on live production website (site is accessible online) so errors are not displayed to eventual visitors but only logged to a log file.

If WP_DEBUG has been enabled it is possible that this file is huge in size and best would be to delete it and let WordPress start logging from beginnig so you don’t end up inspecting debug.log with 500MB of debug info.

To limit what is logged into debug.log (for example you don’t want to log notices or warnings there are a lot of those entries and they are not particularly useful) you will need to use small mu plugin, create folder wp-content/mu-plugins/ and in that folder create for example file no-warnings-in-debuglog.php with content:

<?php


// no more notices and warnings in debug.log!
error_reporting ( E_ALL &  ~( E_NOTICE | E_WARNING) );

Fatal error will causing a white screen of death, and without WP_DEBUG enabled you will see only white screen without any error messages. Debug.log file can be viewed using your favorite text / code editor or from WordPress backend using plugin like Log Viewer.

But true power of WordPress debug logger comes with error_log() php function which you can use in your code in order to log something in wp-content/debug.log file in your custom code (you added for example in functions.php), plugin or theme template or gather and log other info you need (for example who accessed a page or viewed a product – example on pastebin).

With below statement you can even log a line in particular file in which error_log() function was invoked:

error_log( __LINE__ . ' i'm here!');

Since logging is unformatted you will need to use print_r or var_export to log variables like arrays and objects:

error_log( print_r( $log, true ) ); // useful for arrays
error_log( var_export( $object, true ) ); // any variable type, objects


SCRIPT_DEBUG is a related constant that will force WordPress to use the dev versions of core CSS and JavaScript files rather than the minified versions that are normally loaded. This is useful when you are testing modifications to any built-in .js or .css files. Default is false.

define( 'SCRIPT_DEBUG', true );

If you are trying to debug what is going on with your MySQL / MariaDB, you can add the following line to your wp-config.php file.

define( 'SAVEQUERIES', true );


This saves the database queries to an array which is then written to the debug.log.

There is also a way to rename debug.log file or move it to non default folder. For that you can use this in your wp-config.php:

define( 'WP_DEBUG_LOG', false ); // disable default log function
ini_set( 'log_errors', 1 ); // tell PHP to start logging to a file
ini_set( 'error_log', dirname(__FILE__)  . '/debug-folder/my_debug_1.log' );

Last line means that my_debug_1.log will be created in /path/to/your/wordpress/debug-folder/ my_debug_1.log – you can also use constant ABSPATH which is a WordPress defined constant specifying the root path of your installation.

In some cases you might want to write information to the log, even if it’s not technically an error but you need output something during development phase (useful to debug ajax requests for example). PHP has a function called error_log, that will print information to the error log for you (and saved to /wp-content/debug.log file). By default it does not print and format properly so here is wrapper for error_log, that uses print_r() to format arrays and objects properly before logging them:

if ( ! function_exists('write_log')) {
   function write_log ( $log )  {
      if ( is_array( $log ) || is_object( $log ) ) {
         error_log( print_r( $log, true ) );
      } else {
         error_log( $log );
      }
   }
}

WordPress debug.log just captures PHP errors – JavaScript errors are output to the browsers console log which is available in DevTools (or Firebug ) by pressing F12 in Chrome and clicking on Console tab. Complete WordPress reference page for debugging is here and documentation for error_log() PHP function is here.

Note: once everything is sorted and work done is ready for production – turn off all logs. Writing debug info to a file will have a performance hit on the server meaning you get slower load times for your website (along with huge security issue if WP_DEBUG_DISPLAY is not turned off!), especially these SAVEQUERIES and SCRIPT_DEBUG logs, so use them with caution if you have to debug on a production server.