WordPress Plugins and debug mode

Sometimes when we’re developing a plug-in, it’s easy to forget that we’re not building something that is meant to be standalone. What we’re building is going to exist as part of the WordPress ecosystem and as such it should respect it’s configuration. Simply put, if WordPress is in debug mode, than your plugin should be to.

Once the WP_DEBUG and WP_DEBUG_LOG constants are set to true in wp-config.php, WordPress will start logging any PHP errors to the debug.log file in your wp-content folder. This fantastic for tracking any issue on the PHP side but what about CSS and Javascript ?

With CSS it’s very time consuming to track down a particular rule that is problematic but even if it’s been compressed, you can always to a search in your editor or IDE to find the rule. But wouldn’t it be a huge time saver to have the full, indented CSS file complete with line comments when inspecting an element in the browser?

Javascript on the other hand can be really hard to debug if the only file you can view is minified. Some plugins have their non-minified counterparts included with the rest of the code but that may not help if you’re trying to debug a runtime error.

In this developer’s humble opinion, plugins should handle which version of CSS and JS to load based on the SCRIPT_DEBUG constant setting in wp-config.php. When SCRIPT_DEBUG is set to true, WordPress will load the development versions of core css and javascript so it follows that our plugins ( and themes ) should do the same.

There have been times where I have run into some kind of Javascript issue between the code I was writing, and a plugin. I was never able to resolve the issue because the only files I had to look at were minifed and the only error reference I had was something like:

ReferenceError: c is not defined
TypeError: this.a is not a function

It could have been something as simple as a naming collision ( in my example, not the code above 😀 ) but without seeing the source code, I’ll never know.

My solution in that case was to source a different plugin. That’s not good for the developers who spent the time to create that plugin. Let’s not make the same mistake.

So how do we implent this? It’s pretty simple, just check for the SCRIPT_DEBUG constant and set the path accordingly.

//define the base path to our assets
$basepath = plugin_dir_url( __FILE__ );

//setup the production names for the files
$js_file = 'scripts.min.js';
$css_file = 'styles-compressed.css';

//check for WP_DEBUG constant status
if( defined( 'WP_DEBUG' ) && WP_DEBUG ) {

	//check for SCRIPT_DEBUG constant status
	if( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) {
		$js_file = 'scripts.js';
		$css_file = 'styles-development.css';

//load the files
wp_enqueue_script( 'plugin_scripts', $basepath . '/js/' . $js_file  );
wp_enqueue_style( 'plugin_styles', $basepath . '/css/' . $css_file  );

You may notice in the code above that I am checking for WP_DEBUG before SCRIPT_DEBUG. I realize that I am breaking my own rule of the plugin respecting the WordPress config because there could be a case where WP_DEBUG is false but SCRIPT_DEBUG is true. A valid use case or not, that is possible.

In this case, I believe that the WordPress philosophy of ‘Decisions, not Options’ takes precedence over my rule because there should be no reason to have debug off but be loading the dev versions of CSS and JS – unless someone forgot to remove that line of code before going live.

Leave a Reply