More informative message when plugin installs fail

[DavidAnderson]

I am an author for a very popular plugin. About once a week, I get a support request from someone who tried to update their plugin via installing a new version in the WP dashboard, *without de-installing the existing version first*.

I wonder how many man hours in the WordPress world are lost to telling people "you need to de-install the existing version of the plugin first"! Too many for my liking.

The existing message, "Destination folder already exists. /home/mywebsite/wp-content/plugins/my-plugin/" is not clear enough for many non-expert users to deduce the cause. Non-expert users don't know the structure of the WordPress filesystem, and won't realise that this simply means "you've already got that plugin, and we don't allow this." And crucially, neither does it indicate to the non-expert user *how to solve the problem*.

The attached patch makes the cause and the solution clearer, and hopefully should help a lot of plugin authors to spend more time coding and less explaining WP's internals! :-)

[DavidAnderson]

Patch to provide further information and indicate the solution

[jdgrimes]

Related: #9757

[adamsilverstein]

slight cleanup

[adamsilverstein]

Replying to DavidAnderson:

David,

Thanks for your patch! It makes sense to provide better error messages, I can only imagine your frustration support end users of your plugin with the same issue over and over again.

I refreshed your patch in 27196.diff​:

• added spacing throughout as per the ​WordPress PHP Coding standards

• adjusted error message language to make tense match other messages
• removed the @ in front of in_array (what output are we suppressing here?)

Otherwise looks good to me, although I haven't tested directly to make sure it works as expected. Have you done that? A screencast or screenshots would be helpful here (showing the error message, before and after the patch), even better would be a unit test if its even possible to simulate this type of issue with the unit testing framework. (I'm not really sure how to approach that)

[DavidAnderson]

Hi,

Yes, I've tested it. I'll attach a screenshot of the results afterwards. (The only difference before the patch is that the "You cannot install..." message is not there).

David

[DavidAnderson]

Screenshot of results with patch

[mindctrl]

What happens if the plugin contains an uninstall.php file, the message tells the user to delete the plugin, and they lose all their plugin-related data?

[DavidAnderson]

The uninstall function in the WordPress dashboard already warns you if you're about to delete the plugin's data. So, that is not hidden from the user.

Of course, some users will click anything, and accept no responsibility for doing so. My patch is about reducing the percentages, not eliminating them entirely (that's impossible).

[mindctrl]

That's true. But, given the two support scenarios, I'd much rather deal with telling people how to properly upgrade the plugin versus dealing with them after WordPress told them to do something that deleted their data. As you noted, some users will click anything.

Dealing with one user who loses data, no matter whose responsibility, is like dealing with 50+ people who only need to be pointed to a page to follow a couple lines of instructions.

What about instead of telling them to delete the installed version and risking data loss, either:

• Tell them the plugin already exists, and link to the updates page to check for updates.
• Point them to a Codex page that gives more proper instructions

[DavidAnderson]

Let's not over-complicate this. The patch merely clarifies an existing message. It does not attempt to change any existing practices.

[SergeyBiryukov]

Replying to mindctrl:

What about instead of telling them to delete the installed version and risking data loss, either:

• Tell them the plugin already exists, and link to the updates page to check for updates.
• Point them to a Codex page that gives more proper instructions

The first option sounds good to me.

[DavidAnderson]

I'm attaching a new patch which changes the message to suggest the two possibilities to the user.

Note that it would often be wrong and potentially result in *more* support requests if it only gave the advice to visit the dashboard plugin updates page. Not all people trying to install plugins manually are doing so as an alternative to an automatic update: 1) Not all plugins have automatic updates (I know multiple commercials ones in this category), or 2) The developer might have sent the user a version to try manually (e.g. bugfix), or 3) The user might be trying to manually install a "trunk" version they obtained from wordpress.org. There are probably other possibilities too.

[DavidAnderson]

Updated patch

[helen]

Unable to install over existing folder - you probably need either to delete the installed version first, or to perform your update using the dashboard\'s updates page. doesn't feel right. "Probably" is not exactly a reassuring word.

How does one end up here in the first place? The plugin installer UI doesn't allow me to install an existing plugin, it tells me to update it. Are you referring to the upload part of the installer?

[DavidAnderson]

Hi Helen,

To reproduce, do this:

1) Install a plugin, any plugin, by any mechanism.

2) Then try to install a plugin with the same slug, via the built-in dashboard "Upload" page (Plugins -> Add New -> Upload).

Result: message: "Destination folder already exists. /home/mywebsite/wp-content/plugins/my-plugin/"

Users don't understand this message. They then file support requests with the plugin author. (Which is what motivated me to get it fixed - responding to the same request over and over gets dull quickly!).

Usually the user is attempting to update the plugin. The plugin *might* have an automatic update available, or might not (some 3rd party plugins don't have automatic updaters; or, the user might have been sent, or obtained themselves, a development version to try out, to fix a bug).

The patch adds a new message to give them some more information as to why the operation failed.

How about this for a message?

"You are trying to install a plugin that already exists. This cannot be done - you need either to de-install the existing plugin first, or to use the update mechanism instead."

???

[helen]

Okay, I think you're saying "yes, I'm referring to the upload part of the plugin installer" :)

"De-install" is not a word, and the sentence structure is weird. I'm punting this - we can move it back to 3.9 if somebody comes up with some awesome words in the next couple days.

[DavidAnderson]

Hi Helen,

De-install is in the Oxford dictionary. But not in Meriam Webster, I note. However, it's our (the Brits) language, so Oxford wins.... Just kidding. ;-)

As a minimal suggestion, how about, "You are trying to install a plugin that is already installed. This cannot be done."

That gets to the point, and allows the user to know why the operation did not work, and avoids any ambiguous advice on how to resolve it.

[hardeepasrani]

How about we add "Make sure to delete the existing install first." in it?

[mindctrl]

Replying to DavidAnderson:

Users don't understand this message. They then file support requests with the plugin author. (Which is what motivated me to get it fixed - responding to the same request over and over gets dull quickly!).

Usually the user is attempting to update the plugin. The plugin *might* have an automatic update available, or might not (some 3rd party plugins don't have automatic updaters; or, the user might have been sent, or obtained themselves, a development version to try out, to fix a bug).

I think in every case you mentioned here, the onus is on you to supply the customer with accurate instructions applicable to the situation. There are several well-tested solutions for automatic upgrade integration in plugins not hosted in the .org repo, and people installing development versions very well could have to follow special instructions from the developer. A generic message telling people to simply uninstall their plugin when there are unknown factors just doesn't feel right.

But, I do think the text could be improved. I wonder if it makes sense to allow developers to filter that text to provide instructions for their context?

[DavidAnderson]

A generic message telling people to simply uninstall their plugin when there are unknown factors just doesn't feel right.

@mindctrl: see comment 16 for the current suggestion for a message, which does not suggest any cause of action, but merely clarifies the cause of the current (confusing) message which WordPress gives.

And believe me, we supply exhaustive instructions for everything. Some people never read instructions. But that's beside the point of this bug. The point of this bug is simply that WordPress provides an error message that is technical and confusing, and people don't know what it means. The suggested message addresses that.

[jdgrimes]

How about this text:

The plugin folder "/my-plugin" already exists. If you are trying to update a plugin, you need to delete or rename the old plugin folder first. If you are trying to install a new plugin, rename the zip file and try again.

[DavidAnderson]

Renaming the zip file won't result in a different outcome, will it? The clash is with the folder name inside the zip file.

[jdgrimes]

Replying to DavidAnderson:

Renaming the zip file won't result in a different outcome, will it? The clash is with the folder name inside the zip file.

If I remember correctly, the folder name is based on the name of the zip file, but maybe that isn't true in all cases.

[hardeepasrani]

Nah, renaming the .zip file won't do any good. User would have to rename the folder itself. Can we add a help panel (just like we have at many places) to the top explaining what to do in this position and add a text which says, "Look at the help panel for more information."

[DavidAnderson]

@jdgrimes: Assuming you're right, I think the advice is probably likely to cause as much trouble as good: if the user already has a plugin with the same slug active, then it's *probably* another version of the same plugin. Advising them of how they can (probably) install two versions of the same plugin at the same time is unlikely to be a great idea.

[jdgrimes]

Replying to DavidAnderson:

@jdgrimes: Assuming you're right, I think the advice is probably likely to cause as much trouble as good: if the user already has a plugin with the same slug active, then it's *probably* another version of the same plugin. Advising them of how they can (probably) install two versions of the same plugin at the same time is unlikely to be a great idea.

Yeah, it looks like I'm wrong, I just tried it.

So I'd suggest just something like this:

The plugin folder "/my-plugin" already exists. If you are trying to update a plugin, you need to delete the old plugin folder first.

[DrewAPicture]

The proposed string changes in 27196.2.diff​ could stand for some feedback from the wordsmiths on the docs team. Side note: the apostrophe should be encoded here as ’ instead of escaped.

[jazzs3quence]

Replying to jdgrimes:

So I'd suggest just something like this:

The plugin folder "/my-plugin" already exists. If you are trying to update a plugin, you need to delete the old plugin folder first.

Since the "Destination folder exists" message still displays, there's no reason for the first part ("plugin folder my-plugin already exists"). But I agree that the wording in the patch is weird. Adding a different idea...patch and screenshot coming.

[jazzs3quence]

screenshot of 27196.3

[DavidAnderson]

Looks good to me.

[DrewAPicture]

Some notes:

• Following the tone and structure of the first two strings, "Unpacking the package ..." and "Installing the plugin ...", the third string should be "The plugin folder already exists."
• The fourth string seems a little wordier than it needs to be, leading to an unclear message: Should I do this one thing or this other thing? Or both?
• Maybe something like this instead: "Visit the Updates screen to update existing plugins, or delete the existing plugin first before attempting to reinstall."

[jazzs3quence]

Good points, both. Changing the strings for my next patch.

[DrewAPicture]

After re-reading everything here I'm actually leaning toward wontfix.

If the consensus is still that "Destination folder" is a little too sterile, I'm all for reworking just that single string.

However, keep in mind that this string is used for both plugin and theme installs, so in order to say "plugin folder" here, we'd have to introduce a second string for themes, plus differentiate between the types when tossing the error, etc. It's an awful lot of changes just to clarify "destination folder".

String changes aside, I'd love to see an improved workflow here at some point in the future. Rather than saying, "you can't do that, here are some vague directions," it would be interesting to explore the idea of the "manual upgrade" or "manual reinstall" a la #13953.

[DrewAPicture]

I'm going to go with maybelater here.

If your users are attempting to "install a new version" of your plugin over the top of the old version, I"m guessing that:
a) You aren't leveraging the ability to route your plugin updates through the WordPress admin
b) Your plugin is hosted elsewhere than the WP.org repository

That said, I'm not sure an update here is necessary without other improvements to the installation workflow first.

[DavidAnderson]

a) No, I am providing in-dashboard updates. But some users just like to try uploading a new version manually, for whatever reason. Or they got sent a version to test out via email.

Anyway, the ticket wasn't meant to be about that - but about simply providing a much clearer error message than the existing one for non-expert users.

I think this ticket has been over-complicated. We have a very unclear error message (based on the user feedback I've seen); the ticket proposes only one thing: provide a clearer one. I think either that should be done, or the ticket closed permanently - I can't see what good will be served by marking it as maybelater. The ticket has had lots of comments from lots of different people, and if we can't get a clearer message after all this discussion, then we probably never will.

[DavidAnderson]

Greetings, past self! 4 more years of people baffled by WordPress's tech-speak in this message passed before I realised I could help them without a fix in core.... in case anybody else finds this useful, here's how to do it (change the slug and message for your case, of course)...

<?php
add_filter('upgrader_source_selection', 'my_upgrader_source_selection', 10, 4);
function my_upgrader_source_selection($source, $remote_source, $upgrader_object, $hook_extra = array()) {

        if (!is_array($hook_extra) || empty($hook_extra['type']) || 'plugin' !== $hook_extra['type'] || empty($hook_extra['action']) || 'install' !== $hook_extra['action'] || empty($source) || 'updraftplus' !== basename(untrailingslashit($source)) || !class_exists('ReflectionObject')) return $source;
        
        $reflect = new ReflectionObject($upgrader_object);
        
        $properties = $reflect->getProperty('strings');
        
        if (!$properties::IS_PUBLIC || !is_array($upgrader_object->strings) || empty($upgrader_object->strings['folder_exists'])) return $source;

        $upgrader_object->strings['folder_exists'] .= ' '.__('A version of UpdraftPlus is already installed. WordPress will only allow you to install your new version after first de-installing the existing one. That is safe - all your settings and backups will be retained. So, go to the "Plugins" page, de-activate and de-install UpdraftPlus, and then try again.', 'updraftplus');

        return $source;

}