Debugging Wordpress - Enabling Wp_Debug To Troubleshoot Issues

Enabling WP_DEBUG in wp-config.php

WP_DEBUG is a constant in WordPress that allows developers to enable the display of notices during development and debugging. It outputs debug messages, errors, warnings and other information that is useful for diagnosing problems in plugins, themes or in WordPress core.

To enable WP_DEBUG, add the following line to your wp-config.php file located in the root WordPress directory:

define('WP_DEBUG', true);

This will enable the display of all debug messages. You can also enable specific debug components by passing an integer as value instead of true:

Table of Contents

// Enable debug log
define( 'WP_DEBUG_LOG', true );
 
// Enable debug display
define( 'WP_DEBUG_DISPLAY', true );
 
// Show database errors 
define( 'WP_DEBUG_DB', true );

It’s recommended to only have WP_DEBUG enabled on development or staging sites and to disable it on production sites. Leaving debugging enabled on live sites can expose sensitive information.

Viewing Debug Messages

With WP_DEBUG enabled in wp-config.php, WordPress will output debug messages, warnings and fatal error notifications to the browser. These are displayed to administrators and can help diagnose problems.

Different types of debug messages include:

Notices – Non-critical issues that shouldn’t stop operations
Warnings – More severe issues that may cause problems
Fatal errors – Critical issues that stop execution
Deprecation notices – Features that have become obsolete

Pay attention to warnings and fatal errors in particular as they indicate issues that need to be fixed like PHP syntax errors, invalid function usage, missing files and more.

Debugging Specific Issues

Log PHP Errors and Exceptions

Enabling WP_DEBUG will log fatal PHP errors to the browser but exceptions may still get swallowed. To further debug PHP issues, enable logging to file:

ini_set('log_errors','On');
ini_set('error_log', __DIR__ . '/debug.log');

This will log errors and exceptions in depth to the specified logfile for analysis.

Log MySQL Queries

To check which database queries are being triggered, enable MySQL debugging by adding this line to wp-config.php:

define('SAVEQUERIES', true);

All MySQL queries will then be saved to the $wpdb->queries array for debugging.

Debug JavaScript Issues

Use browser developer tools like the Console to debug JavaScript. Some common issues are:

Reference errors – Undefined variables or functions
Syntax errors – Mistakes in code logic or structure
Type errors – Mismatch between data type expect and received

Enabling logging of JavaScript errors can also help diagnose issues.

Fix CSS Conflicts

If a WordPress theme or plugin is not styled properly, enable debug info in the rendered HTML source code to see CSS rules, inheritance and cascade ordering to debug style issues:

 
add_filter('w3tc_can_print_comment', '__return_true');

This will add CSS debugging comments to pinpoint rules causing problems.

Customizing Error Logging

Log to File Instead of Displaying Errors

Instead of displaying errors in the browser, you can log them directly to a file for analysis by adding the following to wp-config.php:

define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'log_errors', 1 );
@ini_set( 'error_log', dirname(__FILE__) . '/debug.log' );

This will silently log all errors and warnings without publicly exposing them.

Configure Error Logging Thresholds

By default all errors are logged with WP_DEBUG. To only log warnings and higherseverity issues, use the WP_DEBUG_DISPLAY filter:

add_filter( 'wp_debug_display', function() { 
        return WP_DEBUG_DISPLAY_WARNINGS_AND_ERRORS; 
} );

This will hide notices in favor of more severe messaging.

Prevent Debug Info Leaking Publicly

If WP_DEBUG gets accidentally left enabled on a production site, you can prevent debug infos from being exposed publicly by adding this code to wp-config.php:

if ( !is_user_logged_in() ) {
   add_filter( 'wp_debug_display', '__return_false' ); 
   add_filter( 'wp_debug_display_errors', '__return_false' );
}

This will hide errors and exceptions from non-logged in visitors.

Recommendations and Best Practices

Use Staging Sites for Debugging

It’s always recommended to enable WP_DEBUG and test new code on a staging or development WordPress site before deploying to production. Pushing untested code with debugging enabled on live sites is risky.

Debugging Plugins and Themes

When debugging plugins or themes, selectively enable WP_DEBUG logging/output just for that plugin or theme code using conditionals:

if ( strpos( $current_filter, 'my_plugin' ) !== false ) {
    WP_DEBUG_LOG = true;
}

This isolates debug output to just the specified plugin or theme.

Security Considerations

WP_DEBUG can expose sensitive info publicly like server paths, database creds etc. So always disable on production sites and block non-logged in users from seeing debugging output if accidentally left open.

Performance Impacts

Logging extensive debug information like queries and request data can slow down overall site performance. After debugging, make sure to disable or configure debugging thresholds appropriately.

Debugging WordPress – Enabling Wp_Debug To Troubleshoot Issues