Lessons for custom WordPress plugins and themes

I was reminded of this WordPress issue that has bitten me twice now, so it’s definitely time to document it.

Short version: If you write a custom WordPress theme or plugin only for your site, you probably want to include Update URI: false in the header comment. This stops WordPress from checking for updates against the official directories and potentially overwriting your code. Read more in the official blog post.

Longer version: When WordPress checks for updates to plugins and themes, it is basically checking the name and the version number against the official directories. If there is a newer version, then it prompts you to install the update. This generally works fine until you consider more generically-named things. For example, years ago for a work client, we set up a member directory plugin that we very aptly named... “member directory.” Later, the client saw there was a new version available so clicked “update” and suddenly the directory stopped working.

Yep, the WordPress update system didn’t really have a way to differentiate generically-named plugins. The update process replaced our custom plugin with the one in the official plugin list. We have backups so it was an easy fix, but it was baffling to find out that could even happen. I tracked down a WordPress issue discussing it and chimed in with my +1.

Thankfully there was an update in version 5.8, but it still requires developers to opt-out by adding a line to the header comment. We were bitten by this again today with a third-party plugin called “custom post types.” No, not that one.

Lessons for custom plugins and themes:

• Use Update URI: false in the header comment to disable update checks
• Optional, but a good practice: use more specific names. Prefixing the name with the client/organization goes a long way to making unique names.