How to Use WordPress Debug System to Optimize Your Theme and Plugin

There are thousands and thousands of themes and plugins (both free and premium) for the entire WordPress community and their numbers continues to grow with each passing day. WordPress follows a coding standard and expects developers to follow the same while developing plugins and themes for the users. It's not just the coding style, but the use of deprecated functions and bugs that must be taken care of while developing an extension for WordPress. During the development phase, the best way to come out with a cleanly coded plugin or a theme is to use the WordPress internal debug facility. It's easy to use and provides you with detailed PHP stack trace to identify problems in your code. The techniques discussed here are not on a production server. You must use these methodologies in a test environment while optimizing the theme or plugin code.

Activating Debug Mode

The first obvious step to benefit from WordPress debug functionality is to activate it correctly. There are several directives associated with the debug system that lets you customize the debug environment according to your needs. Here's the first primary directive that activates the debug mode. You have to include all these directives in wp-config.php file.

define('WP_DEBUG', true);

This directive activates the debug mode in WordPress. The second parameter is a Boolean value and should not be included in parenthesis. By default, this directive is deactivated with a false Boolean value. You simply have to replace it with a true value.

Once debug mode is activated, by default all the notices, warnings or errors are displayed directly on the screen. This generally makes the screen cluttered and makes it impossible to navigate through different options and menus within the dashboard. To get rid of this problem, you must suppress debug trail display on the screen. Here's the directive to do that.

define('WP_DEBUG_DISPLAY', false);

Removing error messages from the display presents you with a new challenge. How to track the debug trail now? Since you're not going to see them on the screen, there must be some mechanism to divert the debug message stream to an alternative source which you can access later for detailed analysis. You can instruct WordPress to store all the debug messages in a special log file debug.log that will be created under /wp-content/ directory. Here's the directive to do that.

define('WP_DEBUG_LOG', true);

Now, if you also want to inspect and optimize the database queries that your theme or plugin may be using, you must activate a mechanism to keep an eye on these DB queries. For that, use the following directive.

define('SAVEQUERIES', true);

This directive creates a special array, where all the executed queries and their associated data like SQL query, function which triggered it and the maximum execution time are stored. But simply defining this directive doesn't give access to all the query related data. For that, you have to use $wpdb->queries to fetch all the SQL debug data. To understand how it is used, you can inspect the wpdb-profiling.php file in WPDB Profiling plugin.

Using The Log File

The log file generated by WordPress contains complete timestamped PHP stack trace to find out errors, bugs, and deprecated code. Although you can filter out deprecated function calls from the log file, I'll strongly recommend using Log Deprecated Notices plugin that makes it very easy to monitor any usage of deprecated code within your theme or plugin.



The log file is very easy to interpret and follow. The leftmost column contains the timestamps when the events took place. The red arrows in the picture show notices and warnings along with an explanatory message. Each section contains the function calls in chronological order from top to down. This way you can easily track where the code needs to be corrected or optimized.

Plugin Assisted Debugging

If you don't want to mess with cryptic log files or manual directive insertions, you can use several powerful debugging plugins available for WordPress developers. Here are some of the select plugins that can be used to easily debug your WordPress code.


Debug Bar - This is the most popular and widely used plugin by WordPress developers. It adds a handy debug menu within the top admin bar and provides several vital details to help you optimize the code. If you've already enabled debug mode along with 'SAVEQUERIES directive in the wp-config.php' file, you must also install Debug Bar Console plugin that attaches a PHP/MYSQL console to the existing debug bar for displaying all PHP and MySQL debug information. The combination of both these plugins gives you an all-in-one debugging monster to help you write the most bug-free and complaint code for your theme or plugin.


SM Debug Bar - This is yet another useful debugging plugin for theme and plugin developers. This handy solution lets you watch and print the value of PHP variables in real time within the dashboard. It creates a debug button in the admin bar to access the debug console. It's perfect for optimizing your queries and data-intensive routines while writing functions for your theme and plugins. Its sliding console presents the values through a nice interface making the code inspection very easy. Once installed, access to this console is only reserved for administrators so that general user cannot fiddle with the code without your permission.

Over To You

I'm sure there are several other ways to debug WordPress code and I would really like to know about them in the comments below. If you have some killer techniques to debug plugins and themes, do share with our readers so that they can benefit from it. If you have working examples or links to some unique WordPress debugging methodologies, you can definitely share it with us.