How to prevent unwanted theme updates from WordPress.org

Have you ever created a custom theme, and seen an unexpected update notice?

Ever click that unexpected update notice, and find that your custom theme has been replaced by a totally different theme?

If you haven’t run into this situation before, it may sound implausible. But it isn’t.

If your theme happens to have the same slug and lower version number as one hosted on WordPress.org, this exact scenario is totally possible. But not to worry, I’ll show you how to prevent it from happening.

Simulating an unwanted update notice

The following two conditions need to be met:

Your proprietary theme slug must match one on WordPress.org
Your proprietary theme version must be lower than the one on WordPress.org

Let’s say my proprietary theme has a slug of “bravado” (wp-content/themes/bravado/) and the version in the stylesheet is set at 1.0.0.

But there’s also a theme called Bravado hosted in the WordPress.org theme directory (https://wordpress.org/themes/bravado/) and its version number is 1.0.1.

The slug matches. The version number is lower. Both conditions are true. Update notice for a totally different theme appears.

Preventing an unwanted update notice

There are several techniques to prevent an unwanted update notice from appearing. We’ll start with the most straightforward and obvious techniques, and conclude with the most effective “don’t worry about it” technique.

Use a weird slug

Instead of wp-content/themes/bravado/, I could use wp-content/themes/hi-this-theme-is-not-on-wordpress-org-bravado/, and I’d only have to worry about it if somebody else used that very un-SEO-friendly theme slug for their WordPress.org-hosted theme.

Keep in mind if you change the slug of an active theme, WordPress will be confused and you’ll need to reactivate it.

Also keep in mind that the WordPress.org theme update system goes by the slug, not the name. The theme name is what’s displayed on Appearance → Themes. The slug is not so apparent.

That means, your slug can be super weird, and your clients probably won’t even notice.

Use a weirdly high version number

While I don’t have data to back it up, I’d guess most themes hosted on WordPress.org are versioned at 1.x.x.

That means, if your proprietary theme was versioned at something wild like 99.1.52, you would probably never have to worry about a higher-versioned-same-slugged theme causing an unwanted update notice.

Cut off the source

If you’re the type of person who always thinks of the worst case scenario, like let’s say…an unscrupulous competitor using the same slug and an even higher version number as your proprietary theme framework in an attempt to sabotage a bunch of your client sites, you might want a more bulletproof solution.

Rest assured, there is one.

Plop the following function (remembering to update prefix_ with your own), and never worry about unwanted theme updates again:


/**
 * Disable requests to wp.org repository for this theme.
 *
 * @since 1.0.0
 */
function prefix_disable_wporg_request( $r, $url ) {

	// If it's not a theme update request, bail.
	if ( 0 !== strpos( $url, 'https://api.wordpress.org/themes/update-check/1.1/' ) ) {
			return $r;
		}

		// Decode the JSON response
		$themes = json_decode( $r['body']['themes'] );

		// Remove the active parent and child themes from the check
		$parent = get_option( 'template' );
		$child = get_option( 'stylesheet' );
		unset( $themes->themes->$parent );
		unset( $themes->themes->$child );

		// Encode the updated JSON response
		$r['body']['themes'] = json_encode( $themes );

		return $r;
}
add_filter( 'http_request_args', array( $this, 'prefix_disable_wporg_request' ), 5, 2 );

Hat tip to Devin and Jared.

Don’t yell at WordPress.org about this

If you’ve ever had a theme replaced via an accidental, unwanted WordPress.org update, I empathize with your frustration.

If the mere revelation that this is even possible makes you angry, that’s fair.

I know it’s tempting to demand WordPress.org do something about this, but before you do, I’ll let you in on a little secret.

They know. You don’t need to remind them.

WordPress.org is a beast of a website. Merely keeping it online and running smoothly is a herculean feat, and something you, as a WordPress developer, should be very thankful for.

Yelling at them is not the answer.

The answer is to be aware of the issue and defend against it, using one or more of the techniques outlined above.

Preventing unwanted theme updates from WordPress.org