Let’s face it, every developer’s nightmare is a buggy site/app. The beautiful and inherently complex system goes all out of whack from a simple, often avoidable error, and this results in a cascade of failures that’ll swoop down and erase several hours of your life in a snap.
If you find yourself in such a situation, here’s a brief, no-nonsense guide to debugging WordPress. Do note – it helps to approach your problem with an analytical, open mind (and some coffee, perhaps).
There’s also a misconception you’ll need to leave at the door. When a WordPress site crashes or does something unexpected, the go-to response is to do the standard test of deactivating all plugins and reactivating them one-by-one, hoping to find the plugin that did the damage. Unfortunately, this approach discounts any underlying issues in a less recent plugin/theme that failed to resurface until an innocuous, well-coded update in a recent plugin or theme triggered it. The plugin test, while helpful in terms of narrowing down the culprits, could let the real issue slide away undetected, which could mean repeating the whole process at a later date.
Now that that’s out of the way, let’s disable browser cache and get to work.
1. Plugins for WordPress Debugging
There are also some WordPress plugins that can help with the debugging. Here is a little info about any plugins you might be considering for that debugging project.
Helpful:
- Query Monitor plugin — Logs detailed information about database queries, functions called (and which plugins called them), memory usage, etc. Can help pinpoint the source of lags (and errors).
- Simply Show Hooks – This one shows all the actions / filter hooks that are currently running on any given page, along with methods and priorities. Can be helpful when nothing else is working.
- Debug Bar – Lets you get useful information about the pages in your website. Analyses and logs queries and templates, along with other useful bits of information.
More hype than help (and must be avoided):
- P3 Plugin Profiler plugin by GoDaddy — Most developers swore by this plugin (me included), because it did what it said on the tin. Back when it was regularly updated, which was 3 years ago. The P3 profiler we have today is incompatible with the latest versions of WordPress (does not support PHP 7).
Now for 9 simple yet powerful tips and techniques for developers when it comes to using WordPress debugging it.
2. WP_DEBUG
This is your best friend. If you’re developing something for WordPress and WP_DEBUG is not enabled, did you even learn the basics, Michael?
WP_DEBUG is the default built-in WordPress debugging mode. It has two subtypes – WP_DEBUG_DISPLAY (which shows errors on-screen) and WP_DEBUG_LOG (which keeps a log of error messages). All three functions can be set to either true or false within wp_config.php
A simple bit of code inserted before /*That’s all, stop editing! Happy Blogging.*/ line within your wp_config.php will enable WordPress to record all errors, warnings, and notices in a file called debug.log.
// Enable WP_DEBUG mode
define( 'WP_DEBUG', true );
// Enable Debug logging to the /wp-content/debug.log file
define( 'WP_DEBUG_LOG', true );
// Disable display of errors and warnings
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );
// Use dev versions of core JS and CSS files (only needed if you are modifying these core files)
define( 'SCRIPT_DEBUG', true );
If you didn’t have it enabled when the error occurred, do it and wait for 20 minutes. The best use of the previously mentioned ‘plugin deactivation and reactivation test’ is to do it after you have enabled WP_DEBUG. Once you reach the setup that led to the error, that’s when you’ll know exactly what went wrong. If it’s a conflict between two components, check on both instead of looking through the latest one and calling it a day. The information you need will be recorded by WP_DEBUG in a in a file at wp-content/debug.log
3. – is_wp_error()
This is another WordPress debugging tool that comes bundled with the whole thing. It lets you check if a result is a WordPress error (type WP_Error). Basically confirms your hypotheses about an erroneous function. If the code fails, it will return a WP_Error object and show an error message.
4 – Test Website and Configuration
Sounds basic, but it’s incredible how many developers simply forget about separating test environments from live websites and end up breaking things in front of people visiting it.
Make sure your test environment is set up to match the live website to the last dot, regardless of where the test one is hosted (locally or on staging server). I’d recommend going with a staging server.
5. WPDB Error Reporting
WordPress Database error reporting is the go-to tool if you’re using wpdb class for dealing with all matters relating to the database. This ensures that your queries execute properly and that any errors show up (with messages) for prompt debugging.
Enable it.
6. Check the Server Error Logs
These can save you hours of poking around in your front-end code and queries if you think of looking them up first.
Messages like ‘internal server error’ can be the result of a script exceeding the maximum runtime, which won’t log or display as a PHP or WordPress error. If something like this does happen, double-check your error log just to ensure that the error wasn’t on your end before ringing up your hosting provider and asking for error logs or some activities that could have caused the error to occur.
7. PHP Errors
There’s a simple way of keeping a log of PHP errors whose notices you may have missed (or the ones that didn’t show up at all). PHP comes with its own error reporting tricks. You can run phpinfo(); and take a look at the error_log method.
You can also configure your php.ini file to enable error reporting and designate a location to store the error log, like so:
error_reporting = E_ALL | E_STRICT
error_log = /var/log/php_error.log
If php.ini is inaccessible (because your hosting provider deems it so), you can still debug the PHP errors causing the white screen of death. Often, the error is from a misspelled function or a missing semicolon. Use PHP Code Checker (or something similar) to find and fix the syntax errors.
If the syntax had no error, it’s time to bring out the big guns. Use an IDE like PHPStorm or Eclipse which will break the code in parts to let you check whether you’re doing something logically incorrect (like overriding a variable you stored previously in a string)
8. Script_debug
This constant forces WordPress to use the extra hardcore ‘developer’ versions of some of the core CSS and JavaScript files in place of compact (minified) versions that end up loading. For serious debugging in cases where you’re testing some modifications to built-in JS or CSS files, this is a must. Simply define the constant as true.
define( 'SCRIPT_DEBUG', true );
Note that core jQuery package does NOT give a crap about this function.
9. SAVEQUERIES
This saves the database queries to an array which you can see in order to analyze them for debugging later on. Information saved (when the constant is defined as true) includes queries, their run times, and the function that called them in the first place, stored in global $wpdb ->queries.
define( 'SAVEQUERIES', true );
Note that keeping this enabled will slow your site significantly, so it’s advised you enable this only when debugging and disable it promptly afterward.
10. doing_it_wrong()
Errors in code usually show up as notices due to a WordPress function doing_it_wrong(). It goes without saying that you should Read. The. Dang. Error. Message.
Why? Because it often contains the detail pointing to reasons that caused the error. Common among these is ‘not using action hooks to load scripts (Javascripts, in particular).’
But seriously, a developer dissing an error message is just not on.
The Upshot
It’s easier said than done, this whole debugging lark. Make sure you don’t assume anything (read the intro again!) and remember that a patch job now is a migraine later. Instead of getting the site back up as soon as possible (followed by going home and never having to think about it), think of discovering errors and streamlining the coding so you can learn.
You might also like – Complete Security Guide for WordPress.
This is a guest post by Pawan Sahu. He is the founder of MarkupTrend. He is a passionate blogger and marketing geek who enjoys writing creative and technical posts (mostly related to WordPress, Web Design, Web Development, Blogging, Marketing, eCommerce etc.).