WordPress Debugging – Tips, Theory and Tools to use

WordPress is one of the web platforms used the most to create websites (25%+ of the worlds website are created using WordPress). As such, WordPress has a very big community of developers and judging even from my own experience i can say WordPress is one of the most extensible platforms out there.

You can start creating a WordPress website, even a complex WordPress website in matter of days not weeks, you can copy/paste snippets of code made available from other wordpress developers online for free, use those snippets on your project and thats all … here you have just added a new functionality/feature/design, etc to your design.

Its as simple as that with WordPress. This is ofcurse something that helps us as programmers a lot but this copy/pasting thing should also make us worry. Worry because we might be using an old snippet of code, we might be using deprecated functions or even worse code that has vulnerabilities (think of unsanitized user input for example), etc.

In order for us to always be sure we are using “good code” even when we are copy/pasting, we need to debug the website on the dev environment we are working on before putting the website live on the production environment.

The WordPress way to enable debug mode is not hard, like most of the rest of WordPress infact.

In general we just need to add/modify 2-3 lines of code in wp-config.php file.

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'WP_DEBUG_LOG', true );
  • WP_DEBUG set to true activates the Debug mode in wordpress.
  • WP_DEBUG_DISPLAY – false, hides all notices, warnings, errors from being shown on the browser
  • WP_DEBUG_LOG – true, logs all the notices, warnings, errors in debug.log file (you will find this file inside wp-content folder, which means you need to set the right permissions for this folder/file to be writeable)

There are other more advanced ways/methods we can implement that can help us to debug or make our life easier while developing wordpress themes or plugins.

We can for example install the plugin Developer which comes affiliated with a nice bunch of tools/plugin that can help us while debugging. Tools like the Debug Bar (where we can see how much queries are being made in the db, page loading time, page load in ram memory, etc).

Another handy plugin i like to use while creating WordPress themes is What the File. This plugin will add a new item in the frontend user toolbar showing the template parts/views that are being called from WordPress in order to create the current page/view. If you ever wondered which file needs to be modified to change the layout of a certain page then this plugin is the perfect one for you.

Both this plugin and the Developer plugin need the admin bar to be visible in the frontend so if you want to debug using this plugins then you shouldn’t disable showing toolbar on frontend (since this is by default active on every new wordpress install).

Dealing with special cases

WordPress is also known for having a high rate of white screen of death shown (probably because of the vast amount of code created from non professional coders). White screen of death errors are one of those kind of errors that usually dont help very much the programmer for debugging … since the only thing they show on the screen is just a white empty screen.

First thing you need to do in this case normaly is to activate debug mode and save all logs in debug.log file. Reload the page 1-2 times and check what debug.log has to say. Check errors that appear there (normally there should be errors there, very very rarely i have seen websites that dont have programming errors) and try to fix them. First of all though you need to check if any of those errors is causing a set of other errors … so just by resolving that single error you resolve all the rest of the errors showing up. After doing the initial checks, solve as many errors as you can and then do a page reload on the page that gave you the WSOD (white screen of death).

If the page now works without problems that, congrats, you just debugged and resolved the WSOD :)

If still even by resolving all errors showing up on debug.log the WSOD still shows up then start using the divide and conquer method to find what causes the WSOD. Start by deactivating all un-needed plugins, then the lesser needed plugin, then all plugin … until you find the plugin that creates the problem. Repeat this step for as much times at it is needed to find the issue (which means, more plugins … more tests, thats why i always recommend the least number of plugins possible).

If you identify the issue by using the divide and conquer method on plugins, then congrats … if not then do a simple check on the theme. Try changing your active them with another theme, lets say 1 of the wordpress default themes for example. If the WSOD does not appear then there is probably something wrong with your theme … if the problem does appear even on the other theme and all the plugins are disabled, then remains 1 place left to check, WP core itself.

Delete all wp core files/folders, except, wp-config, wp-content folder and do a fresh install of wordpress. Open same page on your browser. Now the problem should have been solved (well in theory the problem should have been solved a long time ago … but i only took an extreme case scenario where you have to go all the way doing debug after debug) … so congrats :)

Other resources you might find interesting about this topic: