Automatic Updates For Private And Commercial Plugins

Last updated on June 26, 2015.

Since time immemorial, only plugins hosted in the official 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.

An upgrade notice for a privately hosted plugin.

The version information window with placeholder data

The version information window with placeholder data



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

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" : "",
    "version" : "2.0",
    "author" : "John Smith",
    "sections" : {
        "description" : "Plugin description here. Basic HTML allowed."

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

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 “plugin-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-update-checker/plugin-update-checker.php';
$MyUpdateChecker = PucFactory::buildUpdateChecker(

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 2.0 of the update checker.
require 'plugin-update-checker/plugin-update-checker.php';
$MyUpdateChecker = new PluginUpdateChecker_2_0 (

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 provided a valid download_url, users will be able to install the update with a single click.

Tip: When creating the ZIP file for an update, put all plugin files inside a directory. The directory name should match the plugin slug. Do not put the files at the root of the ZIP archive – it can cause subtle bugs and errors when someone ties to install the update.

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”.


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.


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.


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.


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”.


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 :

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

  1. Amit says:

    The page reload update is working fine. But i have a problem with ajax update which is showing this error.

    TypeError: g.find(…).html(…) is undefined


    Please help me!!!!

  2. Jānis Elsts says:

    That looks like an error in WP core or another plugin. Try deactivating all other plugins and switching to the default theme to test for conflicts.

  3. Amit says:

    I tried in other sites, set to default template, removed other plugins…still no solution..
    is there anything m missing.

    My meta data file looks like:

    “name” : “Woocommerce with active Campaign”,
    “slug” : “Woo_Active”,
    “download_url” : “”,
    “version” : “2.0.0”,
    “author” : “Amit Kumar”,
    “sections” : {
    “description” : “Sell products and services in Woocommerce and also save the Email Id to Active Campaign Lists.”

    or am i missing something in the plugin-update-checker.php file which has…

    public $metadataUrl = ‘’; //The URL of the plugin’s metadata file.
    public $pluginAbsolutePath = ‘Woo_Active/woocommerce_Active.php’; //Full path of the main plugin file.
    public $pluginFile = ‘woocommerce_Active.php’; //Plugin filename relative to the plugins directory. Many WP APIs use this to identify plugins.
    public $slug = ‘woocommerce_Active’; //Plugin slug.
    public $optionName = ”; //Where to store the update info.
    public $muPluginFile = ”; //For MU plugins, the plugin filename relative to the mu-plugins directory.

    public $debugMode = false; //Set to TRUE to enable error reporting. Errors are raised using trigger_error()
    //and should be logged to the standard PHP error log.
    public $scheduler;

    protected $upgraderStatus;

    private $debugBarPlugin = null;
    private $cachedInstalledVersion = null;

    what are other things important for the ajax response replacement error…..

  4. Jānis Elsts says:

    It looks like your plugin slug contains both uppercase and lowercase characters. Is your plugin directory name the same (Woo_Active)?

    There’s a known bug in WordPress core that prevents AJAX updates from working correctly for plugins that have uppercase characters in the directory name. Since this is a core bug, it can’t be fixed by this update checker. As far as I know, the only solution is to use all-lowercase names.

  5. Amit says:

    Thanks, man….it worked….awesome

  6. Uli says:

    Hello, Your code works great. But I found some missing feature:
    1. Missing Background image if using the download server (rating, download, active installs, num_ratings).
    2. Missing display of screenshots like described in the WordPress readme.txt, if I use the download server.

    1st problem I solved with this code:

    // Add some data to the API like the header picture
    class MyCustomServer extends Wpup_UpdateServer
    protected function filterMetadata($meta, $request)
    $referer_url = ‘/wp-content/plugins/lit-client/assets/’;
    $low_banner = $referer_url . ‘banner-772×250.png’;
    $high_banner = $referer_url . ‘banner-1544×500.png’;

    $banner_array = array
    “low” => $low_banner,
    “high” => $high_banner

    $meta = parent::filterMetadata($meta, $request);

    $meta[‘banners’] = $banner_array;
    $meta[‘rating’] = ’90’;
    $meta[‘downloaded’] = ‘106’;
    $meta[‘active_installs’] = ’85’;
    $meta[‘num_ratings’] = ’34’;

    return $meta;

    The banners must be located in the subdir “assets” and must have the names like the code describes.

    Next step could be to make a WordPress- GUI for the server to display the plugins in a list with the possibility to rate it like in And there could be a download counter in the server because the server knows the number of downloads. Then the static values could be calculated dynamic.

    For the 2nd problem I found no quick solution. Seams to be a new filter in the download server and some changes in the client.

    Again. Thanks for the gteat software!

  7. Uli says:

    Hello, another nice but missing feature is that the client does show the “View Version Details” link only in that case when a plugin update is available but not in that case when the plugin is up to date.

    So it is not posssible to show the info after an update of the plugin.

    Would be nice to have the link in both cases.

  8. Uli says:

    Hello again. Here with a question. Is there in the updater any global variable for the “plugin version” that I can use to display the current plugin version in the backend footer of my plugin?

  9. Jānis Elsts says:

    Background image and screenshots: That’s on the long-term to do list.

    Server UI for listing and rating plugins: Probably not going to happen. It’s beyond the scope of this project. I’m not planning to build a full replacement for the plugin directory.

    Download counter in the server: That would require a database of some kind. This means more complicated setup and increased server requirements. Is the additional complexity worth it?

    Showing the “view version details” when there is no update: Probably not going to happen because WordPress doesn’t do it. You’re welcome to add that link to your own plugin, of course.

    Getting the current version:
    Yes, use $updateChecker->getInstalledVersion(). It returns the version number as a string.

  10. Aires says:


    I am so glad I ran across this I can not thank you enough. I am hoping to offer updates to my customers real soon.

    I have an issue that I cant seem to figure it out it shows that there is an update available and will go through the process and then say all updates are completed. But it doesnt really update nothing changes. If i refresh it tells me i still have an update.

    I am hosting the DL file on google drive.

    Thanks for any input you may have.

  11. Jānis Elsts says:

    The first thing to check is whether the update – that is, the ZIP file that your download_url points to – isn’t actually the same as the installed version. Also make sure that the version number in the metadata file matches the version in the ZIP file.

  12. Aires says:

    Google drive was the issue I think I have it figured out.

  13. Andrea says:

    Hi! First… great code, well done.
    Just a question; are there any problems on using two plugins in the same wp site that use your updater?

  14. Jānis Elsts says:

    The update checker was designed with situations like that in mind. As long as both plugins are using the code correctly, there shouldn’t be any problems.

    In this case, “correctly” means that if your plugins is only compatible with a specific version of the library (i.e. the one bundled with your plugin), your code should explicitly ask for that particular version by using e.g. “new PluginUpdateChecker_2_3(…)”. On the other hand, if you’re sure you always want the latest version, you can use “PucFactory::buildUpdateChecker(…)” instead.

  15. Andrea says:

    Great, thank you.

  16. Miguel Arias says:

    This works for updating themes as well?

  17. Jānis Elsts says:

    This only works for plugins, but there’s another library that works for themes:

  18. Andrew says:

    The plugin works. I have an unexpected problem with plugin’s php and css files after update: nellow each line is inserted a new blank line (if i have 50 lines of code, now i have 100 lines because blank lines were inserted and the code is harder to read).

    This does Not happend with files from /plugin-updates/, i suppose if from php page encoding or file headers set your script when unzip. Any help or ideas please? thanks

Leave a Reply