Despite all my efforts to guarantee you all a smooth upgrade from Seamless Donations 3.3 to 4.0, things didn’t quite work out as planned. If you are experiencing upgrade problems, white screen of death, or hangs while trying to update the plugin, here’s what you need to do.

If you haven’t tried updating yet

If you haven’t tried updating yet, here’s the set of steps you should take. First, go to your Plugins page and deactivate Seamless Donations. Then delete the plugin. Refresh your plugins page (this is very important, make sure to refresh). Now you can Add New and bring Seamless Donations 4.0 onto your site.

If you tried updating and are experiencing problems

If you are no longer able to deactivate the plugin from the Plugins dashboard, you will need to remove the seamless-donations folder from your wp-content/plugins folder using FTP or your file manager on your server.

Once you’ve done that, go back to the plugins page in WordPress. You will probably see an error message like this: “The plugin seamless-donations/dgx-donate.php has been deactivated due to an error: Plugin file does not exist.” This is good. This is what you want to see. If you don’t see this message, make sure you refresh the plugins page. Again, it’s very important that you refresh the page once you’ve removed the seamless-donations folder.

Now, go ahead and Add New and download.

Techie discussion of what’s going on

Every plugin has a plugin comment block in one main file that defines the plugin. In the case of Seamless Donations 3.3, the plugin comment block was in a file called dgx-donate.php, located in the seamless-donations directory.

When I first adopted Seamless Donations and looked into best-practices, I read somewhere (wish I could find that link) that it’s best to have the main plugin file and the plugin folder use the same name. So I created seamless-donations.php and moved the plugin comment block into that file. I then moved dgx-donate.php into a legacy folder with other older code.

Seemed like a good idea at the time.

As it turns out, when WordPress activates a plugin, it records the folder/main-file pair in the active_plugins option in the wp_options table. That means that, for many of you, WordPress recorded seamless-donations/dgx-donate.php as the active plugin information. When the plugin updated, the files in the seamless-donations folder changed, and there was no longer a seamless-donations/dgx-donate.php file where WordPress expected it.

I didn’t realize that’s how it worked. I thought WordPress scanned the plugins folder directly. Not so much.

In order to make the update work, the┬áseamless-donations/dgx-donate.php record has to be removed from the active_plugins option. The easy way to do that is simply deactivate the plugin. If you tried to install the new Seamless Donations 4.0 and couldn’t do the update, the odds are that the old dgx-donate.php file is still listed in the active_plugins option.

That’s why deleting the folder and refreshing the plugins page is important. If you delete the folder and then refresh the page, WordPress will notice the folder isn’t there and then deactivate the plugin. But WordPress will only do this if you go to the plugins page and force it to check for the plugin files, which is why you need to go to that page and refresh.

Once you’ve done that, the active_plugins option will no longer have the old data and you’re safe to download the new plugin.

I am so sorry, folks. I really tried to make this a seamless upgrade.


P.S. I did think about just moving everything back into dgx-donate.php, but very helpful advice from the folks said we were all better off leaving the change as is, because a double-change could really screw things up even more. Sigh.