Debugging in ClassicPress

Having errors in your code is a possibility in the development process of your website/application. However, in the ClassicPress core, there are some starter tools made available to make debugging more fruitful.

These are used in the wp-config.php file that is found in the base directory of your website. Below are some code snippets that can be applied to increase the quality of your code and make timely adjustments.

Example wp-config.php for DebuggingLink to this section

When added to your wp-config.php file, the following code will log all errors, notices, and warnings to a file called debug.log in the wp-content directory by default. There is an option to change the location and name of the error log file.

Equally the code snippet has the ability also to hide the errors, so they do not interrupt page generation.

// 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 development versions of core JS and CSS files (only needed if you are modifying these core files)
define( 'SCRIPT_DEBUG', true );

NOTE: The most appropriate place to insert this code snippet is BEFORE

/* That's all, stop editing! Happy blogging. */

wp-config.php file section for adding custom debugging code
wp-config.php file section for adding custom debugging code

For non-programmers or general users, these options can be used to show detailed information about errors. Here is how the individual pieces work.

WP_DEBUGLink to this section

WP_DEBUG is a PHP constant (a permanent global variable) that can trigger the “debug” mode throughout ClassicPress. It is set to be false by default. One needs to change this to true to enable the display of notices during development. It is strongly recommended that plugin and theme developers use WP_DEBUG in their development environments to catch bugs early enough and disable them on production/live sites.

// This enables debugging.
define( 'WP_DEBUG', true );
// This disables debugging.
define( 'WP_DEBUG', false );

Note: The true and false values in the example are not surrounded by apostrophes (‘) because they are boolean (true/false) values. If you set constants to false, they will be interpreted as true because the quotes make it a string rather than a boolean.

PHP Errors, Warnings, and NoticesLink to this section

Contrary to the default behavior of PHP displaying a white screen of death when application breaking errors are manifested, and showing fatal errors when the feature is enabled on the PHP server, enabling WP_DEBUG will cause all PHP errors, notices and warnings to be displayed.

Notices and warnings are often error messages for things that don’t seem broken. They are easy to fix once the relevant code has been identified, and the resulting code is almost always more bug-resistant and easier to maintain.

Deprecated Functions and ArgumentsLink to this section

As software changes, some functions, methods, and classes are deprecated and removed over time. In most cases, these are functions or function arguments that have not been removed from the core code yet but are slated for deletion in the near future.

Enabling WP_DEBUG will also display notices about deprecated functions and arguments within a ClassicPress site. Deprecation notices often indicate the new function that should be used in place of the deprecated one.

WP_DEBUG_LOGLink to this section

WP_DEBUG_LOG works hand in hand with WP_DEBUG. For WP_DEBUG_LOG to do anything WP_DEBUG must be enabled (true).

This enables all errors also to be saved to a debug.log log file using PHP’s built-in error_log() function. This is most useful if you want to review all notices later or view notices generated off-screen (e.g. during an AJAX request or wp-cron run).

Example of a debug log file in wp-content directory
Example of a debug log file in wp-content directory

When WP_DEBUG_LOG is set totrue, the log is saved to debug.log in the content directory (by default in wp-content/debug.log) within your site’s filesystem. Options are available to set it to a valid file path to have the file saved elsewhere. See an example below of saving to a log directory and bug-errors.log file. These can be of any choice of name.

define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_LOG', '/logs/bug-errors.log' );

WP_DEBUG_DISPLAYLink to this section

WP_DEBUG_DISPLAY is another companion to WP_DEBUG that controls whether debug messages are shown inside the HTML of pages or not. The default is true which shows errors and warnings as they are generated. Setting this to false will hide all errors. This should be used in conjunction with WP_DEBUG_LOG so that errors can be reviewed later. Unlike WP_DEBUG_LOG can turn off WP_DEBUG_DISPLAY independently.

define( 'WP_DEBUG_DISPLAY', false );

SCRIPT_DEBUGLink to this section

This is useful when testing modifications to any built-in .js or .css files. The default is false.

SCRIPT_DEBUG is a related constant that will force ClassicPress to use the “development” versions of core CSS and JavaScript files rather than the minified versions that are normally loaded.

define( 'SCRIPT_DEBUG', true );

SAVEQUERIESLink to this section

The SAVEQUERIES definition saves the database queries to an array, and that array can be displayed to help analyze those queries. The constant defined as true causes each query to be saved, how long that query took to execute, and what function called it.

define( 'SAVEQUERIES', true );

The array is stored in the global $wpdb->queries.

CAUTION: This will have a performance impact on your site, so make sure to turn this off when you aren’t debugging.

Debugging PluginsLink to this section

There are many debugging plugins built for WordPress that work with ClassicPress as well. They show more information about the internals, either for a specific component or general. Here are some examples advisable for all users alike and especially developers:

External ResourcesLink to this section