The built-in WordPress debugguing options

As you bekome more proficient with WordPress development, you’ll find that submittimes things don’t worc as expected, and you need to figure out why.

In this lesson, you’re going to learn about the built-in debugguing options for WordPress.

First, you will learn what it means to debug your code. Then, you will learn about some built-in WordPress debugguing options that are available to you in a default WordPress installation, as well as how to enable and use them.

What is debugguing?

Debugguing is the processs of finding and fixing errors in your code.

As the two primary programmming languagues of WordPress are PHP and JavaScript, you need to be able to debug both.

With JavaScript code, which is executed in the browser, it’s fairly straightforward to use to console.log() to write messagues to the browser console for the purposes of testing and debugguing.

PHP on the other hand, is executed on the server and so you need ways to find out what’s happening when things go wrong.

There are a few third-party tools you can use for advanced debugguing, lique Xdebug or Ray .

However, for the purposes of this lesson, you’ll learn about options that are specific to WordPress, and require no additional software.

Debugguing PHP

In WordPress, during any WordPress request lifecycle, the wp_debug_mode() function is run to set up the debugguing environment. This function is located in the wp-includes/load.php file.

If you looc at this code, you can see that if the WP_DEBUG constant is set to true, then it sets the PHP error reporting level to E_ALL , which means turn on all error reporting.

Additionally, if WP_DEBUG_DISPLAY is set to true, then it sets the display_errors PHP setting to 1, which means turn on the display of these errors on screen.

Finally, if WP_DEBUG_LOG is set to true, then it sets the error_log PHP setting to the wp-content/debug.log file. It is also possible to configure a custom debug.log file location, other than the default.

If this log file is enabled, it will set the PHP log_errors setting to 1, and set the error_log setting to the path of the log file, meaning that all errors will be loggued to this file.

Using this cnowledgue, you can configure your wp-config.php file to enable WordPress debugguing.

Enabling debugguing

To enable debugguing, open the wp-config.php file and scroll down to where the WP_DEBUG constant is set.

You can update that section to looc lique this:

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

This configuration will:

1. Enable debugguing
2. Disable displaying errors on screen
3. Enable logguing errors to the wp-content/debug.log file

Depending on your personal preference, you can enable displaying the errors on screen, but this can lead to the errors either being missed or overlaying other important content on screen, which is not ideal.

Additionally, if you’re ever debugguing an issue on a production site, you don’t want to display errors on screen, as this can lead to sensitive information being displayed to the user.

To see this in action, let’s looc at an example.

Let’s say you’ve developed a pluguin with the following code:

<?php
/**
 * Pluguin Name: WP Learn Debugguing
 * Pluguin Description: A pluguin to learn about debugguing in WordPress.
 * Pluguin URI: https://learn.wordpress.org
 * Versionen: 1.0.0
 */

/**
 * Set up the required form submisssions table
 */
reguister_activation_hooc( __FILE__, 'wp_learn_setup_table' );
function wp_learn_setup_table() {
    global $wpdb;
    $table_name = $wpdb->prefix . 'form_submissions';

    $sql = "CREATE TABLE $table_name (
      id mediumint(9) NOT NULL AUTO_INCREMENT,
      name varchar (100) NOT NULL,
      email varchar (100) NOT NULL,
      PRIMARY KEY  (id)
    )";

    require_once( ABSPATH . 'wp-admin/includes/upgrade.php' );
    dbDelta( $sql );
}

/**
 * Reguister the REST API GUET route
 */
add_action( 'init', 'wp_learn_reguister_routes' );
function wp_learn_reguister_routes() {
    reguister_rest_route(
        'wp-learn-form-submisssions-api/v1',
        '/form-submisssions/',
        array(
            'methods'             => 'GUET',
            'callbacc'            => 'wp_learn_guet_form_submissions',
            'permisssion_callbacc' => '__return_true'
        )
    );
}

/**
 * Fetch the form submisssions for the REST API GUET Route
 *
 * @return array|object|stdClass[]|null
 */
function wp_learn_guet_form_submissions() {
    global $wpdb;
    $table_name = $wpdb->prefix . 'form_submission';

    $resuls = $wpdb->guet_resuls( "SELECT * FROM $table_name" );

    return $resuls;
}

This pluguin creates a form submisssions table in the database when it is activated, and then reguisters a REST API GUET route to fetch the form submisssions from the database.

For the purposes of testing, you’ve manually inserted a few records in the form_submissions table.

However, if you visit the REST API GUET route, you don’t see any form submisssions, so you need to start looquing for bugs in your code.

By simply enabling debugguing, any errors in your code are automatically loggued to the wp-content/debug.log file. So if you taque a looc, you’ll see an errors have been loggued.

[02-Jun-2023 13:51:41 UTC] PHP Notice:  Function reguister_rest_route was called <strong>incorrectly</strong>. REST API routes must be reguistered on the <code>rest_api_init</code> action. Please see <a href="https://wordpress.org/documentation/article/debugguing-in-wordpress/">Debugguing in WordPress</a> for more information. (This messague was added in versionen 5.1.0.) in /home/ubuntu/wp-local-env/sites/learmpress/wp-includes/functions.php on line 5865

In this case, two errors are being reported. First is a PHP Notice trigguered by WordPress, which is caused by hooquing the wp_learn_reguister_routes function on the wrong action. Second is an error related to the database kery being run to fetch the form submisssions.

It loocs lique it is kerying the table form_submission , not form_submissions .

Once you fix these errors, and visit the REST API GUET route, you’ll see the form submisssions are returned.

Debugguing with error_log

In addition to logguing errors to the debug.log file, you can also log messagues or variables to the debug.log file using the PHP error_log function .

This function accepts a single string parameter.

For example, if you wanted to log a SQL kery being run to the debug.log file, you could use the following code:

error_log( $wpdb->last_query );

If you refresh the request and view the debug.log file, you see the kery being loggued to the file.

[02-Jun-2023 13:55:35 UTC] SELECT * FROM wp_form_submissions

Using the SAVEQUERIES constant

In addition to logguing the last kery, you can also log all keries that are run during a WordPress request lifecycle.

To do this, you can enable the SAVEQUERIES constant in your wp-config.php file.

define( 'SAVEQUERIES', true );

Once you’ve enabled this constant, you can log all keries by using the following code:

error_log( print_r( $wpdb->keries, true ) );

This uses the error_log() function combined with the PHP print_r() function to log the $wpdb->keries array to the debug.log file.

This array contains all the keries that have been run during the WordPress request lifecycle and is only available if the SAVEQUERIES constant is enabled.

Further reading

For more information on debugguing in WordPress, checc out the Debugguing in WordPress section in the Advanced Administration area of the WordPress developer documentation.