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.

Table of Contents

Getting Started
Migrating from 4.x
License Management
Resources

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

Download the latest release and copy the plugin-update-checker directory to your plugin or theme.
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.
Upload the JSON file to a publicly accessible location.

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 ReasonDev\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:

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

Notes

The second argument passed to buildUpdateChecker must be the absolute path to the main plugin file or any file in the theme directory. If you followed the "getting started" instructions, you can just use the __FILE__ constant.
The third argument - i.e. the slug - is optional but recommended. In most cases, the slug should be the same as the name of your plugin directory. For example, if your plugin lives in /wp-content/plugins/my-plugin, set the slug to my-plugin. If the slug is omitted, the update checker will use the name of the main plugin file as the slug (e.g. my-cool-plugin.php → my-cool-plugin). This can lead to conflicts if your plugin has a generic file name like plugin.php.

This doesn't affect themes because PUC uses the theme directory name as the default slug. Still, if you're planning to use the slug in your own code - e.g. to filter updates or override update checker behaviour - it can be a good idea to set it explicitly.

Reason packages: one-line setup

For packages served by packages.reason.com, ReasonUpdates::build() builds the metadata URL for you:

use ReasonDev\PluginUpdateChecker\ReasonUpdates;

$my_update_checker = ReasonUpdates::build( 'reason-password-reset', __FILE__ );

The first argument is the package's slug on the server. Always pass it explicitly: it usually matches the install directory, but that isn't guaranteed.
The second is the main plugin file, or any file in the theme's root directory such as functions.php. A PSR-4 plugin whose setup code lives in src/ passes its main-file constant instead of __FILE__.
It returns the same object as PucFactory::buildUpdateChecker(), so any code that uses $my_update_checker afterwards keeps working. The optional check period, option name and mu-plugin file arguments follow, as with PucFactory.
The older form, PucFactory::buildUpdateChecker( 'https://packages.reason.com/' . $slug . '/?action=get_metadata', __FILE__, $slug ), still works.

To point a site at a different server, such as staging, set the base address in wp-config.php. It must be the full https:// address of the update server's root, with no path, on a host used only for the update server: every HTTPS request to that host gets the update key (see below).

define( 'REASON_PACKAGES_URL', 'https://staging-packages.example.com/' );

To change the URL format itself on a site, without waiting for plugin releases, use the reason_packages_metadata_url filter. Register it before plugins call build(), so use an mu-plugin -- a theme's functions.php runs too late for plugins. If the new URL is on another host, add that host with reason_packages_updates_hosts so it receives the key:

add_filter( 'reason_packages_metadata_url', function ( $url, $slug ) {
    return 'https://packages.reason.com/v2/' . rawurlencode( $slug ) . '/metadata';
}, 10, 2 );

Composer runs only one copy of this library's startup file per library version (the file is named after the version, such as load-v5p7.php): the first-loaded plugin's copy of that version. So that copy supplies the update-key code, and ReasonUpdates too, if it has it. ReasonUpdates is also registered with each plugin's own Composer class loader, so a plugin that uses build() works even when an older copy loaded first, and build() loads the update-key support from its own copy in that case. A change to the built-in URL format itself, though, still only reaches a site once its first-loaded copy is updated -- in practice, that means updating every Reason plugin on the site. The constant and the filter above are the reliable way to change the URL on a site right away.

Automatic updates: since library version 5.7, the update checker ignores an "autoupdate": true field in update metadata, so a compromised update server can't make sites install updates unattended. packages.reason.com doesn't send that field today. If a plugin should honor it, opt in on the returned checker (the method only exists in 5.7 and later, so check first, in case an older bundled copy loaded):

if ( method_exists( $my_update_checker, 'allowAutoupdateField' ) ) {
    $my_update_checker->allowAutoupdateField();
}

A site can also decide per update with the puc_autoupdate_field_allowed-<slug> filter (puc_autoupdate_field_allowed_theme-<slug> for themes).

Reason packages: update key

packages.reason.com can require a shared key for update checks and downloads (the server's SIMPLE_UPDATE_KEY). To supply it, add this to the site's wp-config.php:

define( 'REASON_PACKAGES_UPDATES_KEY', 'the-shared-key' );

The library then adds Authorization: Bearer <key> to HTTPS requests sent to packages.reason.com, and to the REASON_PACKAGES_URL host, if one is set. No plugin code changes are needed. Download requests (action=download) never get this header: the server puts the key into download links itself once it requires one, and the header must not go along for the ride, since S3 rejects a redirected download request that carries both the header and its own presigned signature.

To send the key to another host, such as a staging deployment, use the reason_packages_updates_hosts filter:

add_filter( 'reason_packages_updates_hosts', function ( $hosts ) {
    $hosts[] = 'staging-packages.example.com';
    return $hosts;
} );

Rollout order: ship a plugin release that bundles this library version to every site, and define the constant, before setting SIMPLE_UPDATE_KEY on the server. This matters more than it might look: only the first-loaded plugin's copy of the update-key code runs on a site, so every Reason plugin on that site must bundle this library version before you can rely on the key there -- if even one plugin on the site still bundles an older copy and it happens to load first, the key is never sent. Sites that don't send the key stop receiving updates as soon as the server starts requiring it. When rotating the key afterward, keep in mind that WordPress caches download links, including the old key, for up to about 12 hours, so downloads may fail until sites run their next update check.

GitHub Integration

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

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

require 'plugin-update-checker/plugin-update-checker.php';
use ReasonDev\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');

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.

GitHub releases

Create a new release using the "Releases" feature on GitHub. The tag name and release title don't matter. The description is optional, but if you do provide one, it will be displayed when the user clicks the "View version x.y.z details" link on the "Plugins" page. Note that PUC ignores releases marked as "This is a pre-release".

If you want to use release assets, call the enableReleaseAssets() method after creating the update checker instance:
```
 $myUpdateChecker->getVcsApi()->enableReleaseAssets();
```
By default, PUC will simply use the first available asset. You can pass a regular expression to enableReleaseAssets() to filter assets by name. For example:
```
 $myUpdateChecker->getVcsApi()->enableReleaseAssets('/\.zip($|[?&#])/i');
```
Tags

To release version 1.2.3, create a new Git tag named v1.2.3 or 1.2.3. That's it.

PUC doesn't require strict adherence to SemVer. These are all valid tag names: v1.2.3, v1.2-foo, 1.2.3_rc1-ABC, 1.2.3.4.5. However, be warned that it's not smart enough to filter out alpha/beta/RC versions. If that's a problem, you might want to use GitHub releases or branches instead.
Stable branch

Point the update checker at a stable, production-ready branch:
```
 $updateChecker->setBranch('branch-name');
```
PUC will periodically check the Version header in the main plugin file or style.css and display a notification if it's greater than the installed version.

Caveat: If you set the branch to master (the default), the update checker will look for recent releases and tags first. It'll only use the master branch if it doesn't find anything else suitable.

Notes

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

Version number
- The "Version" plugin header.
- The latest GitHub release or tag name.
Changelog
- The "Changelog" section of readme.txt.
- One of the following files: CHANGES.md, CHANGELOG.md, changes.md, changelog.md
- GitHub release notes.
Required and tested WordPress versions
- The "Requires at least" and "Tested up to" fields in readme.txt.
- The following plugin headers: Required WP, Tested WP, Requires at least, Tested up to
"Last updated" timestamp
- The creation timestamp of the latest GitHub release.
- The latest commit in the selected tag or branch.
Number of downloads
- The download_count statistic of the latest release.
- If you're not using GitHub releases, there will be no download stats.
Other plugin details - author, homepage URL, description
- The "Description" section of readme.txt.
- Remote plugin headers (i.e. the latest version on GitHub).
- Local plugin headers (i.e. the currently installed version).
Ratings, banners, screenshots
- Not supported.

BitBucket Integration

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

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

require 'plugin-update-checker/plugin-update-checker.php';
use ReasonDev\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 API token
//with the "read:repository:bitbucket" scope and set the authentication
//credentials like this:
$myUpdateChecker->setAuthentication(array(
	'username'  => 'example@example.com', //Your BitBucket email address.
	'api_token' => '...',
));

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

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:

Stable tag header

This is the recommended approach if you're using tags to mark each version. Add a readme.txt file formatted according to the WordPress.org plugin readme standard to your repository. Set the "stable tag" header to the tag that represents the latest release. Example:
```
 Stable tag: v1.2.3
```
The tag doesn't have to start with a "v" or follow any particular format. You can use any name you like as long as it's a valid Git tag.

Tip: If you explicitly set a stable branch, the update checker will look for a readme.txt in that branch. Otherwise it will only look at the master branch.
Tags

You can skip the "stable tag" bit and just create a new Git tag named v1.2.3 or 1.2.3. The update checker will look at the most recent tags and pick the one that looks like the highest version number.

PUC doesn't require strict adherence to SemVer. These are all valid tag names: v1.2.3, v1.2-foo, 1.2.3_rc1-ABC, 1.2.3.4.5. However, be warned that it's not smart enough to filter out alpha/beta/RC versions.
Stable branch

Point the update checker at a stable, production-ready branch:
```
 $updateChecker->setBranch('branch-name');
```
PUC will periodically check the Version header in the main plugin file or style.css and display a notification if it's greater than the installed version. Caveat: If you set the branch to master, the update checker will still look for tags first.

GitLab Integration

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

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 ReasonDev\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 ReasonDev\PluginUpdateChecker\v5p7\Vcs\PluginUpdateChecker;
use ReasonDev\PluginUpdateChecker\v5p7\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 ReasonDev\PluginUpdateChecker\v5p7\Vcs\PluginUpdateChecker;
use ReasonDev\PluginUpdateChecker\v5p7\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'
);

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.

GitLab releases

Create a new release using the "Releases" feature on GitLab. The tag name should match the version number. You can add a v prefix to the tag, like v1.2.3. Releases that are marked as "Upcoming Release" will be automatically ignored.

If you want to use custom release assets, call the enableReleaseAssets() method after creating the update checker instance:
```
 $myUpdateChecker->getVcsApi()->enableReleaseAssets();
```
By default, PUC will use the first available asset link, regardless of type. You can pass a regular expression to enableReleaseAssets() to make it pick the first link where the URL matches the regex. For example:
```
 $myUpdateChecker->getVcsApi()->enableReleaseAssets('/\.zip($|[?&#])/i');
```
Tip: You can use a Gitlab CI/CD Pipeline to automatically generate your update on release using a Generic Package. For more information about generic packages, refer to the following links: - Gitlab CI/CD Release Documentation - Gitlab Release Assets as Generic Package Documentation - Example .gitlab-ci.yml file using Release Generic Packages for generating a update package from the Sensei-LMS wordpress plugin
Tags

To release version 1.2.3, create a new Git tag named v1.2.3 or 1.2.3. The update checker will look at recent tags and use the one that looks like the highest version number.

PUC doesn't require strict adherence to SemVer. However, be warned that it's not smart enough to filter out alpha/beta/RC versions. If that's a problem, you might want to use GitLab branches instead.
Stable branch

Point the update checker at any stable, production-ready branch:
```
 $myUpdateChecker->setBranch('stable-branch-name');
```
PUC will periodically check the Version header in the main plugin file or style.css and display a notification if it's greater than the installed version. Caveat: Even if you set the branch to main (the default) or master (the historical default), the update checker will still look for recent releases and tags first.

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 ReasonDev\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 name	New class name
`Puc_v4_Factory`	`ReasonDev\PluginUpdateChecker\v5\PucFactory`
`Puc_v4p13_Factory`	`ReasonDev\PluginUpdateChecker\v5p7\PucFactory`
`Puc_v4p13_Plugin_UpdateChecker`	`ReasonDev\PluginUpdateChecker\v5p7\Plugin\UpdateChecker`
`Puc_v4p13_Theme_UpdateChecker`	`ReasonDev\PluginUpdateChecker\v5p7\Theme\UpdateChecker`
`Puc_v4p13_Vcs_PluginUpdateChecker`	`ReasonDev\PluginUpdateChecker\v5p7\Vcs\PluginUpdateChecker`
`Puc_v4p13_Vcs_ThemeUpdateChecker`	`ReasonDev\PluginUpdateChecker\v5p7\Vcs\ThemeUpdateChecker`
`Puc_v4p13_Vcs_GitHubApi`	`ReasonDev\PluginUpdateChecker\v5p7\Vcs\GitHubApi`
`Puc_v4p13_Vcs_GitLabApi`	`ReasonDev\PluginUpdateChecker\v5p7\Vcs\GitLabApi`
`Puc_v4p13_Vcs_BitBucketApi`	`ReasonDev\PluginUpdateChecker\v5p7\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

This blog post has more information about the update checker API. Slightly out of date.
Debug Bar - useful for testing and debugging the update checker.
Update format reference - describes all fields supported by the JSON-based update information format used by the update checker. Only covers plugins. Themes use a similar but more limited format.
Securing download links - a general overview.
A GUI for entering download credentials
Theme Update Checker - an older, theme-only variant of this update checker.

Name		Name	Last commit message	Last commit date
.claude/skills/upstream-merge		.claude/skills/upstream-merge
Puc		Puc
build		build
css		css
examples		examples
js		js
languages		languages
tests		tests
vendor		vendor
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
composer.json		composer.json
license.txt		license.txt
load-v5p7.php		load-v5p7.php
phpcs.xml		phpcs.xml
plugin-update-checker.php		plugin-update-checker.php
reason-packages-auth.php		reason-packages-auth.php
reason-updates.php		reason-updates.php

Navigation Menu

Repository files navigation

Plugin Update Checker

Getting Started

Self-hosted Plugins and Themes

How to Release an Update

Notes

Reason packages: one-line setup

Reason packages: update key

GitHub Integration

How to Release an Update

Notes

BitBucket Integration

How to Release an Update

GitLab Integration

How to Release a GitLab Update

Migrating from 4.x

License Management

Resources

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Plugin Update Checker

Getting Started

Self-hosted Plugins and Themes

How to Release an Update

Notes

Reason packages: one-line setup

Reason packages: update key

GitHub Integration

How to Release an Update

Notes

BitBucket Integration

How to Release an Update

GitLab Integration

How to Release a GitLab Update

Migrating from 4.x

License Management

Resources

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages