Home

Awesome

Plugin Update Checker

This is a custom update checker library for WordPress plugins and themes. It lets you add automatic update notifications and one-click upgrades to your commercial plugins, private themes, and so on. All you need to do is put your plugin/theme details in a JSON file, place the file on your server, and pass the URL to the library. The library periodically checks the URL to see if there's a new version available and displays an update notification to the user if necessary.

From the users' perspective, it works just like with plugins and themes hosted on WordPress.org. The update checker uses the default upgrade UI that is familiar to most WordPress users.

<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

Table of Contents

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Getting Started

Note: In each of the below examples, part of the instructions is to create an instance of the update checker class. It's recommended to do this either during the plugins_loaded action or outside of any hooks. If you do it only during an admin_* action, then updates will not be visible to a wide variety of WordPress management tools; they will only be visible to logged-in users on dashboard pages.

Self-hosted Plugins and Themes

  1. Download the latest release and copy the plugin-update-checker directory to your plugin or theme.

  2. Go to the examples subdirectory and open the .json file that fits your project type. Replace the placeholder data with your plugin/theme details.

    • Plugin example:

      {
	"name" : "Plugin Name",
	"version" : "2.0",
	"download_url" : "https://example.com/plugin-name-2.0.zip",
	"sections" : {
		"description" : "Plugin description here. You can use HTML."
	}
}

      This is a minimal example that leaves out optional fields. See this table for a full list of supported fields and their descriptions.

    • Theme example:

      {
	"version": "2.0",
	"details_url": "https://example.com/version-2.0-details.html",
	"download_url": "https://example.com/example-theme-2.0.zip"
}

      This is actually a complete example that shows all theme-related fields. version and download_url should be self-explanatory. The details_url key specifies the page that the user will see if they click the "View version 1.2.3 details" link in an update notification.

  3. Upload the JSON file to a publicly accessible location.

  4. Add the following code to the main plugin file or to the functions.php file:

    require 'path/to/plugin-update-checker/plugin-update-checker.php';
use YahnisElsts\PluginUpdateChecker\v5\PucFactory;

$myUpdateChecker = PucFactory::buildUpdateChecker(
	'https://example.com/path/to/details.json',
	__FILE__, //Full path to the main plugin file or functions.php.
	'unique-plugin-or-theme-slug'
);

    Note: If you're using the Composer autoloader, you don't need to explicitly require the library.

How to Release an Update

Change the version number in the JSON file and make sure that download_url points to the latest version. Update the other fields if necessary. Tip: You can use wp-update-server to automate this process.

By default, the library will check the specified URL for changes every 12 hours. You can force it to check immediately by clicking the "Check for updates" link on the "Plugins" page (it's next to the "Visit plugin site" link). Themes don't have that link, but you can also trigger an update check like this:

  1. Install Debug Bar.
  2. Click the "Debug" menu in the Admin Bar (a.k.a Toolbar).
  3. Open the "PUC (your-slug)" panel.
  4. Click the "Check Now" button.

Notes

GitHub Integration

  1. Download the latest release and copy the plugin-update-checker directory to your plugin or theme.

  2. Add the following code to the main plugin file or functions.php:

    require 'plugin-update-checker/plugin-update-checker.php';
use YahnisElsts\PluginUpdateChecker\v5\PucFactory;

$myUpdateChecker = PucFactory::buildUpdateChecker(
	'https://github.com/user-name/repo-name/',
	__FILE__,
	'unique-plugin-or-theme-slug'
);

//Set the branch that contains the stable release.
$myUpdateChecker->setBranch('stable-branch-name');

//Optional: If you're using a private repository, specify the access token like this:
$myUpdateChecker->setAuthentication('your-token-here');

  3. Plugins only: Add a readme.txt file formatted according to the WordPress.org plugin readme standard to your repository. The contents of this file will be shown when the user clicks the "View version 1.2.3 details" link.

How to Release an Update

This library supports a couple of different ways to release updates on GitHub. Pick the one that best fits your workflow.

Notes

The library will pull update details from the following parts of a release/tag/branch:

BitBucket Integration

  1. Download the latest release and copy the plugin-update-checker directory to your plugin or theme.

  2. Add the following code to the main plugin file or functions.php:

    require 'plugin-update-checker/plugin-update-checker.php';
use YahnisElsts\PluginUpdateChecker\v5\PucFactory;

$myUpdateChecker = PucFactory::buildUpdateChecker(
	'https://bitbucket.org/user-name/repo-name',
	__FILE__,
	'unique-plugin-or-theme-slug'
);

//Optional: If you're using a private repository, create an OAuth consumer
//and set the authentication credentials like this:
//Note: For now you need to check "This is a private consumer" when
//creating the consumer to work around #134:
// https://github.com/YahnisElsts/plugin-update-checker/issues/134
$myUpdateChecker->setAuthentication(array(
	'consumer_key' => '...',
	'consumer_secret' => '...',
));

//Optional: Set the branch that contains the stable release.
$myUpdateChecker->setBranch('stable-branch-name');

  3. Optional: Add a readme.txt file formatted according to the WordPress.org plugin readme standard to your repository. For plugins, the contents of this file will be shown when the user clicks the "View version 1.2.3 details" link.

How to Release an Update

BitBucket doesn't have an equivalent to GitHub's releases, so the process is slightly different. You can use any of the following approaches:

GitLab Integration

  1. Download the latest release and copy the plugin-update-checker directory to your plugin or theme.

  2. Add the following code to the main plugin file or functions.php and define how you want to check for updates from Gitlab (refer to: Gitlab: How to Release an Update):

    require 'plugin-update-checker/plugin-update-checker.php';
use YahnisElsts\PluginUpdateChecker\v5\PucFactory;

$myUpdateChecker = PucFactory::buildUpdateChecker(
	'https://gitlab.com/user-name/repo-name/',
	__FILE__,
	'unique-plugin-or-theme-slug'
);

//Optional: If you're using a private repository, specify the access token like this:
$myUpdateChecker->setAuthentication('your-token-here');

    Alternatively, if you're using a self-hosted GitLab instance, initialize the update checker like this:

    use YahnisElsts\PluginUpdateChecker\v5p5\Vcs\PluginUpdateChecker;
use YahnisElsts\PluginUpdateChecker\v5p5\Vcs\GitLabApi;

$myUpdateChecker = new PluginUpdateChecker(
	new GitLabApi('https://myserver.com/user-name/repo-name/'),
	__FILE__,
	'unique-plugin-or-theme-slug'
);
//Optional: Add setAuthentication(...) and setBranch(...) as shown above.

    If you're using a self-hosted GitLab instance and subgroups or nested groups, you have to tell the update checker which parts of the URL are subgroups:

    use YahnisElsts\PluginUpdateChecker\v5p5\Vcs\PluginUpdateChecker;
use YahnisElsts\PluginUpdateChecker\v5p5\Vcs\GitLabApi;

$myUpdateChecker = new PluginUpdateChecker(
	new GitLabApi(
		'https://myserver.com/group-name/subgroup-level1/subgroup-level2/subgroup-level3/repo-name/', 
		null, 
		'subgroup-level1/subgroup-level2/subgroup-level3'
	),
	__FILE__,
	'unique-plugin-or-theme-slug'
);

  3. Plugins only: Add a readme.txt file formatted according to the WordPress.org plugin readme standard to your repository. The contents of this file will be shown when the user clicks the "View version 1.2.3 details" link.

How to Release a GitLab Update

A GitLab repository can be checked for updates in 3 different ways.

Migrating from 4.x

Older versions of the library didn't use namespaces. Code that was written for those versions will need to be updated to work with the current version. At a minimum, you'll need to change the factory class name.

Old code:

$myUpdateChecker = Puc_v4_Factory::buildUpdateChecker(
	'https://example.com/info.json',
	__FILE__,
	'my-slug'
);

New code:

use YahnisElsts\PluginUpdateChecker\v5\PucFactory;

$myUpdateChecker = PucFactory::buildUpdateChecker(
	'https://example.com/info.json',
	__FILE__,
	'my-slug'
);

Other classes have also been renamed, usually by simply removing the Puc_vXpY_ prefix and converting Category_Thing to Category\Thing. Here's a table of the most commonly used classes and their new names:

Old class nameNew class name
Puc_v4_FactoryYahnisElsts\PluginUpdateChecker\v5\PucFactory
Puc_v4p13_FactoryYahnisElsts\PluginUpdateChecker\v5p5\PucFactory
Puc_v4p13_Plugin_UpdateCheckerYahnisElsts\PluginUpdateChecker\v5p5\Plugin\UpdateChecker
Puc_v4p13_Theme_UpdateCheckerYahnisElsts\PluginUpdateChecker\v5p5\Theme\UpdateChecker
Puc_v4p13_Vcs_PluginUpdateCheckerYahnisElsts\PluginUpdateChecker\v5p5\Vcs\PluginUpdateChecker
Puc_v4p13_Vcs_ThemeUpdateCheckerYahnisElsts\PluginUpdateChecker\v5p5\Vcs\ThemeUpdateChecker
Puc_v4p13_Vcs_GitHubApiYahnisElsts\PluginUpdateChecker\v5p5\Vcs\GitHubApi
Puc_v4p13_Vcs_GitLabApiYahnisElsts\PluginUpdateChecker\v5p5\Vcs\GitLabApi
Puc_v4p13_Vcs_BitBucketApiYahnisElsts\PluginUpdateChecker\v5p5\Vcs\BitBucketApi

License Management

Currently, the update checker doesn't have any built-in license management features. It only provides some hooks that you can use to, for example, append license keys to update requests ($updateChecker->addQueryArgFilter()). If you're looking for ways to manage and verify licenses, please post your feedback in this issue.

Resources