Debugging in WordPress

If you want to keep track of any errors and warnings that may be happening on your WordPress website keep reading on. This will be a quick guide on how to debug PHP errors, where and how to check the error logs and add some custom logs.

It’s usually good to be aware of what’s going on with your website even if you’re not a developer. Sometimes the issues can be as easy to fix as updating a plugin, or replacing it, and other times it may be something harder to debug, but in any case, it’s better to be aware and try to fix any issues that may occur. There can be tons of useful information in logs that we’d be missing otherwise.

WP_DEBUG

WordPress provides us with debugging options out of the box: WP_DEBUG. It is disabled by default, you can enable it and you’ll get all the PHP errors and warnings displayed for you on the screen. In most cases this is not desirable as not only you but all the visitors of your website will see those errors. If you’re still in development mode and the website isn’t accessible by others, then it might be fine.

To enable debugging you need to edit the wp-config.php file.

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

// Disable:
define( 'WP_DEBUG', false );

Now we can enable the debugger and it has some options. You can also enable logging the errors instead of displaying them on screen.

// Enable both on screen and logging:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );

In this case you’ll have them both on screen and logged. The file that contains the logs is in your wp-content directory and is called debug.log.

By default this file doesn’t exist and WordPress will create it when an error or a warning happens.

To enable only logging, and disable displaying errors on screen, you can set WP_DEBUG_DISPLAY variable value to false.

// Enable only logging:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

With this setup you can log all the errors and not display them on the screen. However, this log file wp-content/debug.log is publicly accessible and there might be information in your logs that you wouldn’t want others to have access to, someone trying to get access to your system, for example.

To prevent that, you have at least 2 options:

1. Either block access to the log file by adding the block below to your .htaccess file.

# Block access to debug log.
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^wp-content/debug.log - [F,L]
</IfModule>

To try if that was implemented correctly, visit YOUR_DOMAIN.COM/wp-content/debug.log and you should see something like this:

Forbidden

You don't have permission to access /wp-content/debug.log on this server.

2. Or you can log the errors in other file:

// change this:
define( 'WP_DEBUG_LOG', true );

// to this something like this:
define( 'WP_DEBUG_LOG', '/home/username/website.com/logs/wp/error.log' );

You need to set the absolute path of the log file and the directory must exist and be writable by the server user. The log file will be created by WordPress. This feature is available since WordPress 5.1.

Add custom log messages

If you want to add your own messages to the debug log, you can do so by having a function similar to the one below in your plugin (or theme).

if ( ! function_exists( 'my_logger' ) ) {
    /**
     * Logs custom messages to WP debug log.
     *
     * @param  string  $msg
     * @return void
     **/
    function my_logger( $msg ) {

        if ( true === WP_DEBUG ) {
            error_log( $msg );
        }
    }
}

// Call it like this:
my_logger( 'Bow ties are cool!' );

// or maybe something useful:
$data = gat_data();
if ( ! $data ) {
    my_logger( 'Data is not available.' );
}