WordPress Debugging Tips and Tricks

Outline

Is your WordPress website broken and you're not sure where to start? WordPress and PHP have several built-in functions to help you debug your code and find what went wrong. In the post below, you will find a few tips and tricks that have helped me along my WordPress journey, and hopefully, they will help you too!

Enable Debug Log

The below code is often added near the bottom of your wp-config.php file and will allow debugging output to be written to the /wp-content/debug.log file. Please note, debug output will only be written to the log file and not displayed on the front end of the site (i.e. WP_DEBUG_LOG = true and WP_DEBUG_DISPLAY = false).

This code is helpful when debugging errors on your site and also for debugging custom content which is discussed later in the next section. To learn more about debugging in WordPress, check out this article in the Codex.

<?php

// Turn on Debug
define( 'WP_DEBUG', true );

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

// Disable display of errors and warnings
define( 'WP_DEBUG_DISPLAY', false );

?>

Write custom content to the debug.log file

You can write custom content to the debug log by using the built-in PHP function error_log. PHP DOC. If you've ever run a WP_Query and wondered what the object returned looks like, this is how you can find out!

Dump an Object: error_log(print_r($my_object, true));

Dump a String: error_log("Happy Dance :)");

Example:

<?php

// Example Query for all posts by isaac
$the_query = new WP_Query( array( 'author_name' => 'isaac' ) );

// Now we dump the query object to the debug.log file (an alternative to var_dump)
error_log(print_r($the_query, true));

?>

See how simple that was!

Dump to the frontend

Sometimes you just want to quickly see what an object or variable looks like and don't want to mess with log files. This is where var_dump function comes into play. This built-in PHP function will echo whatever you pass into it out to the frontend.

<?php

// Example from: https://www.php.net/manual/en/function.var-dump.php
$a = array(1, 2, array("a", "b", "c"));
var_dump($a);

?>

Format your objects

When you dump an object out to the front end of your site, the formatting is often pretty ugly. With a single <pre> HTML tag, we can fix that up :)

<pre>
    <?php
    // Example from: https://www.php.net/manual/en/function.var-dump.php
    $a = array(1, 2, array("a", "b", "c"));
    var_dump($a);
    ?>
</pre>

Build a debug helper

Helper functions can implement DRY (don't repeat yourself) principles for frequently used code. In the case of debugging, we can write a helper function to help our code DRY. The below debug_kit helper function will automatically add the <pre> tags when calling var_dump and also auto-format your content (String or Object) when writing to the error log. Simply drop this in your functions.php file to start easily debugging.

<?php

function debug_kit($data, $log=true, $dump=false) {
    // Perform the requested action(s)
    if($log) {
        // Format the data
        if(is_array( $data ) || is_object( $data )) {
            error_log(print_r($data, true));
        } else {
            error_log($data);
        }
    }

    if ($dump) {
        echo "<pre>";
        var_dump($data);
        echo "</pre>";
    }
}

// Examples:
$a = array(1, 2, array("a", "b", "c"));

// Log to a file
debug_kit($a, true);

// Log to frontend
debug_kit($a, false, true);

?>

Note, some inspiration came from a blog post on Elegant Themes.

Run code only on your IP

Sometimes you want to write a test function, shortcode, etc. but don't want that test available to the public. To start, simply find your IP by searching Google for "my IP" and use it to replace <YOUR IP ADDRESS> in the code below. Next, inside the if statement, write any code you want and you can rest easy knowing that it will only run for you :)

<?php 
    if ( $_SERVER["REMOTE_ADDR"] == '<YOUR IP ADDRESS>' ) { 
          // do something 
    }
?>

I hope you have found a few of these tips and tricks helpful and I recommend bookmarking this page for the next time you need to debug code on your WordPress site.