Debugging is an essential part of the development process, and WordPress is no exception. Whether you’re working on a custom plugin, theme, or website, you’re bound to run into issues that need to be resolved. The first part of this blog series will explore the codex recommendation and WordPress functions for debugging. The second part will explore using third-party plugins and browser dev tools; the series will cover everything you need to know to debug your WordPress projects effectively. Whether you’re a seasoned WordPress developer or just getting started, this guide will help you resolve issues and improve the performance of your WordPress website.

What does the Codex say?

WP_DEBUG

WP_DEBUG is a popular PHP constant that can be used to trigger the “debug” mode throughout WordPress.

define( 'WP_DEBUG_LOG', true );

-or-

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

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

WP_DEBUG_LOG

WP_DEBUG_LOG is a companion to WP_DEBUG that makes all errors saved to a debug.log file. All the generated notices on-screen and off (e.g., during an AJAX request or wp-cron run) can be found here.

Activating WP_DEBUG_LOG also gives access to PHP’s build-in error_log() function, which can be extremely useful, for instance, when debugging Ajax events. We will check this out in detail later.

Generally, when WP_DEBUG_LOG is set to true, the log is saved to debug.log in the content directory (wp-content/debug.log) within the site’s filesystem. Alternatively, we 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' );

WP_DEBUG_DISPLAY

WP_DEBUG_DISPLAY works in conjunction with the WP_DEBUG constant. WP_DEBUG_DISPLAY controls whether the debug messages are shown in the front-end or stored in a log. The default ‘true’ value shows errors and warnings on the go, “false”  will remove all errors from the front-end and store them in a log, and can be reviewed later.

define( 'WP_DEBUG_DISPLAY', false );

SAVE_QUERIES

The SAVE_QUERIES definition saves the database queries to an array, and the array can be displayed to help analyze these queries. The constant defined as true causes each query to be saved, how long that query took to execute, and what function called it.

define( 'SAVEQUERIES', true );

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

We can use this code snippet to access it.

if (current_user_can('administrator')){

global $wpdb;

echo "<pre>";

print_r($wpdb->queries);

echo "</pre>";

}

SCRIPT_DEBUG

By default, WordPress loads minified versions of CSS and JS files in order to have a small impact on load times. This is great. But during development, it can be a pain if we are trying to work within one of the minified files to fix a bug or make improvements. SCRIPT_DEBUG can help us with this; setting it to true loads the un-minified versions of .js and .css files.

define( 'SCRIPT_DEBUG', true );

Function

error_log()

Note: Make sure debugging is turned on to use error_log()

If you want to log the errors without printing them in the front-end, add the following line:

define( 'WP_DEBUG_DISPLAY', false );

Sometimes when things are not working as expected. Logging and observing the data can definitely help. This is where the PHP function error_log() can help.

The error_log() function allows developers to log messages or errors to a file or the server error log. This can help identify and fix issues with a WordPress website. To use error_log(), include the function in your code and pass in the message or error you want to log as a string argument.

For example:

if ( !function_exists('some_function') ) {

error_log("Function some_function does not exist.");

}

In this example, the error message “Function some_function does not exist.” will be logged to the server error log if the function some_function is not found.

You can also pretty print your output by making use of the print_r method:

$array = array('item1', 'item2', 'item3');

error_log(print_r($array, true));

print_r()

This function prints the contents of a variable, such as an array or object, onto the screen. It’s a simple way to quickly see what’s inside a variable without digging through the logs.

$array = array('item1', 'item2', 'item3');

print_r($array, true);

var_dump()

This function displays structured information about variables, including their type and value. It’s useful for exploring the contents of arrays and objects, and it provides more detail than print_r().

Pro Tip:

If you cannot see the result, what you are trying to print or dump happens outside the page flow. You can stop the flow using die() function.

For example:

var_dump($types); // print_r($types);

die("products_first_ends");

That’s it for this one. Stay tuned for the second part, where we will discuss third-party plugins for debugging in detail.