Debugging WordPress: Techniques & Tools

Debugging is an essential skill for any developer, every good developer should turn on debugging before getting started coding a new plugin or theme. WordPress Codex “highly recommends” that developers use their specific debug tools This article will show several powerful ways to debug WordPress and PHP errors.

WP_DEBUG

WordPress uses a global constant to specify the needed level of debugging:

• WP_DEBUG is used to set the debugging mode on or off.
• WP_DEUBG_DISPLAY shows errors or hides them.
• WP_DEBUG_LOG saves your error messages in wp-content/debug.log.

The three global constants can be set to true or false in wp-config.php, like this:

define("WP_DEBUG", true);

define("WP_DEBUG_DISPLAY", true);

define("WP_DEBUG_LOG", true);

OR

define("WP_DEBUG", false);

define("WP_DEBUG_DISPLAY", false);

define("WP_DEBUG_LOG", false); 

SCRIPT_DEBUG

When this option and WordPress debugging are enabled WordPress will use the development versions of core CSS and JavaScript files instead of the minified (compressed) version that it normally uses. This debugging option is useful if you are testing changes in .js and .css files. To enable this option add the below line to your wp-config.php file:

define( ‘SCRIPT_DEBUG’, true );

SAVEQUERIES

The SAVEQUERIES definition saves the database queries to an array and that array can be displayed to help analyze those queries. The constant defined as true causes each query to be saved, how long that query took to execute, and what function called it.

define('SAVEQUERIES', true);

The array is stored in the global $wpdb->queries.

NOTE: This will have a performance impact on your site, so make sure to turn this off when you aren’t debugging.

is_wp_error()

WordPress has built-in tool for debugging which is  is_wp_error() . This method  checks if a certain result is of type WP_Error. WP_Error is actually the returned object you should receive if a WordPress method fails.

Example:

$post = array(
    'post_title'    => 'Test post',
    'post_content'  => 'This is my post.',
    'post_status'   => 'publish',
    'post_author'   => 1
);
$result = wp_insert_post( $my_post );

if(is_wp_error($result)){
    echo $return->get_error_message();
}

The code above will add  a new post using the WordPress method wp_insert_post(). If this method fails, it will return WP_Error object.

Debug Bar

A very useful tool for debugging WordPress errors is the Debug Bar free plugin from the WordPress repository. The plugin uses the above methods  and gets the information about every page.

Query Monitor

A WordPress Query Monitor plugin for monitoring database queries, hooks, conditionals, HTTP requests, query vars, environment, redirects including automatic AJAX debugging and more.

Simply Show Hooks

The plugin  Simply Show Hooks is a nice plugin for showing every hook that is running on any page. If you encounter a situation where all error reporting ideas are not working, and you will, then comes the time for fetching out every and all running hooks.

This plugin will tell you what action or filter hooks that run on any page. You can then start analyzing and debugging each hook code. You can also see the attached methods to every hook. And even find out the priority of each.

WPDB Error Reporting

If you use the wpdb class for dealing with your database, then you will always need error reporting. Whether it is for making sure that your queries run correctly, or for showing up error messages for debugging.

Example:

global $wpdb;
// Before running your query:
$wpdb->show_errors = TRUE;
$result = $wpdb->get_results("SELECT field_value FROM table_name");
if(! $result){
    $wpdb->print_error();
    // Or you can choose to show the last tried query.
    echo $wpdb->last_query;
}


// Enables WordPress’s DB Error reporting
$wpdb->show_errors = true;
 
$results = $wpdb->get_results("SELECT * FROM $wpdb->posts 
   WHERE post_title = ‘foo bar baz");
print_r($results);
 
// Outputs 
// WordPress database error: [You have an error in your 
// SQL syntax; check the manual that corresponds to your 
// MySQL server version for the right syntax to use near 
// ”foo bar baz’ at line 1]
// SELECT * FROM wp_posts WHERE post_title = ‘foo bar baz

Xdebug and Remote Debugging

The Xdebug PHP Extension allows for enhanced debugging, function and method tracing, and profiling of PHP applications. This is installed with VVV and can be turned on/off.

With PHPStorm, you can install a browser extension to access Xdebug (or Zend Debugger) from within the IDE.

Rather than manually adding var_dump statements and reloading the page, you can add a breakpoint anywhere in your PHP code, execution will stop and you can see a stack trace, inspect (and modify) the values of all variables and objects or manually evaluate (test) a PHP expression.

With zero-configuration debugging (controlled via cookies and bookmarklets) you don’t need to add ?XDEBUG_SESSION_START to your URLs and you can also debug HTTP post requests.

Server Error Logs

Sometimes neither WordPress or PHP will be able to catch some coding errors. A very good example is, if your code exceeded the maximum allowed run time, we won’t get a PHP error message. Rather, Apache/nginx will pop up something like ‘Internal Server Error’. In case of machine memory issues or any other server resources issues we should go to our log and see what PHP code is causing the issues. We can ask our web hosting provide where the logging is stored, usually it is under logs folder.

PHP Error Logging

PHP has its own level of error reporting to store the issues resolving beyond WordPress. This is extremely useful, especially if something outside of WordPress running and causing some problem.

We can start by configuring our php.ini file to turn on error reporting, and then choosing where to store such messages.
error_reporting = E_ALL | E_STRICT
error_log = /var/log/php_error.log


these above two lines will turn on error reporting, and set the errors to be saved at the specified path.

In order to setup the above lines we will need to log in to our cpanel and go to PHP settings, if you don’t have access to this file(php.ini) you should contact your hosting services and ask them to add the above lines to the php.ini file.

If you want to check if those two lines of code are already on your php.ini you will need to create a php file with this code phpinfo(); and added to your website root directory, then run ( example.com/filename.php ) and then check the error_log option.

PHP Syntax Checker

If our hosting provider deny access to php.ini file, or we can’t access error logs, things can be a bit harder. But, there are many tools to overcome a situation when you get only a blank page with no error message. One quick tool is PHP Code Checker.

PHP_CodeSniffer

PHP_CodeSniffer tokenizes PHP, JavaScript and CSS files and detects violations of a defined set of coding standards.

In PhpStorm, we can configure code style through Settings/Preferences | Editor | Inspections | PHP | Code Sniffer and use one of the many available schemes. There are also various inspections that check our code against the code style. We can add additional code style inspections to PhpStorm using tools like PHP Code Sniffer. PHP Code Sniffer is a PHP5 script that “sniffs” PHP, JavaScript and CSS files to detect violations of a defined coding standard. By default, it will warn us whenever violations are encountered against the PEAR coding standards, but we can also specify other coding standards like PHPCS, PSR1, PSR2, Squiz and Zend. Many popular frameworks like WordPress, Drupal and Symfony2 also come with their code style rules for PHP Code Sniffer. PhpStorm integrates PHP Code Sniffer so that its warnings and errors can be shown in the same way PhpStorm inspections are shown.

Browser Web Inspectors

1. Chrome DevTools for Google Chrome
2. Firebug for Mozilla Firefox
3. F12 developer tools for Internet Explorer
4. Opera Dragonfly for Opera

Notes

Types list of common PHP errors:

A – Notice: This is the least important error message you will see with PHP. It does not necessarily mean something is wrong, but there is possible improvement suggested.

B – Warning: It’s a more severe error, but does not cause script termination.

C – Fatal error: This is a dangerous indicator of something going really wrong, and the script terminated.

Let me know if you have any WordPress debugging tips that you’d like to share, please do so in the comments below!