NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist
Packagist, #2539 most downloaded on Packagist
A custom update checker for WordPress plugins and themes. Useful if you can't host your plugin in the official WP repository but still want it to support automatic updates.
Latest stable
v4.8.1
Last release 16 days ago
06 Nov 2026
Ships fairly regularly
a new release about every 7 months
Nearly every release is documented
notes for 37 of 38 stable releases
Nothing withdrawn
no release was ever pulled
12 years old
40 releases · first in 2014
Drag across the ruler to compare, or tap a release to open it.
Fixed a fatal error that could happen when loading the Puc_v4_Factory class with the Composer-generated autoloader.
Fixed a fatal error that could happen when loading the Puc_v4_Factory class with the Composer-generated autoloader.
Nothing published for this version
Testing a different Composer autoloading mechanism.
Testing a different Composer autoloading mechanism.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
…could not be resolved for some reason: "Deprecated: strpos(): Non-string needles will be interpreted as strings in the future".
Fixed a PHP notice that was triggered in PHP 7.3 when the path to the mu-plugins directory could not be resolved for some reason: "Deprecated: strpos(): Non-string needles will be interpreted as strings in the future".
This is a hotfix to remove some debug logging code that was accidentally left in the 4.3 release.
This is a hotfix to remove some debug logging code that was accidentally left in the 4.3 release.
Added Italian translation. Props to @LDAV.
Fixed error "cannot redeclare class Puc_v4_Autoloader".
Fixed "PCLZIP_ERR_BAD_FORMAT" error when installing an update from a private BitBucket repository.
1.0.2 or v0.0.1).Changed licensing from GNU GPL to the more permissive MIT License.
Minimum required PHP version increased to 7.4.
retain_fields filter not being saved in the database.esc_url() instead of esc_attr() for escaping the URL of the "Check for updates" link.Added optional support for the "autoupdate" field that allows triggering unattended plugin updates. To enable it, you need to both set autoupdate to t
autoupdate to true in plugin update metadata and call $updateChceker->allowAutoupdateField() in your plugin. Props to @hisman for part of the implementation.htmlentities() calls with esc_html(). This takes advantage of automatic character set detection in WP core, and should eliminate some static analysis warnings. See #597.wp_redirect() calls with wp_safe_redirect(). This shouldn't matter in practice since PUC only ever does internal redirects, but it pacifies some static analysis tools. See #597.zh_CN, @seatonjiang)zh_TW, @alexclassroom)Fixed a number of PHP 8.4 deprecation notices like "Implicitly marking parameter $foo as nullable is deprecated, the explicit nullable type must be us…
Removed information about plugins and themes that manage updates via PUC from data that WordPress core sends to api.wordpress.org when it checks for u
api.wordpress.org when it checks for updates. Props to @DavidAnderson684 (#578).
remove_from_default_update_checks filter. Example:$updateChecker->addFilter('remove_from_default_update_checks', '__return_false');
Added automatic update checks before certain WP-CLI commands that read plugin/theme update status, such as wp plugin status, wp theme update, and so o
wp plugin status, wp theme update, and so on. This just triggers the existing scheduling logic, so if you run multiple commands in very quick succession, PUC won't check for updates every time. See #558.Ui class (YahnisElsts\PluginUpdateChecker\v5p3\Plugin\Ui) sometimes did not load correctly if multiple active plugins/themes were using different versions of PUC.upgrader_process_complete callback.phpcs.xml from exported archives. Props to @szepeviktor.Fixed a fatal error that could happen in the unusual situation where the Debug_Bar class exists but Debug_Bar_Panel does not. See #543.
Debug_Bar class exists but Debug_Bar_Panel does not. See #543.Fixed a few PHP 8.2 deprecation notices like Creation of dynamic property YahnisElsts\PluginUpdateChecker\vXpY\Plugin\PluginInfo::$example is deprecat…
Creation of dynamic property YahnisElsts\PluginUpdateChecker\vXpY\Plugin\PluginInfo::$example is deprecated.Added a way to filter GitHub and GitLab releases.
//Allow only beta versions (e.g. for testing).
$updateChecker->getVcsApi()->setReleaseVersionFilter(
'/beta/i', //Regex for the version number.
Api::RELEASE_FILTER_ALL, //Disables the default filter(s).
30 //Max number of recent releases to scan for matches.
);
//Set an arbitrary custom filter.
$updateChecker->getVcsApi()->setReleaseFilter(
function($versionNumber, $releaseObject) {
/*
Put your custom logic here. The $releaseObject variable contains
the release data returned by the GitHub/GitLab API. The format
will vary depending on which service you're using.
*/
return true;
},
Api::RELEASE_FILTER_ALL
);
Api::RELEASE_FILTER_ALL, you can also use Api::RELEASE_FILTER_SKIP_PRERELEASE to filter out pre-releases.wp_strip_all_tags() instead of strip_tags() when available. Supposedly, it's better at stripping the contents of <script> and <style> tags.main branch is now treated as a default branch (in addition to master).Fixed a PHP deprecation notice: preg_match(): Passing null to parameter #2 ($subject) of type string is deprecated. It could be triggered if the updat…
use YahnisElsts\PluginUpdateChecker\v5\PucFactory;
$myUpdateChecker = PucFactory::buildUpdateChecker(
'https://example.com/info.json',
__FILE__,
'my-slug'
);
If you want to use version 5.0 specifically instead of "latest loaded 5.x version", replace v5 in the namespace with v5p0.readme.txt from a remote BitBucket remote repository to see if it has a Stable tag header that points to a valid tag. This makes it possible to avoid some unnecessary HTTP requests and may improve performance for your users. Example:use YahnisElsts\PluginUpdateChecker\v5p0\Vcs\BitBucketApi;
$bitbucketPluginChecker->addFilter('vcs_update_detection_strategies', function($strategies) {
//Don't look for a "Stable tag" header in readme.txt.
unset($strategies[BitBucketApi::STRATEGY_STABLE_TAG]);
return $strategies;
});
Different APIs support different strategies. Currently implemented strategies include:
STRATEGY_LATEST_RELEASESTRATEGY_LATEST_TAGSTRATEGY_STABLE_TAGSTRATEGY_BRANCHpreg_match(): Passing null to parameter #2 ($subject) of type string is deprecated. It could be triggered if the update metadata URL did not include a path.Switched from a deprecated GitHub API authentication mechanism that used the access_token query parameter to using the Authorization HTTP header. This…
access_token query parameter to using the Authorization HTTP header. This should stop GitHub sending you email notices about authentication via URL query parameters. Props to @jccit for the initial implementation.first_check_time (full name: puc_first_check_time-$slug). It's passed one argument that is the calculated Unix timestamp of the first update check. Return a new timestamp to make the first check happen at a different time.//Usage example:
$updateChecker->addFilter('first_check_time', function($unusedTimestamp) {
//Always check for updates 1 hour after the first activation.
return time() + 3600;
});
Fixed a fatal error that could happen when activating two plugins or themes that use Composer autoloaders and include different versions of this libra
major.minor (e.g. 5.2) and the site was running version major.minor.patch (e.g. 5.2.1). This complements an earlier patch where a similar warning was show on the "Updates" page.Finished upgrading to BitBucket API 2.0. This should fix the "this API is no longer supported" errors experienced by some users.
Added a puc_get_vcs_service filter that lets users add their self-hosted GitLab or BitBucket instance as a recognised service. Props to @Tofandel.
puc_get_vcs_service filter that lets users add their self-hosted GitLab or BitBucket instance as a recognised service. Props to @Tofandel.Puc_v4pX_Factory) wouldn't be able to instantiate any classes.Added support for GitLab subgroups.
readme-parser.php. Props to @Tofandel for one of the fixes.readme.txt section when it's empty.Added a way to show a plugin icon on the "Dashboard -> Updates" page. Usage: Add the following entry to your JSON file: `json "icons" : { "1x" : "http
"icons" : {
"1x" : "http://example.com/assets/icon-128x128.png",
"2x" : "http://example.com/assets/icon-256x256.png",
"svg": "http://example.com/assets/icon.svg"
}
See supported icon sizes and image formats.enableReleaseAssets() method of the GitHub API class.$gitHubUpdateChecker->getVcsApi()->enableReleaseAssets();
You can make PUC look for a specific asset by passing a regular expression to enableReleaseAssets(). For example, $api->enableReleaseAssets('/custom-asset/') will make PUC use the first asset where the file name contains the string "custom-asset".Added GitLab support. Props to @aaronkirkham.
puc_view_details_link-$slug filter. Return an empty string to remove the link.puc_view_details_link_position-$slug filter. Valid return values are "before", "after", "replace", and "append".readme.txt capitalisations. Most plugins use a lowercase name, but there are some that call this file README.txt or README.TXT. This was an issue when trying to retrieve the readme from a VCS repository.register_uninstall_hook().Added the GitHub API response to the Vcs_Reference instance as an $apiResponse property.
Vcs_Reference instance as an $apiResponse property.wp_remote_get().
request_metadata_http_resultadd_filter(): puc_request_metadata_http_result-$slug or puc_request_metadata_http_result_theme-$slug.$updateChecker->addFilter('request_metadata_http_result', function($response) {
return $response;
});
set_time_limit() being disabled. Changing the limit can be useful when you're on a slow network connection, but normally the library works fine with the default limits.Fixed a PHP warning when trying to load update details that were saved by a different version of PUC that had a custom namespace. This was a pre-exist
Added the ability to automatically load plugin banners from a local assets subdirectory. Props to @timwiel for the initial implementation.
assets subdirectory. Props to @timwiel for the initial implementation._).main branch will now be treated as a default branch (in addition to master).Fixed a few warnings about deprecated jQuery features.
lastRequestApiErrors property that could prevent certain update errors from being reported.Added support for the new auto-update feature introduced in WordPress 5.5.
buildFromHeader($filePath, $args) that lets you specify the repository URL in the plugin header and set other update checker arguments using an associative array. Example:/*
Plugin Name: Example Plugin
Description: Lorem ipsum
Version: 1.0
GitHub URI: https://github.com/foo/bar/
*/
//...
$updateChecker = Puc_v4p10_Factory::buildFromHeader(
__FILE__,
array(
'slug' => 'plugin-slug-here',
'checkPeriod' => 12,
'optionName' => 'abc-custom-option',
)
);
.999.Added support for the Composer autoloader.
php (PHP version) and locale (WordPress locale) to query parameters that are sent when checking for updates. This only applies to projects using JSON metadata.GitHub support: The setAccessToken() method was deprecated. Use setAuthentication('token_here') instead.
New features
Breaking changes
Renamed PucFactory to Puc_v4_Factory. Use Puc_v4_Factory::buildUpdateChecker() to initialize the update checker.
Renamed all classes to comply with the PSR-0 autoloading standard.
Changed how the factory deals with multiple versions of the library being loaded at the same time. Instead of simply choosing the highest available version, it now uses the highest minor version. For example, version 4.0 of the factory class can build version 4.5 or 4.9.1 instances, but not version 5.0. The goal of this change is to reduce the risk that future releases could accidentally break plugins that are using old versions of the library.
GitHub support: The class PucGitHubChecker_x_y was removed. Use Puc_v4_Factory::buildUpdateChecker() instead and pass the repository URL as the first argument. Example:
$updateChecker = Puc_v4_Factory::buildUpdateChecker(
'https://github.com/username/repository',
__FILE__
);
GitHub support: The setAccessToken() method was deprecated. Use setAuthentication('token_here') instead.
As part of theme support, the plugin info and update container classes were refactored and two base classes (Puc_v4_Metadata, Puc_v4_Update) were introduced. If your plugin extends the update class, review the changes to see if you need to update your code.
Minor changes
require.examples directory.add_filter() or add_action(). I recommend using the $updateChecker->addFilter() method instead which will automatically append the right suffix and slug.
puc_something-$slug.puc_something_theme-$slug.Fixed parsing of "= version =" headers in readme.txt.
WP_DEBUG is enabled. To prevent that, specify a unique slug when calling PucFactory::buildUpdateChecker or creating a PluginUpdateChecker instance.Added basic support for translation updates. This feature is also known as "language packs". See the "translations" entry in the supported field list
tested field to 4.5 or above.This release includes a few changes that break backwards compatibility. In practice, most plugins will not be affected.
Breaking changes
This release includes a few changes that break backwards compatibility. In practice, most plugins will not be affected.
PluginUpdateChecker, PluginUpdate and PluginInfo. Use the versioned class names instead, e.g. PluginUpdateChecker_3_0.$checkPeriod, $throttleRedundantChecks, $throttledCheckPeriod fields and the maybeCheckForUpdates() method from PluginUpdateChecker to a new class called PucScheduler.$triggerErrors parameter from the fromJson() method. Now the update checker will always trigger a PHP notice if your metadata file does not contain valid JSON or is missing a required key.Other changes
isPluginBeingUpgraded() method. It returns true if the plugin is being updated right now. This can be useful for plugins that hook into WordPress core to change how WordPress installs updates. Caution: The method is not guaranteed to be accurate.admin_url()/network_admin_url() with self_admin_url().debug-bar-plugin.php file is now optional. If you're not using Debug Bar, you can remove the file and the library will keep working. Previously it would crash if the file was missing.Fixed automatic directory renaming not working with the AJAX-based plugin update process that was introduced in WP 4.2.
Added an optional active_installs field. This should be an positive integer that indicates how many sites use your plugin. WordPress will show it in t
active_installs field. This should be an positive integer that indicates how many sites use your plugin. WordPress will show it in the "view version 1.2.3 details" pop-up. For example, if you set it to 10000, users will see "Active Installs: 10,000+".class_exists(). Apparently, some autoloader implementations will throw warnings or even crash if they get a class name that they can't load.Added experimental GitHub support. You can use the new PucGitHubChecker class to retrieve plugin updates from a GitHub repository. It can be configure
Added experimental GitHub support. You can use the new PucGitHubChecker class to retrieve plugin updates from a GitHub repository. It can be configured to check either the latest release, the latest tag, or a specific branch. It will automagically extract version details (description, changelog, etc) from a number of different locations - release description, plugin headers, readme.txt, changelog.md and more.
Added support for plugin banners. To use it, add a new key named "banners" to the metadata file. It should be a JSON object with two string properties: "low" and "high". "low" must be a fully qualified URL pointing to a 772x250 image (PNG or JPG). "high" must point to a 1544x500 image. Only one of "low" or "high" is required.
Example:
{
"banners" : {
"low" : "//example.com/assets/banner-772x250.png",
"high" : "//example.com/assets/banner-1544x500.png"
}
}
Fixed some duplicate HTML ids. See #26.
Added a workaround for situations where the currently installed version and the update package have different directory names. This can happen if you serve updates from a source like GitHub that generates different directory names for each branch/tag/etc.
The "slug" field of the metadata file is no longer used. The update checker will now ignore it and use the slug passed to the class constructor instead. If no slug is specified, it will generate a slug based on the plugin file name.
Fixed background updates not working for plugins using this library.
filename property to the PluginInfo and PluginUpdate classes. It contains the plugin file name relative to the plugins directory (equivalent to PluginUpdateChecker::pluginFile).WordPress has supported background plugin updates since WP 3.7. Previously automatic updates didn't work with PUC even if explicitly enabled. This release adds basic support for that WP feature.
Nothing published for this version
One column per quarter.