Avoiding plugin name collisions with WP updater

Question

I have a client who has a WordPress site that uses a custom plugin written for them by another developer. Recently, they ran the WordPress updater and one of the updates clobbered that custom plugin and replaced it with a plugin from the Plugin Repository that happened to have the same name.

I'm trying to figure out exactly what needs to change in order to avoid this from happening again in the future. The plugin in question didn't have any particularly unique identifier in the directory/main file names; imagine it's like this:

foo/foo.php

So if there's already a "Foo" plugin in the repository, it's understandable why WP would confuse the two.

My understanding in the past had been that the way to avoid this was by putting a unique identifier in those names, like:

client-foo/client-foo.php

Adding the "client-" bit, I thought, was the way to reduce the odds of a collision by making the plugin specific to the one WordPress site that was running it.

However, even after renaming the files, I found the updater was still confusing the plugin with the "foo" plugin in the repository.

Next I tried changing the "Name" field in the plugin metadata header, from

Plugin Name: Foo

to

Plugin Name: Foo (Client)

And this seemed to remove the collision; the updater no longer flagged it as matching the public plugin.

So now I'm confused. Is it really the case that the only thing the updater checks to avoid collisions is the Plugin Name metadata field? That seems really brittle compared to the way I had thought it was doing it (comparing filenames), at least to me.

Anyway, I've been unable to find a definitive word on what information the updater uses to make this check, and while I did find this previously asked question the answer thread doesn't ever come out and say "this is how it works." So I thought I'd ask.

Answer 1

The way WordPress uses to find a plugin in repository is not public AFAIK.

As per Otto answer in question you linked it involves plugin url header alongside plugin name.

BTW, remove the plugin from the list of plugin to update is the best way to ensure this problem is not going to happen again: once the matching method is not public you can't know if it is going to change in future.

Answer 2

Since the logic used for updates from official repositories is both fuzzy and exact details are kept secret — it's not possible to reliably dodge it by merely manipulating details.

The only reliably practice at the moment is to filter out data from the set sent for update check. Even that is highly inconvenient and needs to be performed on HTTP API request level. One of the related challenges is that if plugin excludes itself it can't do it when inactive and still risks being destroyed by update in that case.

Personally I wrote a small Update Blocker helper for this. In more serious sites I would recommend to kill updates altogether and manage site with Composer.

While WP project generally agrees that this is an issue now (which took literally years) the ticket proposing header opt-out flag has been stalled for a while now, requiring updates on WordPress org site. See ticket #32101 in core trac.