How To Debug WordPress

WordPress Debugging is essential if you are developing a WordPress theme or plugin. The following methodology concerns exclusively your development workstation and never the production server.

Enable Errors Logging in WordPress

WordPress does not display errors by default. You have to make changes in your wp-config.php.

To enable error displaying on the screen use

define( 'WP_DEBUG', true );

To enable error logging to the file wp-content/debug.log use:

define( 'WP_DEBUG_LOG', true );

These are enough in most cases.

Log MySQL Queries

To enable MySQL queries logging, in your wp-config.php use:

define( 'SAVEQUERIES', true );

Then use in your PHP code something like this:

global $wpdb;
echo print_r( $wpdb->queries, true );

This setting might become a performance killer – use it ONLY when it is needed.

Sample output:

Array
(
    [0] => Array
        (
            [0] => SELECT option_name, option_value FROM wp_options WHERE autoload = 'yes'
            [1] => 0.0025980472564697
            [2] => require_once('wp-load.php'), require_once('wp-config.php'), require_once('wp-settings.php'), wp_not_installed, is_blog_installed, wp_load_alloptions
            [3] => 1661511235.2872
            [4] => Array
                (
                )
        )
)

Summary of changes in wp-config.php

/**
 * For developers: WordPress debugging mode.
 *
 * Change this to true to enable the display of notices during development.
 * It is strongly recommended that plugin and theme developers use WP_DEBUG
 * in their development environments.
 *
 * For information on other constants that can be used for debugging,
 * visit the documentation.
 *
 * @link https://wordpress.org/support/article/debugging-in-wordpress/
 */

// define( 'WP_DEBUG', false );

// log errors on screen
define( 'WP_DEBUG', true );

// additionally log errors in wp-content/debug.log
define( 'WP_DEBUG_LOG', true );

// ATTENTION - it might become a performance killer - use it ONLY when it is needed
// define( 'SAVEQUERIES', true );

Log Your Own Messages

Use error_log or file_put_contents to write to a custom destination.

Example using error_log:

error_log( gmdate( 'Y-m-d H:i:s' ) . ' my-debug-message' . PHP_EOL, 3, '/tmp/php_errors.log' );

Example using file_put_contents:

file_put_contents( '/tmp/php_errors.log', gmdate( 'Y-m-d H:i:s' ) . ' my-debug-message' . PHP_EOL, FILE_APPEND );

Then use tail -f to monitor file changes, e.g.

tail -f /tmp/php_error.log

If you like to use a graphical application to monitor your log file, glogg is an excellent choice.

Chrome Logger

Chrome Logger is a Google Chrome extension for debugging server-side applications in the Chrome console.

Here is a quick hack to use Chrome Logger with WordPress:

Download the browser extension here. Enable it.

Download ChromePhp.php class from its Github repo and put it in a folder (e.g. /path/to/your-site/src).

Create a file in mu-plugins folder with any name you want, e.g. chrome-logger.php

<?php
/**
 * Just require ChromePhp class
 *
 * @package debug
 */

require_once ABSPATH . 'src/ChromePhp.php';

That’s it! Now you can output messages to Chrome Console from your PHP code, using:

\ChromePhp::log( 'foo' );

Display Current Template File

Use the following code in functions.php (child theme recommended)

function show_template() {
	global $template;
	echo $template . ' | ' . get_page_template();
}
add_action( 'wp_head', 'show_template' );

Or you may use: https://wordpress.org/plugins/show-current-template/

Query Monitor Plugin

You may want to use a plugin for debugging. In this case, take a look at Query Monitor.

Worth seeing