WordPress Debug mode: Benefits and Pitfalls

Developers know how to best use debug in WordPress and it’s WP_DEBUG constant to get through potential problems and bugs their code might have. But, for regular users, using debug mode can be a very much confusing and can cause more problems than it can help solve.

PHP Errors

Before we go on, here is the short overview of common PHP errors you can find while running any PHP code, including WordPress. Beside these 4, there are some 8 or 9 more error types, most of which you will not see if your PHP is installed properly and is not unstable build.

1. Notices: These errors are trivial and non-critical, and these errors are not displayed by default and they can’t stop code execution (variable not defined yet, for example).
2. Warnings: These are errors that also don’t stop code execution, but they are displayed to user since they point to a code problem that can cause further issues (failed to include file, for example).
3. Fatal Errors: These are critical errors that are displayed and that will also stop code execution. These errors point to a problem that prevents further execution (missing class or function, for example).
4. Parse Errors: These are critical errors that are caused by invalid PHP code (missing semi colons or some other unexpected characters).

WordPress Error Handling

By default WordPress debug mode is disabled. Error handling and display depends on the server settings. In most cases this means that errors will not be displayed (even fatal errors), but they should be logged into file (again, depends on server settings, and it can happen that logging of errors is disabled).

To enable WP debug mode, you need to add WP_DEBUG constant set to TRUE into wp-config.php file. Recently, wp-config.php has definition for this constant included and set to FALSE. So, you need to have this line in your wp-config.php:

define('WP_DEBUG', true);

This will activate error reporting for all types of errors including strict and deprecated errors. There are two more debug constants that can be used if WP_DEBUG is active:

define('WP_DEBUG_DISPLAY', true);
define('WP_DEBUG_LOG', true);

First one will activate (or force) displaying of errors on the screen. Second one will activate logging errors into the file. This file will be debug.txt in your wp-content folder.

Why use WP Debug mode?

By default, if you don’t make changes to WP core files, and you don’t have any plugins or third party themes, active WP debug mode is not going to make any difference and you will see no errors. But, as soon as you start adding plugins and change theme, things will get very, very different.

Main reason for debug mode is to discover errors thrown by the PHP code. If you are working with development installation (your localhost, or server test enviroment), it’s highly recommended to use WP Debug mode. If you write your own plugins or themes, it is essential to use it.

Debug mode is on, what now?

For live environments, WP Debug mode should be used only if you get broken website or no access to it at all. Typical case is that you open your website (any page or only some pages), and instead of content you either get 505 internal server error, or you get blank screen. In most cases, if server is set correctly, errors will be logged in any case and you need to check error logs to find out what the problem is. But, if that is not the case, enable WP Debug mode through wp-config.php, and you will be able to see what the problem is.

When you get the error, that error includes path to the file where the error has happened. In 90% of the cases that is some plugin that is causing problem. But, very often, you will see that error is in some WordPress file in wp-admin or wp-includes folders. If used normally, there should be no errors there, so that points again to a plugin that uses some WP function or class the wrong way. Debugging in that case can be a bit harder, but this will always (well, almost always) help:

1. Disable all plugins.
2. If the problem is still there, theme is causing it, disable it to check.
3. If the theme is not the problem enable plugins one by one.
4. After enabling a plugin try to repeat the operation that caused the error.
5. Once you see the error again, last plugin you activated is at fault.
6. Contact plugin author with the error message and description of what you were trying to do.
7. Wait for the solution… Or
8. Try to fix it yourself, if you are developer or have PHP experience.

Fatal Error: Out of Memory…

Typical errors you will discover like this, include famous PHP is Out of Memory error, that many users don’t understand at all. When you see this error don’t panic: you only need to increase available memory for PHP. In most cases server was configured to use 16M or 32M (standard values), but WordPress with several plugins will need more. So typically, 64M should be enough for anything. If you have more than 40-50 plugins, you could need more than that.

But, this error can also point to a memory leak in some plugins. If you increase memory to 128M or more, and you have 10-15 plugins, a plugin or theme you are using is bad, and it leaks memory most likely due some endless loop in the code or greedy SQL queries that return too many results or for some other reason. Detecting which plugin leaks memory, usually is easy to see. If you look at full error description you will see where the problem occurred, and that will include path to the file, and that path includes the folder name of the plugin (or theme). Again, memory leak is not the same as having just too little memory allocated. Any WP installation should use 64M to 128M, more than that can point to a leak.

Here are several methods for increasing PHP memory:
http://www.dev4press.co….rease-php-available-memory/

And once again, hosting company comes to the stage, because some of them will not allow you to change PHP memory on your own (or at all, yes I have seen few of those), and you have to wait for them to do it. In this case, there is only one solution: change your hosting company. Whatever you are paying for hosting, I am sure that there are at least 5 other companies with same prices that will not limit you in using some basic things like memory allocated to PHP.

Debug Notices

And now Pitfalls

Yes, this all looks great, enable WP Debug mode and you will find the problem. And what if you find to many problems? Finding fatal errors is one thing, but enabling debug mode will open the door for all other error types to surface, even if they are not critical. Take a look at the screenshot on the right, and you will see all sorts of errors: notices, deprecated use and warning. They are not critical, but when debug mode is on, you will see it all, and this can make debug almost impossible.

From experience 95% of all plugins and themes (this can be applied to commercial ones) for WordPress will generate these non critical errors when used. Most developers don’t care about these, and they will leave in the code, and that points to another problem: if they didn’t care to fix these non critical errors and warnings, what else is in their code that can be a real problem? As I said before, development should be done with debug mode on, and these notices will be visible. If they left them in the code, they didn’t see them, and that means they didn’t used debug mode at all. For my part I try to fix every notice and warning I have in my plugins (even most minor one: initializing variables and arrays), and my plugins will not throw such notices (if you find any that I maybe missed, please report it).

So, you activate debug mode, and you find yourself drowning in the pool of notices all over the screen, and you have no idea where to begin. You can go through each plugin code to fix the problems, but that is not really good idea. Waiting for developers to fix own plugins? Well, that can take a long time… After all this, you see that debug mode can be a tricky to use since it can be rendered useless when you have old and not maintained or not very well written plugins in the first place. You can combine display and logging of errors, but for non developers and less experienced users, debug mode can be impossible to use.

There must be some easier way?

How to use debug mode and how to get these error messages displayed without messing with the page content? Thankfully there is a way. PHP provides methods to override default error handlers and to ‘hijack’ their output to hide it or use for some other purpose. You are not going to write own handlers every time, best is to use a plugin that will do that for you. As far as I know, there are 2 free plugins that can do this: Debug Bar and BlackBox Debug Bar. If I were to use any of them, that would be BlackBox and that is the one I can recommend.

Debug Notices with GD Press Tools Pro

But, there is another plugin that can do much, much more to help you with debugging needs. And that is Dev4Press own: GD Press Tools Pro. When debugger is active, with the same errors as on the image with notices above, those errors will be part of debugger window, while the page content will be undisturbed. As you can see, plugin debugger is activated through red bug in the top of the screen (can be repositioned). It can have many tabs with all sorts of data. All notices, warnings and errors will be in this tab,and you can review it from there, no more mess in the page content.

Also, it allows expanding with new tabs, and other plugins or themes can add own data to it. Plugin adds few more debug tools: unserializer for JSON and PHP, fancy print replacement for displaying complex structures and tracker that profiles loading and can be used as a console to display data at any point in the code execution.

Conclusion

WP Debug mode is powerful tool to use, but it’s also not something everyone will be able to use effectively. When your site breaks, you will need debug mode as a first step in determining the problem, and if possible fixing it. At the very least info you get from it, will be useful to developers of the theme or plugin that are causing problems.