When running a WordPress site, it’s important to understand how PHP’s error messaging works. Even if you are not a developer yourself, you need to know how to properly set up and run a site and how to know what’s important for messaging so that you can get the correct information back to developers. This article will cover the basics of PHP’s error messaging and WP’s debug mode.
PHP Error Messaging
I’m using the term “error message” collectively since that’s what most people call it (whether they are developers or not). But the fact is that PHP has different levels of messaging when things are not right and not all of those messages are “errors.”
PHP basically has three levels of messages:
Errors are actual PHP errors. Something broke in the processing of a script and thus continuation of code execution was halted. This is an actual error.
Warnings and notices are something different and are not technically “errors.” These are classifications that indicate something is not right with the script being executed, but it’s not something that halts code execution. Execution continues but it’s telling you things you probably should fix in the syntax of the script.
The fact is that for your production site (the main site you use and run), you should NEVER have PHP set to display all messages. If you have messaging turned on at all, it should only be errors. Personally, I prefer all error messaging turned off.
The error messaging setting is generally handled in the php.ini file. This is a directive file for Apache (or whatever your webserver runs) to tell it what settings to enable and disable. For many of you, you will not have access to this. Any changes to your PHP settings will likely need to be done through your host.
If you don’t know what you’re doing – ask your host. It’s OK to not know HOW to do something. What is more important is WHAT and WHY. In this case, that is to not degrade the user experience and display unnecessary scripting messages to the user.
WP Debug Mode
“But if I turn off error messaging, how will I be able to know things need fixing and how to fix them?”
I’m glad you asked!
PHP has a nice little function that turns on messaging by script rather than by settings (as mentioned about the php.ini directive above). So you can set PHP to supress messages in the settings but turn them on via an actual PHP script (essentially using your application to turn it on when needed).
To make this even more simple, WP has made this available in the wp-config.php file. wp-config is the file that holds your primary WP configuration. Most you know this file has your db username and password, db location, and the location of your site. But it contains a number of other settings, including what is known as “WP Debug Mode”.
Debug mode turns on all PHP messaging. You should never run your production site in debug mode for the same reason that we don’t want to display messages discussed above. Debug mode can (and should) be used for two purposes:
- Running your development site
- There is no second reason, but I’m going to add “checking what might be wrong with a production site” since some people use their production site for development (a topic for another time)
Debug mode is intended for your development site so that you can see ALL errors, warnings, and notices in PHP. This will tell you if things are working or not.
When running in debug mode, please do not confuse warnings and notices for errors. It may be worth notifying a plugin or theme developer about a warning or a notice so that they can clean up their code, but remember the difference. These are not necessarily “bugs”. And they may be things specific to how you have your site running – specific to plugin compatibility, PHP version, etc.
If you have something that is not working – for example, script execution of a plugin doesn’t appear to complete – then you can turn on debug mode (if it is off) to see if you are getting PHP errors. Remember at the beginning it was mentioned that an error halts execution. So if you are not getting all the page output that is expected, there may be a PHP error. Turning on debug mode will allow you to find out if this in fact a PHP error and what that is. That information is necessary to figure out what needs to be done to fix it.
How to Enable WP Debug Mode
To enable debug mode, open your wp-config.php file. Near the end, you will see WP_DEBUG defined as a constant.
By default, WP_DEBUG’s value will be false:
define( 'WP_DEBUG', false );
To enable debug mode, change this value to true:
define( 'WP_DEBUG', true );
That’s all you need to do to turn on debug mode.
If this is a production site, make sure you turn it off when you are done. Do not leave a production site in debug mode.
For documentation on WP_DEBUG, see this codex article.
Simply turning on WP_DEBUG will not necessarily log your errors; it merely outputs them to the screen. In some situations, you may need errors to be written to the log. This would be necessary if the script isn’t one where there is user viewable output (such as a background process) or if you are on a production site where having errors displayed on the site might be discouraged.
To enable logging, use the constant WP_DEBUG_LOG set to true. This is the same as setting the debug constant – it’s just another constant.
define( 'WP_DEBUG_LOG', true );
When enabled, WP_DEBUG_LOG will allow errors to be written to the debug.log file, which you will generally find in your /wp-content/ folder.
If you are running on a production site and need to log errors but don’t want errors on the screen, use the additional constant WP_DEBUG_DISPLAY set to false.
define( 'WP_DEBUG_DISPLAY', false );
What if you don’t have access to wp-config.php? Sometimes, if you’re doing client work or similar, you might have access to the WP admin panel, but not direct access to the wp-config.php file where you would need to set these constants. There’s a utility function on the code snippet site wpbitz.com that will allow you to do all of the above things with a simple code snippet.