Tag: wordpress

Just like Ross I’ve had to dance around the current state of WordPress themes and find the docs to be bad with lots of edge cases once you start looking through Github issues and Stack Exchange posts…and god knows what else.

When I look at the current state of building WordPress themes I don’t think I ever would have started with WordPress if this is where I had to start. It’s so much more difficult now and did I mention the docs suck.

For a long time, I manually changed the $version parameter when I was using wp_enqueue_script or wp_enqueue_style. At some point, I’d forget to make the change though and then some caching plugin would have issues because it wouldn’t realize that the script/style had been updated and I’d waste time wondering why I was seeing a cached version of scripts.

To combat this I started adding the version number of the plugin or theme as the $version argument in wp_enqueue_script so let’s look at how I do that.

get_file_data

My first stab at solving this problem was while writing a plugin and dealing with admin scripts and styles only. If this is your sole use case then get_plugin_data( __FILE__ ) will get you the information you need.

add_action( 'admin_enqueue_scripts', 'admin_enqueue' );

function admin_enqueue(){

	$plugin_data = get_plugin_data( __FILE__ );
	$version = $plugin_data['Version'];

	wp_enqueue_script( 'my_script_name', plugins_url( '/plugin-folder/path-to/script.js' ), array( 'jquery'), esc_attr( $version ), true );

}

Unfortunately, if you want a method that works when you’re adding scripts to the frontend and to the admin area of WordPress you’re going to be let down by get_plugin_data as this function is only defined in the WordPress admin area.

To get reliable access to this data anytime you want to add $version to your enqueued scripts you need to use get_file_data . This is available on both the frontend and the admin area in WordPress.

add_action( 'wp_enqueue_scripts', 'frontend_enqueue' );

function frontend_enqueue(){

	$plugin_data = get_file_data( __FILE__, [
		'Version' => 'Version',
	], 'plugin' );
	$version = $plugin_data['Version'];

	wp_enqueue_script( 'my_script_name', plugins_url( '/plugin-folder/path-to/script.js' ), array( 'jquery'), esc_attr( $version ), true );

}

get_file_data reads the first 8kb of a file for metadata embedded in the file. Then you can define the metadata values you want to be passed through in an array. The final declaration of plugin above will translate into a filter that will be named extra_plugin_headers that you could modify if needed.

Caveats

The biggest caveat to using get_file_contents is that you need to be doing your enqueue work in the main plugin file that has the standard WordPress plugin headers as that is what the plugin is reading.

That works for me, and using get_file_contents I can use a standard snippet to enqueue scripts and make sure I have the version number appended all the time.

One of the biggest tips I’d give to any new programmers is that your code should gracefully degrade. Let’s look at a simplified example in a recent WordPress project I was working on.

In a plugin there was a line similar to what you’d see below that includes a file from a theme.

require_once plugin_dir_path(__FILE__) . '../../themes/<theme-name>/lib/assets.php';

In our default install this isn’t a problem because the theme exists and assets.php also exists. So the file is included and we have no issues.

But this week I’ve been building a system to check which theme is active and force activate a specific theme for a site if it’s not active. It also lets us know if the theme isn’t present so it can’t be activated. While testing this I renamed the theme folder to have it deactivate itself and then the line above breaks.

This is where we should fail gracefully and check if we have the file in the expected location before we try and include it. Further, outside of standard PHP notices, there is no reporting at any level about the issue.

I’ve added a task to fix this, but this is what the fix would look like in pseudo-code if you’re curious.

• Check if the theme exists with wp_get_themes()[^1]
• If theme exists, check if the file in question exists
• If either of the above fail, let someone know about it in your reporting system so that the issue can be resolved.

In the case above, I’d send a message to the our dev slack channel along with some information about what the fix should be and if a developer should be involved. We have a number of errors that can be handled by support staff without involving a developer because of the tooling we’ve already built.

In general, before you try to use some custom functionality, make sure it exists and then deal with the case if it doesn’t exist so your whole site doesn’t die.

Yes we should not even have a plugin/theme dependency like this. That is a different topic to address and one of the many items of technical debt we need to dig out of.

[^1]: This can be an expensive function so be clear about it’s cost and that the cost of the function increases as you add more themes.