You are bound to encounter bugs and errors in your WordPress journey now and then. It’s inevitable. So, instead of dreading the day it will come, it’s best to be ready for it when it strikes.
The developers at WordPress have a specific tool just for the job. The tool was designed to catch bugs and “snitch” on them. That important tool is no other than the WP_DEBUG tool.
Table of Contents
What is wp_debug?
Wp_debug is a tool that comes with every WordPress core. It identifies the source of an error and helps you better understand it, making it easy to resolve any issue.
Wp_debug is a PHP constant that enables WordPress debugging mode to troubleshoot and fix issues when they arise.
Debugging is ideally meant for local testing and staging environments. The WordPress Codex encourages all WordPress developers to have WP_DEBUG enabled when working on their products. This is because there’s a higher chance of getting errors at this stage.
When wp_debug is enabled, it displays any errors, notices, and warnings it detects. With the information, you can identify and mitigate the error to restore normalcy to any WordPress site in development.
Enabling WP_DEBUG on live WordPress sites is not recommended for security purposes and to maintain a quality user experience.
Enabling WP_DEBUG on live sites will cause PHP errors, notices, and warnings to be publicly displayed, compromising your site and distorting the user’s experience.
However, should a live site experience any issues, enabling debugging mode will help rectify the issue faster.
How do you enable wp_debug for your WordPress Website?
Enabling wp_debug in WordPress is simple. You have to make a minor change to the wp-config.php file in your WordPress backend.
By default, wp_debug is disabled in the WordPress core. In the wp-config.php file, there is a line of code that sets wp_debug mode to false. To enable debugging, you need to edit that line of code and change the wp_debug mode from false to true.
There are several ways to edit the wp-config.php file. You could use an FTP client like FileZilla, your cPanel’s File Manager or Web Editor, or a WordPress plugin.
This guide will show you how to enable debugging in a WordPress site using a staging environment.
A staging environment is perfect for WordPress developers to build WordPress sites from scratch, create WordPress products, test updates and changes before syncing to a live site, and troubleshoot live site errors. It is a private space, so there’s no risk of vulnerability exposure.
In this guide, we will use InstaWP’s staging environment because it is the best staging environment for developers to enable wp_debug mode when working on their WordPress projects. You will discover why shortly.
Enabling WP_Debug via InstaWP Dashboard
That’s the easiest way to enable wp debug for WordPress. Install InstaWP Connect plugin on your site, connect your site to your InstaWP dashboard.
Now, you can enable or disable wp debug, wp debug log or any config setting right from your InstaWP dashboard (Advanced Options > Config Manager)
Enabling WP_Debug via InstaWP In-Built Code Editor
Now, let’s discuss how you can use the InstaWP staging environment to enable wp_debug in WordPress.
From your InstaWP dashboard, Go to Staging.
Hover on the staging site for which you wish to enable wp_debug and click on Code Editor.
Alternatively, you can click the More actions icon (three vertical dots) adjacent to the staging site you want to enable wp_debug. Select Tools > Code Editor.
Select the Open in Web Editor option from the popup, and select the root folder.
Locate the wp-config.php file and double-click on it to open it on the Web Editor.
Search for or scroll to the bottom of the file until you find the following line of code.
define( ‘WP_DEBUG’, false );
Simply change it from false to true.
If you cannot find the code in the WordPress site’s wp-config.php file, you can add it yourself. Simply insert it above the line that says /* That’s all. Stop editing! Happy blogging. */.
Next, click File > Save from the left panel to save the file, and close the Web Editor.
That’s it. You have successfully enabled wp_debug in your WordPress staging site.
Additional wp_debug Constants
There are additional wp_debug constants that can help with advanced debugging options for WordPress. They include:
1. WP_DEBUG_LOG
The WP_DEBUG_LOG debugging constant is a recorder that logs every error, notice, and warning detected by the WP_DEBUG tool. It stores the records in a debug.log file, which can be found in the wp-content folder.
It is recommended that you also enable WP_DEBUG_LOG alongside wp_debug. You can also allow the WP_DEBUG_LOG to be constant in the wp-config.php file. By default, this option is set to false.
You can rewrite it to true:
define( ‘WP_DEBUG_LOG’, true );
2. WP_DEBUG_DISPLAY
The WP_DEBUG_DISPLAY file resolves the issue of errors getting displayed directly on the site. The WP_DEBUG_DISPLAY constant can determine if error messages and warnings are to be shown inside the HTML of the WordPress site pages or hidden.
By default, this option is set to true. You can also turn off the WP_DEBUG_DISPLAY constant in the wp-config.php file by inserting the following piece of code in the wp-config.php file:
define( ‘WP_DEBUG_DISPLAY’, false );
Setting WP_DEBUG_DISPLAY to false will hide all errors. If you must conceal errors, then you must enable WP_DEBUG_LOG. When enabled, the errors are saved inside the debug.log file, making them available for later review.
3. SCRIPT_DEBUG
The SCRIPT_DEBUG constant comes in handy when debugging inbuilt CSS and JavaScript files, which are set to false by default. To enable it, you need to add the following piece of code to the wp-config.php file:
define( ‘SCRIPT_DEBUG’, true );
Enabling SCRIPT_DEBUG will force WordPress to use the “dev” versions of the core CSS and JavaScript files instead of the minified versions set by default.
4. SAVEQUERIES
The SAVEQUERIES constant saves every SQL query made to the WP database into an array (the global $wpdb->queries) that can also be queried and displayed. This allows you to analyze database queries, finding out how long any particular query took to execute and what function called it.
This constant is disabled by default. To enable it, add the following line of code to the wp-config.php file:
define( ‘SAVEQUERIES’, true );
Enabling SAVEQUERIES can impact your WordPress site’s performance and congest its database, so be sure to disable the constant when you are done debugging.
How to Access and Interpret wp_debug Logs
Debug Logs are stored in a debug.log file found in the wp-content directory.
With InstaWP, you can access the Logs from your InstaWP dashboard. Simply hover over the WordPress staging site and click the View Logs option.
You can also access the Logs from the More Actions icon. Go to Tools > View Logs.
In InstaWP, you will be presented with four types of Logs:
- Error Log
- Access Log
- Command Log
- Debug Log
You must select the Debug Log tab to see the PHP errors, notices, and warnings recorded by the wp_debug_log constant. If no logs are present, you will see a “no log found” feedback message.
Alternatively, you can view Logs directly from your browser using the yourdomain.com/wp-content/debug.log path.
Advanced Debugging Techniques
The wp_debug tool can only help identify and resolve basic PHP and WordPress errors. This means it won’t be able to locate and display non-error information that may still need to be debugged, such as site speed, storage usage, cache, junk tables in the database, slow queries, etc. You need advanced debugging techniques for that, including:
Using Debugging Plugins
This technique involves using WordPress debugging plugins for various kinds of debugging and troubleshooting. Several debugging plugins for WordPress can show in-depth debugging information. Two standouts are Query Monitor and Debug Bar.
1. Query Monitor: Query Monitor is a versatile and advanced WordPress debugging tool that can debug database queries, PHP errors, stylesheets and scripts, hooks and actions, Ajax calls, Rest API calls, block editor blocks, user capabilities, etc. and identify poorly performing plugins, themes, functions, or duplicate queries that are affecting your site’s performance.
2. Debug Bar: Debug Bar is a WordPress debugging plugin that monitors and displays database queries, cache size, and information, as well as other helpful debugging information, easily accessible from the debug menu added to the admin bar. When WP_DEBUG is enabled, the Debug Bar tool can track and display PHP warnings and notices, making them easier to find and resolve.
PHP Error Logging
PHP Error logging is the default PHP error background recording feature that reports syntax errors, runtime errors, and fatal errors. When errors are encountered, it displays fatal error warnings or a full white screen of death and logs them to the server’s error_log file.
Custom Debugging Functions
Custom debugging functions are WordPress functions combined with wp_debug and conditional statements to create custom error debugging and handling in WordPress.
WordPress developers use custom debugging functions when developing their products. You can add custom functions in the funtions.php files of your plugin or theme, including child themes and site-specific plugins, or by using a code snippet plugin.
Here are some commonly used custom debugging functions in WordPress:
1. `error_log`: This debugging function allows you to log custom error messages to the server’s error log file.
Example usage: `error_log(‘Custom error message’);
2. `wp_die`: This debugging function terminates the execution of a script and displays the corresponding error message. It can be used to handle fatal errors or display custom error messages.
Example usage: `wp_die(‘Error message’);
3. `var_dump`: This function can display structured information about one or more variables and inspect their contents when debugging.
Example usage: `var_dump($variable);
4. `print_r`: This function is similar to the `var_dump` function, but it displays information about a variable in a more human-readable output.
Example usage: `print_r($array);`.
5. `debug_backtrace`: This function generates a backtrace of function calls in code. It can be used to trace the flow of execution and identify the origin of an error or unexpected behavior.
Example usage: `$backtrace = debug_backtrace();
Debugging Performance Issues in WordPress
Let’s explore how you can debug performance issues in WordPress in terms of speed, storage, and database.
1. Speed Issues
If your site speed is slow, you can enable caching using a caching plugin like WP Rocket, minify CSS and JavaScript using plugins like Autoptimize, and compress and optimize images using plugins like Smush. You can also evaluate themes and plugins, and remove the ones that are slowing down your site or replace them with lightweight alternatives.
2. Storage Issues
Are you having storage issues? Use tools to identify large files and media on your site and reduce them by minifying their codes or compressing them. Seek lightweight alternatives for bulky themes and plugins. And upload and host videos on third-party platforms like YouTube, Vimeo, etc.
3. Database Issues
Clean up the database and optimize database tables regularly, removing unnecessary data like post revisions, spam comments, unused plugins, themes data, etc, using plugins like WP-Optimize. Also, reduce database calls and optimize slow queries using plugins like Query Monitor and Debug Bar.
Debugging Themes and Plugins in WordPress
Now, let’s quickly see how you can debug and resolve issues resulting from themes and plugins, such as conflicts, code-related issues, and problems related to hooks and filters.
1. Conflicts
A conflict error may arise from installing or updating a plugin or theme. You can resolve conflict errors by deactivating other plugins one after the other until the error clears out or switching to a different theme.
2. Code-Related Issues
With wp_debug enabled, you can identify and resolve code-related errors or deprecated functions.
3. Hooks and Filters
You can find helpful information about hooks and filters on your WordPress site using plugins like Query Monitor and Debug Bar. You can use the information to identify issues like incorrect hook and filter usage or conflicts between multiple hooks and filters. You can also cross-reference your codes with the official WordPress documentation on hooks and filters to ensure you use them correctly.
Best Practices for Using wp_debug
Here are some recommended practices for seamless debugging with wp_debug:
- Use a staging environment for all debugging purposes.
- Enable the wp_debug_log constant alongside wp_debug. And ensure to disable them when you are done.
- Do not enable debug mode on a live site. Instead, use plugins like Query Monitor and Debug Bar to monitor your site.
- If you have to enable wp_debug on a live site for any reason, turn off wp_debug_display or put the site on maintenance mode first to protect it.
Conclusion
As a WordPress developer, you must know how to debug and resolve errors. With this information, you should be able to quickly identify various forms of errors and maintain a seamless user experience.
FAQs
1. Will deactivating wp_debug stop PHP Error Logging?
No. PHP error logging is independent of the wp_debug function.
2. Is wp_debug_log and error_log the same?
No. The wp_debug_log constant logs WordPress errors to the debug.log file, while error_log logs standard PHP errors in the server’s log.
3. What should I do if I can’t find wp_debug in my wp-config.php file?
If wp_debug is not found in wp-config.php, you can manually add the code just above the line that says /*. That’s all. Stop editing! Happy blogging. */.
4. How to locate error_log php?
You should be able to locate the error_log file in your site’s root folder or through this path: home/$USERNAME/public_html/error_log.
