Automatic Updates For Private And Commercial Plugins

Last updated on May 17, 2014.

Since time immemorial, only plugins hosted in the official WordPress.org plugin directory have supported automatic updates. Now, I’ve written a PHP library that you can use to add automatic update capabilities to any plugin. Public, private and commercial plugins alike – all can now enjoy the benefits of automatic update notifications and one-click upgrades.

The custom update checker integrates closely with the upgrade system already built into WordPress, producing a seamless user experience. Observe :

An upgrade notice for a privately hosted plugin.

The ‘Plugin Information’ window with placeholder data.

Download

License




This library is licensed under the GPL and is distributed free of charge. If you find it useful, consider making a donation.

Commercial licensing (e.g. for projects that can’t use an open-source license) is available upon request.

Quick-start Guide

This section describes the quickest way to get automatic updates working for your plugin. Here’s what you’ll need to do: create a metadata file for your plugin, host it somewhere publicly accessible, and tell the update checker where to find it.

Lets start with the metadata. Copy the JSON code below into a new file and replace the placeholder values with your plugin’s info.

{
    "name" : "My Cool Plugin",
    "slug" : "my-cool-plugin",
    "download_url" : "http://example.com/plugins/my-cool-plugin.zip",
    "version" : "2.0",
    "author" : "John Smith",
    "sections" : {
        "description" : "Plugin description here. Basic HTML allowed."
    }
}

(This is the minimal amount data required to make automatic updates work. In most cases, you will probably want to add a couple more fields. See the metadata docs below for details.)

Most of the fields should be pretty self-explanatory, with one possible exception – the “slug”. WordPress expects all plugins that support automatic updates to have a unique textual identifier called the “slug”. Normally, slugs are assigned by the official plugin directory. For a private/commercial plugin that’s hosted elsewhere you’ll have to make something up. If unsure, just use the plugin’s file name without the “.php” extension (my-cool-plugin/my-cool-plugin.php becomes my-cool-plugin).

Upload the metadata file you just created to your web server. It doesn’t matter where exactly you put the file or how you name it. The important thing is for its URL to be accessible from wherever someone might install your plugin.

Next, copy the “update-checker” directory from the client library archive to your plugin’s directory. Then fire up your favourite code editor and add the following lines to the top of your plugin file:

require 'plugin-updates/plugin-update-checker.php';
$MyUpdateChecker = PucFactory::buildUpdateChecker(
    'http://example.com/path/to/metadata.json',
    __FILE__,
    'your-chosen-slug'
);

If you followed my advice and used the plugin’s file name as the slug, you can omit the third parameter of the PucFactory::buildUpdateChecker() call.

Tip: Sometimes you’ll run into a situation where another active plugin is also using this update checker. As a result, there could be several different versions of the library loaded at the same time. The above code snippet will always give you the latest available version. This can be a problem if your plugin expects an older version and is not API-compatible with the latest version.

To use a specific version of the update checker (e.g. the one included with your plugin), instantiate the PluginUpdateChecker_x_y class directly. Replace x and y with the major and minor version numbers:

//Use version 1.5 of the update checker.
require 'plugin-updates/plugin-update-checker.php';
$MyUpdateChecker = new PluginUpdateChecker_1_5 (
    'http://example.com/path/to/metadata.json',
    __FILE__,
    'your-chosen-slug'
);

And that, believe it or not, is it.

The PluginUpdateChecker class will handle the rest. It’ll check the metadata file every 12 hours and, if it discovers that a new version has been released, twiddle the right bits in the undocumented WP API to make it show up as a standard upgrade notification in the “Plugins” tab. Assuming you’ve set up the download_url correctly, users will be able to install the update with a single click.

The rest of this post will be devoted to a more in-depth discussion of the update checker class and the metadata format.

The PluginUpdateChecker class

This class is the core of the update checker. It’s also the only part of the updater that you should need to deal with unless you decide to  extend the library yourself.

Class constructor

All configuration settings should be specified by passing them to the PucFactory::buildUpdateChecker() factory method, or directly to the PluginUpdateChecker constructor. Both takes the following parameters:

  • $metadataUrl – The full URL of the plugin’s metadata file.
  • $pluginFile – The path to the plugin’s file. In most cases you can simply use the __FILE__ constant here.
  • $slug – The plugin’s ‘slug’. If not specified, the filename part of $pluginFile (sans “.php”) will be used as the slug.
  • $checkPeriod – How often to check for updates (in hours). Defaults to checking every 12 hours. Set to zero to disable automatic update checks.
  • $optionName – Where to store book-keeping info about updates. Defaults to “external_updates-$slug”.

checkForUpdates()

Manually trigger an update check. This is especially useful when you’ve disabled automatic checks by setting $checkPeriod (above) to zero. This method takes no parameters and returns nothing.

addQueryArgFilter($callback)

Register a callback for filtering query arguments. Whenever the update checker needs to retrieve the metadata file, it will first run each filter callback and attach the query arguments that they return to the metadata URL. This lets you pass arbitrary data to the server hosting the metadata. For example, commercial plugins could use it to implement some kind of authorization scheme where only users that have the right “key” get automatic updates.

The callback function will be passed an associative array of query arguments and should return a modified array. By default, the update checker will add these arguments to the metadata URL:

  • installed_version – set to the currently installed version of the plugin.
  • checking_for_updates – set to 1 if checking for updates, absent otherwise (i.e. when loading data for the “Plugin Information” box).

This method takes one parameter – the callback function.

addHttpRequestArgFilter($callback)

Register a callback for filtering the various options passed to the built-in helper function wp_remote_get that the update checker uses to periodically download plugin metadata. The callback function should take one argument – an associative array of arguments – and return a modified array or arguments. See the WP documentation on wp_remote_get for details about what arguments are available and how they work.

This method takes one parameter – the callback function.

addResultFilter($callback)

Register a callback for filtering plugin info retrieved from the metadata URL.

The callback function should take two arguments. If the metadata was retrieved successfully, the first argument passed will be an instance of PluginInfo (see the source for a description of this class). Otherwise, it will be NULL. The second argument will be the corresponding return value of wp_remote_get (see WP docs for details). The callback function should return a new or modified instance of PluginInfo or NULL.

This method takes one parameter – the callback function.

Metadata format

The automatic update system uses a JSON-based file format to describe plugins.  Essentially, the entire file is one big JSON-encoded object (AKA hash-table or associative array). Each field – or array key – represents a piece of information about the latest version of the plugin. The full description of all available fields is here.

For the sake of simplicity, both general metadata and update-related information are stored in the same file. If this is undesirable, you can replace the plain JSON file with a script that checks for the presence of the the “checking_for_updates” query parameter and emits just the update-related fields if its set to “1”.

Notes

Your plugin must be active for updates to work. The update checker is just another piece of PHP code loaded and run by your plugin, and it won’t be run if the plugin is inactive.

One consequence of this that may not be immediately obvious is that on a multisite installation updates will only show up if the plugin is active on the main site. This is because update notifications usually appear in the network admin, and only plugins active on the main site are loaded in that case. The main site of a WordPress network is the one that was created first and has the path “/” in the Sites -> All Sites list.

Related posts :

279 Responses to “Automatic Updates For Private And Commercial Plugins”

  1. Jānis Elsts says:

    Is it a problem when the plugin en the update server are on the same hosting/domain name?

    No, that’s completely fine. I’ve used a similar setup before without problems.

    Try installing the Debug Bar plugin. You can use it to get more debug information from the update checker. Once installed, click the “Debug” link in the admin toolbar and switch to the section “PUC (your-plugin-slug)”. It should list all kinds of information – check it for errors.

  2. Erwin says:

    Thnx agian I try it tomorrow I let you know if I see a error.

  3. Erwin says:

    Debug Bar give a error. when I request info from the Metadata URL I get: Warning: The URL http://updates.sggraphics.nl?action=get_metadata&slug=PZN&installed_version=1.0 does not point to a valid plugin metadata file. WP HTTP error: Failed to connect to updates.sggraphics.nl port 80: Connection refused in /home/vhosts/sggraphics.nl/subdomains/kip/httpdocs/wp-content/plugins/PZN/update/plugin-update-checker.php on line 229
    Failed to retrieve plugin info from the metadata URL.

    But when I past this URL in my browser: http://updates.sggraphics.nl/?action=get_metadata&slug=PZN

    Then I see the metadata fine? Can you see at the Warning what I have done wrong?

  4. Jānis Elsts says:

    That sounds like a server configuration problem. Could it be that your server’s firewall is set to block loopback connections? As in, it prevents scripts running on that server connecting back to the same server.

  5. Erwin says:

    I dont know if loopback connections is block? But i’m sure what you say is true. I install the plugin in a other WP on a other hosting and now it works great. :) Now I gonne try this story: http://w-shadow.com/blog/2013/03/19/plugin-updates-securing-download-links/

    thnx agian for all your time and quick respond and thinking for a solution. Thats why it work now :)

  6. Roman says:

    Oh yeah!

    I really thank you for that. First run -> success.
    Will try it more and more and inform you how its going.

    Thanks, thanks, thanks – really good help.

  7. ValvePress says:

    Great Work, How can we add an argument to the download file so we can parse this argument and process the download if the auth is valid?

    I see we can filter the arguments to the meta file but what about the download file itself? I don’t like the access to the download file to be public

  8. Jānis Elsts says:

    You could either do this server-side and show each user a different download URL based on some query argument, or you could use addResultFilter() to filter the update info and change the download URL there.

  9. ValvePress says:

    Thanks. Works Great!

  10. Joel says:

    Hi, would this work with Theme Updates aswell?

  11. […] am using classes provided from here: http://w-shadow.com/blog/2010/09/02/automatic-updates-for-any-plugin/ to not use wordpress.org as the location for the updated […]

  12. Barry says:

    I’m seeing a lot of people update via this plugin but it appears a majority of them do not have my plugin reactivated post update. What could be the issue? Update seems to work fine just doesn’t reactivate the plugin consistently.

  13. Jānis Elsts says:

    That could be caused by providing an update package (i.e. ZIP file) with an incorrect directory structure. Usually all plugin files should be inside a directory, and then that directory should be zipped. If the files are at the root of the archive, or if the directory name doesn’t match the actual plugin directory in /wp-content/plugins, WordPress might install the update in the wrong place or fail to activate it.

    Other than that, it could also be a WordPress configuration problem (e.g. file permissions). The code on this page just checks for updates. It doesn’t install updates; WordPress does that.

    (Nitpick: This is not a plugin, it’s a library used by plugins.)

  14. Barry says:

    I see you release 1.6!? Does this fix only address unattended background automatic WP plugin updates? Or does it resolve other issues as well?

  15. Jānis Elsts says:

    This release only affects background updates.

  16. Barry says:

    Which I believe WP doesn’t upgrade plugins in the background by default?

  17. Jānis Elsts says:

    Yes, by default it only installs minor core updates in the background.

    But you can configure it to automatically upgrade plugins as well:
    http://codex.wordpress.org/Configuring_Automatic_Background_Updates

  18. Adam says:

    Thank You! Your plugin works perfectly.

Leave a Reply