WooCommerce Code Reference

WC_Helper_Updater
in package

WooCommerce

Admin

Helper

WC_Helper_Updater Class

Contains the logic to fetch available updates and hook into Core's update routines to serve WooCommerce.com-provided packages.

CAMPAIGN_PLUGIN_ROW = 'pu_plugin_row': Prefix for the utm_campaign value of links in the notice row under an up-to-date plugin.
CAMPAIGN_UPDATE_ROW = 'pu_plugin_screen': Prefix for the utm_campaign value of links in the message appended to Core's update row.
add_connect_woocom_plugin_message() : void: Runs on in_plugin_update_message-{file-name}, show a message to connect to woocommerce.com for unconnected stores
add_hook_for_modifying_update_notices() : mixed: Add the hook for modifying default WPCore update notices on the plugins management page.
add_install_marketplace_plugin_message() : void: Runs on in_plugin_update_message-{file-name}, show a message to install the Woo Marketplace plugin, on plugin update notification, if the Woo Marketplace plugin isn't already installed.
block_expired_updates() : false|WP_Error: Hooked into the upgrader_pre_download filter in order to better handle error messaging around expired plugin updates. Initially we were using an empty string, but the error message that no_package results in does not fit the cause.
display_connect_notice_for_woo_plugins() : void: Runs on after_plugin_row, show a connect message on WooCommerce.com plugin rows that Core renders no update notice for.
display_notice_for_expired_and_expiring_subscriptions() : void: Runs on in_plugin_update_message-{file-name}, show a message if plugins subscription expired or expiring soon.
display_notice_for_plugins_without_subscription() : void: Runs on in_plugin_update_message-{file-name}, show a message if plugin is without a subscription.
display_subscription_notice_for_woo_plugins() : void: Runs on after_plugin_row, show a subscription message on WooCommerce.com plugin rows that Core renders no update notice for.
flush_updates_cache() : mixed: Flushes cached update data.
get_available_extensions_downloads_data() : array<string|int, mixed>: Get update data for all extensions, for the WP-CLI extension command.
get_translations_update_data() : array<string|int, mixed>: Get translations updates information.
get_update_data() : array<string|int, mixed>: Get update data for all extensions.
get_updates_count() : int: Get the number of products that have updates.
get_updates_count_based_on_site_status() : int: Get the update count to based on the status of the site.
get_updates_count_html() : string: Return the updates count markup.
get_woo_connect_notice_type() : string: Get the type of woo connect notice to be shown in the WC Settings and Marketplace pages.
load() : mixed: Loads the class, runs on init.
setup_message_for_expired_and_expiring_subscriptions() : mixed: Add the hook for modifying default WPCore update notices on the plugins management page.
setup_message_for_plugins_without_subscription() : mixed: Add the hook for modifying default WPCore update notices on the plugins management page.
setup_update_plugins_messages() : void: Runs on load-plugins.php, adds a hook to show a custom plugin update message for WooCommerce.com hosted plugins.
transient_update_plugins() : object: Runs in a cron thread, or in a visitor thread if triggered by _maybe_update_plugins(), or in an auto-update thread.
transient_update_themes() : object: Runs on pre_set_site_transient_update_themes, provides custom packages for WooCommerce.com-hosted extensions.
upgrader_process_complete() : mixed: Fires when a user successfully updated a theme or a plugin.
_update_check() : array<string|int, mixed>: Run an update check API call.
get_cached_products() : array<string|int, mixed>: Extract the products from a cached update-check payload.
get_connect_notice() : string: Message asking an unconnected store to connect to WooCommerce.com.
get_product_id_for_plugin_row_notice() : int: Product ID of the WooCommerce.com plugin a row notice applies to.
get_product_id_from_update_response() : int: Product ID carried by an update response WooCommerce wrote, or 0 for anything else.
get_product_page_url() : string: WooCommerce.com product page URL for a plugin, from the update data Core already holds.
get_product_page_url_from_update_response() : string: WooCommerce.com product page URL carried by an update response, or an empty string.
get_purchase_notice() : string: Message for a plugin whose product the connected account holds no subscription for.
get_renew_link() : string: Cart link that renews one specific subscription.
get_renewable_subscriptions() : array<string|int, mixed>: Expired and lapsing subscriptions for a product that the merchant should act on.
get_renewal_notice() : string: Message for a plugin whose subscription has expired or is lapsing.
get_subscription_notice() : string: Message for a product's subscription state, or an empty string when there is nothing to say.
get_subscriptions_for_product() : array<string|int, mixed>: Every subscription the account holds for a product.
get_update_check_payload() : array<string|int, mixed>: The products to ask WooCommerce.com about, with the file ID and installed version of each.
is_autoupdate_forced() : bool: Checks whether WooCommerce.com flagged this update to be installed automatically.
kses_notice() : string: Strip a notice down to text and a link with a class.
print_plugin_row_notice() : void: Print a notice row underneath a plugin row, styled like the update rows Core renders.
print_update_row_message() : void: Append a message to the update row Core renders for a plugin.
should_use_cached_update_data() : bool: Validates cached update data and checks if it matches the expected hash.

CAMPAIGN_PLUGIN_ROW

Prefix for the utm_campaign value of links in the notice row under an up-to-date plugin.


    private
    mixed
    CAMPAIGN_PLUGIN_ROW
    = 'pu_plugin_row'

CAMPAIGN_UPDATE_ROW

Prefix for the utm_campaign value of links in the message appended to Core's update row.


    private
    mixed
    CAMPAIGN_UPDATE_ROW
    = 'pu_plugin_screen'

add_connect_woocom_plugin_message()

Runs on in_plugin_update_message-{file-name}, show a message to connect to woocommerce.com for unconnected stores


    public
            static    add_connect_woocom_plugin_message() : void

Return values

void —

add_hook_for_modifying_update_notices()

Add the hook for modifying default WPCore update notices on the plugins management page.


    public
            static    add_hook_for_modifying_update_notices() : mixed

Return values

mixed —

add_install_marketplace_plugin_message()

Runs on in_plugin_update_message-{file-name}, show a message to install the Woo Marketplace plugin, on plugin update notification, if the Woo Marketplace plugin isn't already installed.


    public
            static    add_install_marketplace_plugin_message(object $plugin_data, object $response) : void

Parameters

$plugin_data : object: TAn array of plugin metadata.
$response : object: An object of metadata about the available plugin update.

Return values

void —

block_expired_updates()

Hooked into the upgrader_pre_download filter in order to better handle error messaging around expired plugin updates. Initially we were using an empty string, but the error message that no_package results in does not fit the cause.


    public
            static    block_expired_updates(bool $reply, string $package) : false|WP_Error

Parameters

$reply : bool: Holds the current filtered response.
$package : string: The path to the package file for the update.

Return values

false|WP_Error — False to proceed with the update as normal, anything else to be returned instead of updating.

display_connect_notice_for_woo_plugins()

Runs on after_plugin_row, show a connect message on WooCommerce.com plugin rows that Core renders no update notice for.


    public
            static    display_connect_notice_for_woo_plugins(string $plugin_file, array<string|int, mixed> $plugin_data) : void

Core only renders its update row -- and with it the message appended by add_connect_woocom_plugin_message() -- when an update is pending, so an up-to-date plugin gives an unconnected store no indication that it won't receive updates.

Parameters

$plugin_file : string: Path to the plugin file relative to the plugins directory.
$plugin_data : array<string|int, mixed>: An array of plugin metadata.

Return values

void —

display_notice_for_expired_and_expiring_subscriptions()

Runs on in_plugin_update_message-{file-name}, show a message if plugins subscription expired or expiring soon.


    public
            static    display_notice_for_expired_and_expiring_subscriptions(object $plugin_data, object $response) : void

Parameters

$plugin_data : object: An array of plugin metadata.
$response : object: An object of metadata about the available plugin update.

Return values

void —

display_notice_for_plugins_without_subscription()

Runs on in_plugin_update_message-{file-name}, show a message if plugin is without a subscription.


    public
            static    display_notice_for_plugins_without_subscription(object $plugin_data, object $response) : void

Only Woo local plugins are passed to this function.

Parameters

$plugin_data : object: An array of plugin metadata.
$response : object: An object of metadata about the available plugin update.

Return values

void —

display_subscription_notice_for_woo_plugins()

Runs on after_plugin_row, show a subscription message on WooCommerce.com plugin rows that Core renders no update notice for.


    public
            static    display_subscription_notice_for_woo_plugins(string $plugin_file, array<string|int, mixed> $plugin_data) : void

Rows that do have an update are covered by the in_plugin_update_message-{file-name} handlers. Without one, a plugin whose subscription is missing, expired, or lapsing says nothing at all.

Parameters

$plugin_file : string: Path to the plugin file relative to the plugins directory.
$plugin_data : array<string|int, mixed>: An array of plugin metadata.

Return values

void —

flush_updates_cache()

Flushes cached update data.


    public
            static    flush_updates_cache() : mixed

Return values

mixed —

get_available_extensions_downloads_data()

Get update data for all extensions, for the WP-CLI extension command.


    public
            static    get_available_extensions_downloads_data() : array<string|int, mixed>

Sends the same payload as get_update_data(), so both share one cached response and report the same installed versions.

Return values

array<string|int, mixed> — Update data {product_id => data}

get_translations_update_data()

Get translations updates information.


    public
            static    get_translations_update_data() : array<string|int, mixed>

Scans through all subscriptions for the connected user, as well as all Woo extensions without a subscription, and obtains update data for each product.

Return values

array<string|int, mixed> — Update data {product_id => data}

get_update_data()

Get update data for all extensions.


    public
            static    get_update_data() : array<string|int, mixed>

Scans through all subscriptions for the connected user, as well as all Woo extensions without a subscription, and obtains update data for each product.

Return values

array<string|int, mixed> — Update data {product_id => data}

get_updates_count()

Get the number of products that have updates.


    public
            static    get_updates_count() : int

Return values

int — The number of products with updates.

get_updates_count_based_on_site_status()

Get the update count to based on the status of the site.


    public
            static    get_updates_count_based_on_site_status() : int

Return values

int —

get_updates_count_html()

Return the updates count markup.


    public
            static    get_updates_count_html() : string

Return values

string — Updates count markup, empty string if no updates avairable.

get_woo_connect_notice_type()

Get the type of woo connect notice to be shown in the WC Settings and Marketplace pages.


    public
            static    get_woo_connect_notice_type() : string

If a store is connected to woocommerce.com or has no installed woo plugins, return 'none'.
If a store has installed woo plugins but no updates, return 'short'.
If a store has an installed woo plugin with update, return 'long'.

Return values

string — The notice type, 'none', 'short', or 'long'.

load()

Loads the class, runs on init.


    public
            static    load() : mixed

Return values

mixed —

setup_message_for_expired_and_expiring_subscriptions()

Add the hook for modifying default WPCore update notices on the plugins management page.


    public
            static    setup_message_for_expired_and_expiring_subscriptions() : mixed

This is for plugins with expired or expiring subscriptions.

Return values

mixed —

setup_message_for_plugins_without_subscription()

Add the hook for modifying default WPCore update notices on the plugins management page.


    public
            static    setup_message_for_plugins_without_subscription() : mixed

This is for plugins without a subscription.

Return values

mixed —

setup_update_plugins_messages()

Runs on load-plugins.php, adds a hook to show a custom plugin update message for WooCommerce.com hosted plugins.


    public
            static    setup_update_plugins_messages() : void

Return values

void —

transient_update_plugins()

Runs in a cron thread, or in a visitor thread if triggered by _maybe_update_plugins(), or in an auto-update thread.


    public
            static    transient_update_plugins(object $transient) : object

Parameters

$transient : object: The update_plugins transient object.

Return values

object — The same or a modified version of the transient.

transient_update_themes()

Runs on pre_set_site_transient_update_themes, provides custom packages for WooCommerce.com-hosted extensions.


    public
            static    transient_update_themes(object $transient) : object

Parameters

$transient : object: The update_themes transient object.

Return values

object — The same or a modified version of the transient.

upgrader_process_complete()

Fires when a user successfully updated a theme or a plugin.


    public
            static    upgrader_process_complete() : mixed

Return values

mixed —

_update_check()

Run an update check API call.


    private
            static    _update_check(array<string|int, mixed> $payload) : array<string|int, mixed>

The call is cached based on the payload (product ids, file ids, installed versions). If the payload changes, the cache is going to miss. The installed version has to be part of the key: the server decides the autoupdate flag from it, so a response cached under another version, after an update or a rollback, would carry a decision made for a build that is no longer installed.

Parameters

$payload : array<string|int, mixed>: Information about the plugin to update.

Return values

array<string|int, mixed> — Update data for each requested product.

get_cached_products()

Extract the products from a cached update-check payload.


    private
            static    get_cached_products(mixed $data) : array<string|int, mixed>

Used on the paths that serve the previous cache rather than a fresh response — while rate limited, and on the rate-limited response itself.

Parameters

$data : mixed: The data retrieved from the transient, of any shape.

Return values

array<string|int, mixed> — The cached products, or an empty array when there are none.

get_connect_notice()

Message asking an unconnected store to connect to WooCommerce.com.


    private
            static    get_connect_notice(string $campaign_prefix) : string

Parameters

$campaign_prefix : string: Prefix for the link's utm_campaign value.

Return values

string —

get_product_id_for_plugin_row_notice()

Product ID of the WooCommerce.com plugin a row notice applies to.


    private
            static    get_product_id_for_plugin_row_notice(string $plugin_file, array<string|int, mixed> $plugin_data) : int

Returns 0 when the row should get no notice: the plugin isn't WooCommerce.com hosted, the screen is one Core renders no update rows on, or Core already renders an update row for it, which the in_plugin_update_message-{file-name} handlers append their own message to.

Parameters

$plugin_file : string: Path to the plugin file relative to the plugins directory.
$plugin_data : array<string|int, mixed>: An array of plugin metadata.

Return values

int —

get_product_id_from_update_response()

Product ID carried by an update response WooCommerce wrote, or 0 for anything else.


    private
            static    get_product_id_from_update_response(mixed $response) : int

The updater sets the ID to "woocommerce-com-". A filter can replace the response, so anything that does not match exactly is treated as not ours rather than having its digits scraped out.

Parameters

$response : mixed: Update response from the update_plugins transient.

Return values

int —

get_product_page_url()

WooCommerce.com product page URL for a plugin, from the update data Core already holds.


    private
            static    get_product_page_url(string $plugin_file) : string

Parameters

$plugin_file : string: Path to the plugin file relative to the plugins directory.

Return values

string — The product page URL, or an empty string when the update data carries none.

get_product_page_url_from_update_response()

WooCommerce.com product page URL carried by an update response, or an empty string.


    private
            static    get_product_page_url_from_update_response(mixed $response) : string

Parameters

$response : mixed: Update response from the update_plugins transient.

Return values

string —

get_purchase_notice()

Message for a plugin whose product the connected account holds no subscription for.


    private
            static    get_purchase_notice(int $product_id, string $product_page_url, string $campaign_prefix) : string

Links to the product page so the reader can see what a subscription covers before buying. Falls back to the cart when the update data carries no product URL.

Parameters

$product_id : int: WooCommerce.com product ID.
$product_page_url : string: WooCommerce.com product page URL, or an empty string.
$campaign_prefix : string: Prefix for the link's utm_campaign value.

Return values

string —

get_renew_link()

Cart link that renews one specific subscription.


    private
            static    get_renew_link(array<string|int, mixed> $subscription, string $campaign) : string

A plain add-to-cart link would buy a new subscription instead. This is the same link the My Subscriptions screen and the product usage notice use. Renewing needs the product key and the order ID; a record missing either gets the add-to-cart link, which still works.

Parameters

$subscription : array<string|int, mixed>: Subscription record from the WooCommerce.com API.
$campaign : string: utm_campaign value for the link.

Return values

string —

get_renewable_subscriptions()

Expired and lapsing subscriptions for a product that the merchant should act on.


    private
            static    get_renewable_subscriptions(array<string|int, mixed> $subscriptions) : array<string|int, mixed>

Every subscription the account holds for the product counts, wherever it is connected, because renewing and buying can be done from any store. Nothing is returned while another subscription still covers the product, so a store that keeps its updates stays quiet.

Parameters

$subscriptions : array<string|int, mixed>: Every subscription the account holds for the product.

Return values

array<string|int, mixed> — A pair of subscriptions, each an array or false: the expired one, then the lapsing one without auto-renew.

get_renewal_notice()

Message for a plugin whose subscription has expired or is lapsing.


    private
            static    get_renewal_notice(array<string|int, mixed> $subscriptions, string $campaign_prefix) : string

Returns an empty string for a subscription that needs no action.

Parameters

$subscriptions : array<string|int, mixed>: Every subscription the account holds for the product.
$campaign_prefix : string: Prefix for the link's utm_campaign value.

Return values

string —

get_subscription_notice()

Message for a product's subscription state, or an empty string when there is nothing to say.


    private
            static    get_subscription_notice(int $product_id, string $product_page_url, string $campaign_prefix) : string

Resolves the product's subscriptions once and hands them to whichever message needs them, so a screen full of WooCommerce.com plugins doesn't filter the whole list twice per row.

Parameters

$product_id : int: WooCommerce.com product ID.
$product_page_url : string: WooCommerce.com product page URL, or an empty string.
$campaign_prefix : string: Prefix for the link's utm_campaign value.

Return values

string —

get_subscriptions_for_product()

Every subscription the account holds for a product.


    private
            static    get_subscriptions_for_product(int $product_id) : array<string|int, mixed>

Read straight from get_subscriptions() so the per-request static caches in get_installed_subscriptions() and get_unconnected_subscriptions() don't pin the first result for the rest of the request.

Parameters

$product_id : int: WooCommerce.com product ID.

Return values

array<string|int, mixed> —

get_update_check_payload()

The products to ask WooCommerce.com about, with the file ID and installed version of each.


    private
            static    get_update_check_payload() : array<string|int, mixed>

Covers every subscription plus every installed plugin and theme carrying a Woo header, whether or not it has a subscription. Every caller has to send the same payload: the server decides the autoupdate flag from the installed version, and the response is cached under a hash of the payload.

Return values

array<string|int, mixed> — Payload keyed by product ID.

is_autoupdate_forced()

Checks whether WooCommerce.com flagged this update to be installed automatically.


    private
            static    is_autoupdate_forced(array<string|int, mixed> $data, array<string|int, mixed> $item) : bool

Uses core's own autoupdate flag, the same one api.wordpress.org sets on WordPress.org plugins, so these updates follow the same path through WP_Automatic_Updater::should_update(). The flag overrides the per-item setting and the site-wide plugins_auto_update_enabled and themes_auto_update_enabled switches. AUTOMATIC_UPDATER_DISABLED, disable_autoupdate and the auto_update_plugin and auto_update_theme filters still apply.

The package checks are required: forcing an update that cannot be installed, either because no package was supplied or because the subscription expired, only produces a failed update email to every admin on the site.

Parameters

$data : array<string|int, mixed>: Product data returned by the Helper API update check.
$item : array<string|int, mixed>: Update item built for the update transient.

Return values

bool —

kses_notice()

Strip a notice down to text and a link with a class.


    private
            static    kses_notice(string $notice) : string

Parameters

$notice : string: The notice HTML.

Return values

string —

print_plugin_row_notice()

Print a notice row underneath a plugin row, styled like the update rows Core renders.


    private
            static    print_plugin_row_notice(string $plugin_file, string $row_type, string $notice) : void

Parameters

$plugin_file : string: Path to the plugin file relative to the plugins directory.
$row_type : string: Value for the data-plugin-row-type attribute.
$notice : string: The notice text, which may contain a single link.

Return values

void —

print_update_row_message()

Append a message to the update row Core renders for a plugin.


    private
            static    print_update_row_message(string $notice) : void

Core has already printed its own sentence, so the message is preceded by a space.

Parameters

$notice : string: The notice text, which may contain a single link.

Return values

void —

should_use_cached_update_data()

Validates cached update data and checks if it matches the expected hash.


    private
            static    should_use_cached_update_data(mixed $data, string $hash) : bool

Ensures the cached data is properly structured and corresponds to the current payload to prevent fatal errors and avoid stale cache returns.

Parameters

$data : mixed: The data retrieved from the transient.
$hash : string: The expected hash to compare against.

Return values

bool — True if the data is valid and hash matches, false otherwise.

WC_Helper_Updater in package WooCommerce Admin Helper

Table of Contents

Constants

CAMPAIGN_PLUGIN_ROW

CAMPAIGN_UPDATE_ROW

Methods

add_connect_woocom_plugin_message()

Return values

add_hook_for_modifying_update_notices()

Return values

add_install_marketplace_plugin_message()

Parameters

Return values

block_expired_updates()

Parameters

Tags

Return values

display_connect_notice_for_woo_plugins()

Parameters

Tags

Return values

display_notice_for_expired_and_expiring_subscriptions()

Parameters

Return values

display_notice_for_plugins_without_subscription()

Parameters

Tags

Return values

display_subscription_notice_for_woo_plugins()

Parameters

Tags

Return values

flush_updates_cache()

Return values

get_available_extensions_downloads_data()

Tags

Return values

get_translations_update_data()

Return values

get_update_data()

Return values

get_updates_count()

Return values

get_updates_count_based_on_site_status()

Return values

get_updates_count_html()

Return values

get_woo_connect_notice_type()

Return values

load()

Return values

setup_message_for_expired_and_expiring_subscriptions()

Return values

setup_message_for_plugins_without_subscription()

Return values

setup_update_plugins_messages()

Return values

transient_update_plugins()

Parameters

Return values

transient_update_themes()

Parameters

Return values

upgrader_process_complete()

Return values

_update_check()

Parameters

Return values

get_cached_products()

Parameters

Return values

get_connect_notice()

Parameters

Tags

Return values

get_product_id_for_plugin_row_notice()

Parameters

Tags

Return values

get_product_id_from_update_response()

WC_Helper_Updater
in package

WooCommerce

Admin

Helper