After spending so much time trying to get this to work myself, I felt that I had to write this post to help clarify much of the mystery behind Automatic Background Updates in WordPress for others. Hopefully it helps someone else out there.

This post, Part 1, will cover the basics of having your plugin automatically detect a new version when your plugin is not hosted within the wordpress.org repository. In Part 2, I will discuss the methods you can use to have WordPress actually upgrade your plugin for you now that it has detected that there is a new version to be installed.

First some background. At my 9-to-5, we have an internally-developed plugin which we use for a number of maintenance tasks. This plugin is installed onto every WordPress website which we host (which at the time of writing is 97 websites) and obviously we do not want to have to manually push updates to each of these sites individually. Since it is a proprietary plugin we have no intention of releasing the plugin in the wordpress.org repository, so we needed a way to host new versions ourselves. As long as our clients’ installations would detect that a new version was available, we could always log in and click “Update Now” to pull down the latest version. Still, our end goal was always to get Automatic Background Updates working so that WordPress would handle all of the heavy lifting for us.

We tried a few different methods for accomplishing the task of detecting new versions – including the paid plugin AutoHosted – but in the end settled on the Plugin Update Checker written by Janis Elsts (link to GitHub repo here). The library is extremely simple to implement, and when I did have an issue with one important piece of functionality Janis actually had a patch for me in less than 2 hours. Cheers! While PUC doesn’t have the nice friendly WordPress Plugin admin interface for updating the critical details about your plugin that AutoHosted has, we found that the transparency & simplicity of PUC far outweighed the “con” of having to manually update our JSON file whenever we needed to make updates.

So let’s take a look at what it takes to implement:

require_once 'classes/plugin-update-checker/plugin-update-checker.php';
new PluginUpdateChecker_1_6(
    'http://www.example.com/pluginslug.json',
    __FILE__,
    'pluginslug'
);

Easy, right? After including the library, all that’s needed is to instantiate the class and pass it the full web path to the JSON file that contains all of the latest information about your plugin, your plugin’s basepath (in this case, the `__FILE__` constant) and your plugin’s slug. It supports much more, but for explanatory purposes we’ll stick with the basics.

Now let’s take a look at what a basic JSON file looks like:

{
"name" : "myPlugin",
"slug" : "myplugin",
"homepage" : "http://www.example.com/",
"download_url" : "http://www.example.com/wp-content/uploads/2014/10/myPlugin_v3.14.zip",

"version" : "3.14",
"requires" : "3.7",
"tested" : "4.0",
"last_updated" : "2014-10-24 10:38:00",
"upgrade_notice" : "This is my upgrade notice!",

"author" : "AuthorName",
"author_homepage" : "http://www.example.com/",

"sections" : {
"description" : "Version 3.14... now with more pie!",
"installation" : "Installation Instructions can go here if you like",
"changelog" : "The latest information about your changelog in the plugin"
},

"rating" : 100,
"num_ratings" : 1337,
"downloaded" : 2600
}

This file provides all of the information necessary for WordPress to consume the information and know everything there is to know about the plugin, and display it all in the popover window should someone click it from the WordPress Plugins admin page. Note that there are other items supported in the JSON file not shown here also, including custom “sections” (tabs) and more. It’s all included in the documentation.

And that’s it! With your zip file in place, your JSON file in place, and your code snippet inside of your plugin, you are good to go. Any time you update the version number inside the JSON file, all of your installations will “go orange” in the WordPress Plugins page with information about the new version.

In Part 2 we’ll be discussing how to leverage this functionality to allow WordPress to perform Automatic Background Updates for us. Once the system knows there is a new version of our plugin available, how do we get it to install itself? There’s at least 2 ways to do it, which I’ll review in that post. Stay tuned!