Properties

$metadataUrl

$metadataUrl : 

Type

$pluginAbsolutePath

$pluginAbsolutePath : 

Type

$pluginFile

$pluginFile : 

Type

$slug

$slug : 

Type

$checkPeriod

$checkPeriod : 

Type

$optionName

$optionName : 

Type

$muPluginFile

$muPluginFile : 

Type

$debugMode

$debugMode : 

Type

$throttleRedundantChecks

$throttleRedundantChecks : 

Type

$throttledCheckPeriod

$throttledCheckPeriod : 

Type

$license

$license : 

Type

$remoteGetTimeout

$remoteGetTimeout : 

Type

$collectAnalytics

$collectAnalytics : 

Type

$licenseErrorMessage

$licenseErrorMessage : 

Type

$cronHook

$cronHook : 

Type

$debugBarPlugin

$debugBarPlugin : 

Type

$cachedInstalledVersion

$cachedInstalledVersion : 

Type

Methods

__construct()

__construct(string  $metadataUrl, string  $pluginFile, string  $slug = '', integer  $checkPeriod = 12,   $pluginName = '', string  $optionName = '', string  $muPluginFile = '') 

Class constructor.

Parameters

string $metadataUrl

The URL of the plugin's metadata file.

string $pluginFile

Fully qualified path to the main plugin file.

string $slug

The plugin's 'slug'. If not specified, the filename part of $pluginFile sans '.php' will be used as the slug.

integer $checkPeriod

How often to check for updates (in hours). Defaults to checking every 12 hours. Set to 0 to disable automatic update checks.

$pluginName
string $optionName

Where to store book-keeping info about update checks. Defaults to 'external_updates-$slug'.

string $muPluginFile

Optional. The plugin filename relative to the mu-plugins directory.

_addCustomSchedule()

_addCustomSchedule(array  $schedules) : array

Add our custom schedule to the array of Cron schedules used by WP.

Parameters

array $schedules

Returns

array

_removeUpdaterCron()

_removeUpdaterCron() : void

Remove the scheduled cron event that the library uses to check for updates.

getCronHookName()

getCronHookName() : string

Get the name of the update checker's WP-cron hook. Mostly useful for debugging.

Returns

string

requestInfo()

requestInfo(array  $queryArgs = array()) : \PluginInfo

Retrieve plugin info from the configured API endpoint.

Parameters

array $queryArgs

Additional query arguments to append to the request. Optional.

Returns

\PluginInfo

getPluginName()

getPluginName() 

license_invalid_notice()

license_invalid_notice() 

requestUpdate()

requestUpdate() : \PluginUpdate

Retrieve the latest update (if any) from the configured API endpoint.

Returns

\PluginUpdate

An instance of PluginUpdate, or NULL when no updates are available.

getInstalledVersion()

getInstalledVersion() : string

Get the currently installed version of the plugin.

Returns

string —

Version number.

checkForUpdates()

checkForUpdates() : \PluginUpdate|null

Check for plugin updates.

The results are stored in the DB option specified in $optionName.

Returns

\PluginUpdate|null

maybeCheckForUpdates()

maybeCheckForUpdates() 

Check for updates if the configured check interval has already elapsed.

Will use a shorter check interval on certain admin pages like "Dashboard -> Updates" or when doing cron.

You can override the default behaviour by using the "puc_check_now-$slug" filter. The filter callback will be passed three parameters:

  • Current decision. TRUE = check updates now, FALSE = don't check now.
  • Last check time as a Unix timestamp.
  • Configured check period in hours. Return TRUE to check for updates immediately, or FALSE to cancel.

This method is declared public because it's a hook callback. Calling it directly is not recommended.

getUpdateState()

getUpdateState() : \StdClass|null

Load the update checker state from the DB.

Returns

\StdClass|null

resetUpdateState()

resetUpdateState() 

Reset update checker state - i.e. last check time, cached update data and so on.

Call this when your plugin is being uninstalled, or if you want to clear the update cache.

injectInfo()

injectInfo(mixed  $result, string  $action = null, array|object  $args = null) : mixed

Intercept plugins_api() calls that request information about our plugin and use the configured API endpoint to satisfy them.

Parameters

mixed $result
string $action
array|object $args

Returns

mixed

injectUpdate()

injectUpdate(\StdClass  $updates) : \StdClass

Insert the latest update (if any) into the update list maintained by WP.

Parameters

\StdClass $updates

Update list.

Returns

\StdClass —

Modified update list.

fixDirectoryName()

fixDirectoryName(string  $source, string  $remoteSource, \WP_Upgrader  $upgrader) : string|\WP_Error

Rename the update directory to match the existing plugin directory.

When WordPress installs a plugin or theme update, it assumes that the ZIP file will contain exactly one directory, and that the directory name will be the same as the directory where the plugin/theme is currently installed.

GitHub and other repositories provide ZIP downloads, but they often use directory names like "project-branch" or "project-tag-hash". We need to change the name to the actual plugin folder.

Parameters

string $source

The directory to copy to /wp-content/plugins. Usually a subdirectory of $remoteSource.

string $remoteSource

WordPress has extracted the update to this directory.

\WP_Upgrader $upgrader

Returns

string|\WP_Error

getUpdate()

getUpdate() : \PluginUpdate|null

Get the details of the currently available update, if any.

If no updates are available, or if the last known update version is below or equal to the currently installed version, this method will return NULL.

Uses cached update data. To retrieve update information straight from the metadata URL, call requestUpdate() instead.

Returns

\PluginUpdate|null

addCheckForUpdatesLink()

addCheckForUpdatesLink(array  $pluginMeta, string  $pluginFile) : array

Add a "Check for updates" link to the plugin row in the "Plugins" page. By default, the new link will appear after the "Visit plugin site" link.

You can change the link text by using the "puc_manual_check_link-$slug" filter. Returning an empty string from the filter will disable the link.

Parameters

array $pluginMeta

Array of meta links.

string $pluginFile

Returns

array

handleManualCheck()

handleManualCheck() : void

Check for updates when the user clicks the "Check for updates" link.

displayManualCheckResult()

displayManualCheckResult() 

Display the results of a manual update check.

clearCachedVersion()

clearCachedVersion(mixed  $filterArgument = null) : mixed

Clear the cached plugin version. This method can be set up as a filter (hook) and will return the filter argument unmodified.

Parameters

mixed $filterArgument

Returns

mixed

addQueryArgFilter()

addQueryArgFilter(callable  $callback) : void

Register a callback for filtering query arguments.

The callback function should take one argument - an associative array of query arguments. It should return a modified array of query arguments.

Parameters

callable $callback

addHttpRequestArgFilter()

addHttpRequestArgFilter(callable  $callback) : void

Register a callback for filtering arguments passed to wp_remote_get().

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 on what arguments are available and how they work.

Parameters

callable $callback

addResultFilter()

addResultFilter(callable  $callback) : void

Register a callback for filtering the plugin info retrieved from the external API.

The callback function should take two arguments. If the plugin info was retrieved successfully, the first argument passed will be an instance of PluginInfo. 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.

Parameters

callable $callback

addFilter()

addFilter(string  $tag, callable  $callback, integer  $priority = 10, integer  $acceptedArgs = 1) 

Register a callback for one of the update checker filters.

Identical to addfilter(), except it automatically adds the "puc" prefix and the "-$plugin_slug" suffix to the filter name. For example, "request_info_result" becomes "puc_request_info_result-your_plugin_slug".

Parameters

string $tag
callable $callback
integer $priority
integer $acceptedArgs

initDebugBarPanel()

initDebugBarPanel() 

Initialize the update checker Debug Bar plugin/add-on thingy.

installHooks()

installHooks() : void

Install the hooks required to run periodic update checks and inject update info into WP data structures.

getPluginHeader()

getPluginHeader() : array

Get plugin's metadata from its file header.

Returns

array

isMuPlugin()

isMuPlugin() : boolean

Check if the plugin file is inside the mu-plugins directory.

Returns

boolean

setUpdateState()

setUpdateState(\StdClass  $state) : void

Persist the update checker state to the DB.

Parameters

\StdClass $state