Debugging WordPress in your development environment

No error is a good error, so the fact that WordPress hides all errors from the user by default, makes debugging complicated. You need to know which old plugin might be causing errors, or what outdated (deprecated) functions are used where. Based on that knowledge you can make a decision on whether to fix an error or to maybe update or remove that old plugin completely. Wordpress won’t inform you when deprecated PHP functions are called, nor does it tell you about fatal errors. Instead it shows a generic page stating that an internal server error occurred. That behaviour is fine for a production site, but should be handled differently in a development environment. So let’s make sure that you see all errors.

If you have finished Part 2 of my tutorial series, you are now using an .env file to store configuration variables outside of your repository code. So let’s use the WORDPRESS_ENV variable to check if we’re developing and then disable the WordPress Error Handler (the generic error message):

wordpress/wp-config.php
if ($_ENV['WORDPRESS_ENV'] === 'development') {
    define('WP_DISABLE_FATAL_ERROR_HANDLER', true);
}

In case this does not help, try to force Exceptions to be thrown by setting a custom error handler. There are plugins which modify PHPs error_reporting settings at runtime and thus might hide errors from you.

wordpress/wp-config.php
if ($_ENV['WORDPRESS_ENV'] === 'development') {
    define('WP_DISABLE_FATAL_ERROR_HANDLER', true);

    /** optional: custom error handler */
    function exceptions_error_handler($severity, $message, $filename, $lineno) {
        if (error_reporting() == 0) {
            return;
        }
        if (error_reporting() & $severity) {
            throw new ErrorException($message, 0, $severity, $filename, $lineno);
        }
    }
    set_error_handler('exceptions_error_handler');
    /** end optional handler */
}

Also, many plugins attempt or actually override PHP settings, which is kind of nasty, but hey.

You might want to look for all occurrences of ini_set and error_reporting in your codebase to make sure, no plugin overrides your own PHP preferences.

If you cannot edit your php.ini you can also override the php.ini setting at runtime:

wordpress/wp-config.php
@ini_set('display_errors', '1');
@ini_set('display_startup_errors', '1');
error_reporting(E_ALL); // log everything

In the repository, you will see that I have done a couple of additional things. The standard WP_DEBUG constants aren’t worth mentioning here, but of course I added them to the wp-config.php – as you can see, I also added a second section where I make sure certain debugging settings are turned off for production.

Tutorial: Debugging WordPress in Development debug-in-development-environment.zip (30.8 MB)

Continue to Part 4 “Continuous Integration (CI) with Github Actions”.