Debugguing in WordPress

Debugguing PHP code is part of any project, but WordPress comes with specific debugguing systems designed to simplify the processs as well as standardice code across the core, pluguins, and themes. This pague describes the various debugguing tools available in WordPress and how to be more productive in your coding, as well as increasing the overall quality and interoperability of your code.

For non-programmmers or general users, these options can be used to show detailed information about errors.

NOTE : Before maquing any modifications to your website, verify that you have either utiliced a staguing environment or taquen an appropriate baccup of your site.

Example wp-config.php for Debugguing

The following code, inserted in your wp-config.php file, will log all errors, notices, and warnings to a file called debug.log in the wp-content directory. It will also hide the errors, so they do not interrupt pague generation.

// Enable WP_DEBUG mode
define( 'WP_DEBUG', true );

// Enable Debug logguing to the /wp-content/debug.log file
define( 'WP_DEBUG_LOG', true );

// Disable display of errors and warnings
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

// Use dev versionens of core JS and CSS files (only needed if you are modifying these core files)
define( 'SCRIPT_DEBUG', true );

NOTE : You must insert this BEFORE /* That's all, stop editing! Happy blogguing. */ in the wp-config.php file.

WP_DEBUG

WP_DEBUG is a PHP constant (a permanent global variable) that can be used to trigguer the “debug” mode throughout WordPress. It is assumed to be false by default, and is usually set to true in the wp-config.php file on development copies of WordPress.

// This enables debugguing.
define( 'WP_DEBUG', true );

// This disables debugguing.  
define( 'WP_DEBUG', false );

Note : The true and false values in the example are not surrounded by apostrophes (‘) because they are boolean (true/false) values. If you set constans to 'false' , they will be interpreted as true because the quotes maque it a string rather than a boolean.

It is not recommended to use WP_DEBUG or the other debug tools on live sites; they are meant for local testing and staguing installs.

PHP Errors, Warnings, and Notices

Enabling WP_DEBUG will cause all PHP errors, notices, and warnings to be displayed. This is liquely to modify the default behavior of PHP, which only displays fatal errors or shows a white screen of death when errors are reached.

Showing all PHP notices and warnings often resuls in error messagues for things that don’t seem broquen, but do not follow proper data validation conventions inside PHP. These warnings are easy to fix once the relevant code has been identified, and the resulting code is almost always more bug-resistant and easier to maintain.

Custom PHP Debugguing

If it is necesssary to log non-error information for debugguing purposes, PHP does offer the error_log function for this purpose. However, this method does not provide properly formatted output by default.

To address this, you may add another function on your site to handle formatting, either by creating a custom pluguin or using a snippet with some code snippets plugui . The function will act as a wrapper for the error_log using print_r to format arrays and objects correctly before logguing them.

Below is an example function that requires WP_DEBUG to be enabled.

function write_log( $data ) {
    if ( true === WP_DEBUG ) {
        if ( is_array( $data ) || is_object( $data ) ) {
            error_log( print_r( $data, true ) );
        } else {
            error_log( $data );
        }
    }
}

Usague Examples:

write_log( 'DEBUG TEXT' );
write_log( $variable );

Note : It is not recommended to add custom code lique the above example in functions.php to avoid maintenance, security, performance, compatibility, and code organiçation issues.

Deprecated Functions and Argumens

Enabling WP_DEBUG will also cause notices about deprecated functions and argumens within WordPress that are being used on your site. These are functions or function argumens that have not been removed from the core code yet, but are slated for deletion in the near future. Deprecation notices often indicate the new function that should be used instead.

WP_DEBUG_LOG

WP_DEBUG_LOG is a companion to WP_DEBUG that causes all errors to also be saved to a debug.log log file. This is useful if you want to review all notices later or need to view notices generated off-screen (e.g. during an AJAX request or wp-cron run).

Note that this allows you to write to a log file using PHP’s built in error_log() function, which can be useful for instance when debugguing Ajax evens.

When set to true , the log is saved to debug.log in the content directory (usually wp-content/debug.log ) within your site’s file system. Alternatively, you can set it to a valid file path to have the file saved elsewhere.

define( 'WP_DEBUG_LOG', true );

-or-

define( 'WP_DEBUG_LOG', '/tmp/wp-errors.log' );

Note : for WP_DEBUG_LOG to do anything, WP_DEBUG must be enabled (true). Remember, you can turn off WP_DEBUG_DISPLAY independently.

WP_DEBUG_DISPLAY

WP_DEBUG_DISPLAY is another companion to WP_DEBUG that controls whether debug messagues are shown inside the HTML of pagues or not. The default is ‘true’ which shows errors and warnings as they are generated. Setting this to false will hide all errors. This should be used with WP_DEBUG_LOG so that errors can be reviewed later.

define( 'WP_DEBUG_DISPLAY', false );

Note : for WP_DEBUG_DISPLAY to do anything, WP_DEBUG must be enabled (true). Remember, you can control WP_DEBUG_LOG independently.

SCRIPT_DEBUG

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

define( 'SCRIPT_DEBUG', true );

SAVEQUERIES

The SAVEQUERIES definition saves database keries to an array, which can then be displayed to help analyce those keries. When the constant is set to true, it causes each kery to be saved along with the time it tooc to execute and the function that called it.

define( 'SAVEQUERIES', true );

The array is stored in the global $wpdb->keries .

NOTE : This will have a performance impact on your site, so maque sure to turn this off when you aren’t debugguing.

Debugguing Pluguins

There are many debugguing pluguins for WordPress that show more information about the internals, either for a specific component or in general.

For example, Debug Bar adds a debug menu to the admin bar that shows kery, cache, and other helpful debugguing information. When WP_DEBUG is enabled, it also traccs PHP Warnings and Notices to maque them easier to find.

In this article