Commit f0433800339 for woocommerce

commit f0433800339448d684ca79ab4dd3af2d6428cbaa
Author: Thilina Pituwala <thilina.hasantha@gmail.com>
Date:   Thu Nov 19 12:09:31 2026 +1100

    Skip auto-updates for extension versions that need a newer WordPress (#70843)

    * Skip auto-updates for extension versions that need a newer WordPress

    WordPress's auto-updater checks only requires_php, and the single-item
    upgrade it runs skips the requirement check, so an auto or forced update
    installed a WooCommerce.com extension version the site can't run and left
    it active. Pass the update check's requires into the update entries, skip
    auto-updates whose WordPress requirement isn't met, and say which version
    is needed in the plugin update row, which core doesn't do for plugins.

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Grant super admin to the administrator fixture on multisite

    On multisite only super admins have update_core, so the administrator
    case of test_update_row_explains_update_needing_newer_wp didn't get the
    Update WordPress link and failed. Sitemeta writes roll back with the
    test transaction, so no revoke is needed.

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Stop single-item updates that need a newer WordPress

    Core checks an update's WordPress requirement only in bulk_upgrade().
    The "update now" link's URL runs Plugin_Upgrader::upgrade(), which skips
    it, so opening the link in a new tab installed a version WordPress then
    refused to activate. Return an error from upgrader_pre_download for
    WooCommerce.com plugin and theme updates whose requirement isn't met,
    which covers every update path and keeps the package for #69818.

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Accept pre-release suffixes in an update's WordPress requirement

    A requires value like 7.2-RC1 failed the version check and counted as
    no requirement, so the update went ahead and WordPress then refused to
    activate it. Core's is_wp_version_compatible() compares these correctly,
    so pass them through.

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Check an update's WordPress requirement in one place

    The auto-update skip, the plugin row notice and the pre-download guard
    each read the requirement and compared it to the site's version. Move
    that into get_unmet_wp_requirement(), and drop the empty-string check
    is_wp_version_compatible() already covers.

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Check an update's WordPress requirement before other download callbacks

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Return the WordPress requirement error as plain text

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    ---------

    Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
    Co-authored-by: Herman <KokkieH@users.noreply.github.com>

diff --git a/plugins/woocommerce/changelog/wccom-3193-skip-updates-needing-newer-wp b/plugins/woocommerce/changelog/wccom-3193-skip-updates-needing-newer-wp
new file mode 100644
index 00000000000..7264866c666
--- /dev/null
+++ b/plugins/woocommerce/changelog/wccom-3193-skip-updates-needing-newer-wp
@@ -0,0 +1,4 @@
+Significance: patch
+Type: fix
+
+Stop WooCommerce.com extension updates that need a newer WordPress from installing, and say which version an update needs.
diff --git a/plugins/woocommerce/includes/admin/helper/class-wc-helper-updater.php b/plugins/woocommerce/includes/admin/helper/class-wc-helper-updater.php
index 527cf469109..3c621f58562 100644
--- a/plugins/woocommerce/includes/admin/helper/class-wc-helper-updater.php
+++ b/plugins/woocommerce/includes/admin/helper/class-wc-helper-updater.php
@@ -38,7 +38,12 @@ class WC_Helper_Updater {
 		add_action( 'pre_set_site_transient_update_themes', array( __CLASS__, 'transient_update_themes' ), 21, 1 );
 		add_action( 'upgrader_process_complete', array( __CLASS__, 'upgrader_process_complete' ) );
 		add_action( 'upgrader_pre_download', array( __CLASS__, 'block_expired_updates' ), 10, 2 );
+		// Runs first, so a callback that serves the package can't install the update before this check.
+		add_filter( 'upgrader_pre_download', array( __CLASS__, 'block_update_needing_newer_wp' ), 1, 4 );
 		add_action( 'admin_init', array( __CLASS__, 'add_hook_for_modifying_update_notices' ) );
+		// Late, so another callback can't switch the update back on.
+		add_filter( 'auto_update_plugin', array( __CLASS__, 'skip_auto_update_needing_newer_wp' ), PHP_INT_MAX, 2 );
+		add_filter( 'auto_update_theme', array( __CLASS__, 'skip_auto_update_needing_newer_wp' ), PHP_INT_MAX, 2 );
 	}

 	/**
@@ -48,6 +53,7 @@ class WC_Helper_Updater {
 		if ( ! WC_Woo_Update_Manager_Plugin::is_plugin_active() || ! WC_Helper::is_site_connected() ) {
 			add_action( 'load-plugins.php', array( __CLASS__, 'setup_update_plugins_messages' ), 11 );
 		}
+		add_action( 'load-plugins.php', array( __CLASS__, 'setup_message_for_updates_needing_newer_wp' ), 11 );
 		if ( WC_Helper::is_site_connected() ) {
 			add_action( 'load-plugins.php', array( __CLASS__, 'setup_message_for_expired_and_expiring_subscriptions' ), 11 );
 			add_action( 'load-plugins.php', array( __CLASS__, 'setup_message_for_plugins_without_subscription' ), 11 );
@@ -67,6 +73,18 @@ class WC_Helper_Updater {
 		}
 	}

+	/**
+	 * Add the hook for modifying default WPCore update notices on the plugins management page.
+	 * This is for updates that need a newer WordPress than the site runs.
+	 *
+	 * @since 11.4.0
+	 */
+	public static function setup_message_for_updates_needing_newer_wp(): void {
+		foreach ( WC_Helper::get_local_woo_plugins() as $plugin ) {
+			add_action( 'in_plugin_update_message-' . $plugin['_filename'], array( __CLASS__, 'display_notice_for_update_needing_newer_wp' ), 10, 2 );
+		}
+	}
+
 	/**
 	 * Add the hook for modifying default WPCore update notices on the plugins management page.
 	 * This is for plugins without a subscription.
@@ -125,6 +143,11 @@ class WC_Helper_Updater {
 				$item['requires_php'] = $data['requires_php'];
 			}

+			$requires = self::get_required_wp_version( $data );
+			if ( '' !== $requires ) {
+				$item['requires'] = $requires;
+			}
+
 			if ( isset( $data['tested'] ) ) {
 				$item['tested'] = $data['tested'];
 			}
@@ -193,6 +216,12 @@ class WC_Helper_Updater {
 				$item['requires_php'] = $data['requires_php'];
 			}

+			// Core's theme update row and Updates screen read this and withhold the update.
+			$requires = self::get_required_wp_version( $data );
+			if ( '' !== $requires ) {
+				$item['requires'] = $requires;
+			}
+
 			if ( self::is_autoupdate_forced( $data, $item ) ) {
 				$item['autoupdate'] = true;
 			}
@@ -240,6 +269,139 @@ class WC_Helper_Updater {
 		return 0 !== strpos( $item['package'], 'woocommerce-com-expired-' );
 	}

+	/**
+	 * Gets the minimum WordPress version an update needs, from an update-check product or an update offer.
+	 *
+	 * The value arrives from a remote response or from a filtered update offer, so anything that
+	 * isn't a version number, optionally with a pre-release suffix such as -RC1, is treated as no requirement.
+	 *
+	 * @since 11.4.0
+	 * @param array $data Update-check product data, or an update offer cast to an array.
+	 * @return string The version, or an empty string when there is none.
+	 */
+	private static function get_required_wp_version( $data ): string {
+		$requires = is_array( $data ) ? ( $data['requires'] ?? null ) : null;
+
+		if ( ! is_string( $requires ) && ! is_int( $requires ) && ! is_float( $requires ) ) {
+			return '';
+		}
+
+		$requires = trim( (string) $requires );
+
+		return 1 === preg_match( '/^\d+(\.\d+){0,3}(-[0-9A-Za-z.]+)?$/', $requires ) ? $requires : '';
+	}
+
+	/**
+	 * Gets the WordPress version an update offer needs, when the site runs an older one.
+	 *
+	 * @since 11.4.0
+	 * @param mixed $offer The update offer: an object for plugins, an array for themes.
+	 * @return string The version the site doesn't meet, or an empty string when it meets the requirement or there is none.
+	 */
+	private static function get_unmet_wp_requirement( $offer ): string {
+		$requires = self::get_required_wp_version( is_object( $offer ) ? get_object_vars( $offer ) : $offer );
+
+		return is_wp_version_compatible( $requires ) ? '' : $requires;
+	}
+
+	/**
+	 * Skips an automatic update to a WooCommerce.com extension version that needs a newer WordPress.
+	 *
+	 * Core's auto-updater checks only the PHP requirement, and the single-item upgrade it runs skips
+	 * the requirement check a manual update gets. Without this, an auto-update or a forced update
+	 * installs a version the site can't run, and leaves it active.
+	 *
+	 * @since 11.4.0
+	 * @param bool|null $update Whether to update the item.
+	 * @param mixed     $item   The update offer.
+	 * @return bool|null False when the update needs a newer WordPress, otherwise $update unchanged.
+	 */
+	public static function skip_auto_update_needing_newer_wp( $update, $item ) {
+		// Only turn an update off, so a null "not decided" stays null for core's settings screens.
+		if ( ! $update || ! is_object( $item ) ) {
+			return $update;
+		}
+
+		if ( '' === self::get_unmet_wp_requirement( $item ) ) {
+			return $update;
+		}
+
+		return self::is_woo_update_offer( $item ) ? false : $update;
+	}
+
+	/**
+	 * Checks whether an update offer is for a locally installed WooCommerce.com extension.
+	 *
+	 * @since 11.4.0
+	 * @param object $item The update offer.
+	 * @return bool
+	 */
+	private static function is_woo_update_offer( $item ): bool {
+		if ( isset( $item->plugin ) && is_string( $item->plugin ) ) {
+			return array_key_exists( $item->plugin, WC_Helper::get_local_woo_plugins() );
+		}
+
+		if ( isset( $item->theme ) && is_string( $item->theme ) ) {
+			return in_array( $item->theme, wp_list_pluck( WC_Helper::get_local_woo_themes(), '_stylesheet' ), true );
+		}
+
+		return false;
+	}
+
+	/**
+	 * Runs on in_plugin_update_message-{file-name}, explains that an update needs a newer WordPress.
+	 *
+	 * Core's plugin update row only reads the PHP requirement, so it offers "update now" for a
+	 * version that will fail to install.
+	 *
+	 * @since 11.4.0
+	 * @param array  $plugin_data An array of plugin metadata.
+	 * @param object $response    An object of metadata about the available plugin update.
+	 * @return void
+	 */
+	public static function display_notice_for_update_needing_newer_wp( $plugin_data, $response ) {
+		$requires = self::get_unmet_wp_requirement( $response );
+		if ( '' === $requires ) {
+			return;
+		}
+
+		self::print_update_row_message( self::get_wp_requirement_notice( $requires ) );
+	}
+
+	/**
+	 * Message saying an update needs a newer WordPress, telling users who can update it to do so first.
+	 *
+	 * The HTML version links to the WordPress Updates screen. The plain-text version is for errors,
+	 * which callers may show as text.
+	 *
+	 * @since 11.4.0
+	 * @param string $requires The minimum WordPress version the update needs.
+	 * @param bool   $as_html  Whether to return HTML with a link, or plain text.
+	 * @return string
+	 */
+	private static function get_wp_requirement_notice( string $requires, bool $as_html = true ): string {
+		$notice = sprintf(
+			/* translators: 1: WordPress version the update needs, 2: WordPress version the site runs. */
+			__( 'This update needs WordPress %1$s or later, and this site runs WordPress %2$s.', 'woocommerce' ),
+			$as_html ? esc_html( $requires ) : $requires,
+			$as_html ? esc_html( wp_get_wp_version() ) : wp_get_wp_version()
+		);
+
+		if ( ! current_user_can( 'update_core' ) ) {
+			return $notice;
+		}
+
+		if ( ! $as_html ) {
+			return $notice . ' ' . __( 'Update WordPress first.', 'woocommerce' );
+		}
+
+		return $notice . ' ' . sprintf(
+			/* translators: %s: URL of the WordPress Updates screen. */
+			__( '<a href="%s">Update WordPress</a> first.', 'woocommerce' ),
+			esc_url( self_admin_url( 'update-core.php' ) )
+		);
+	}
+
 	/**
 	 * Runs on load-plugins.php, adds a hook to show a custom plugin update message for WooCommerce.com hosted plugins.
 	 *
@@ -1454,6 +1616,46 @@ class WC_Helper_Updater {
 			)
 		);
 	}
+
+	/**
+	 * Runs on upgrader_pre_download, stops an update to a WooCommerce.com extension version that needs a newer WordPress.
+	 *
+	 * Core checks the requirement only in bulk updates. The single-item upgrade behind the "update now"
+	 * link's URL skips it, and would install a version WordPress then refuses to activate.
+	 *
+	 * @since 11.4.0
+	 * @param bool|WP_Error $reply      Whether to bail without returning the package, or an error already set.
+	 * @param string        $package    The package file name or URL.
+	 * @param WP_Upgrader   $upgrader   The upgrader instance.
+	 * @param array         $hook_extra Extra arguments, naming the plugin or theme being updated.
+	 * @return bool|WP_Error An error when the update needs a newer WordPress, otherwise $reply unchanged.
+	 */
+	public static function block_update_needing_newer_wp( $reply, $package = '', $upgrader = null, $hook_extra = array() ) {
+		unset( $package, $upgrader ); // Avoid parameter not used PHPCS errors.
+
+		if ( false !== $reply || ! is_array( $hook_extra ) ) {
+			return $reply;
+		}
+
+		if ( isset( $hook_extra['plugin'] ) && is_string( $hook_extra['plugin'] ) ) {
+			$transient = get_site_transient( 'update_plugins' );
+			$item      = (object) array( 'plugin' => $hook_extra['plugin'] );
+			$offer     = is_object( $transient ) ? ( $transient->response[ $hook_extra['plugin'] ] ?? null ) : null;
+		} elseif ( isset( $hook_extra['theme'] ) && is_string( $hook_extra['theme'] ) ) {
+			$transient = get_site_transient( 'update_themes' );
+			$item      = (object) array( 'theme' => $hook_extra['theme'] );
+			$offer     = is_object( $transient ) ? ( $transient->response[ $hook_extra['theme'] ] ?? null ) : null;
+		} else {
+			return $reply;
+		}
+
+		$requires = self::get_unmet_wp_requirement( $offer );
+		if ( '' === $requires || ! self::is_woo_update_offer( $item ) ) {
+			return $reply;
+		}
+
+		return new WP_Error( 'woocommerce_update_needs_newer_wp', self::get_wp_requirement_notice( $requires, false ) );
+	}
 }

 WC_Helper_Updater::load();
diff --git a/plugins/woocommerce/tests/php/includes/admin/helper/class-wc-helper-updater-test.php b/plugins/woocommerce/tests/php/includes/admin/helper/class-wc-helper-updater-test.php
index 3616505faeb..092dc4bdff1 100644
--- a/plugins/woocommerce/tests/php/includes/admin/helper/class-wc-helper-updater-test.php
+++ b/plugins/woocommerce/tests/php/includes/admin/helper/class-wc-helper-updater-test.php
@@ -2398,6 +2398,337 @@ class WC_Helper_Updater_Test extends WC_Unit_Test_Case {
 		);
 	}

+	/**
+	 * Values the update-check response could report for requires, and what the update item should carry.
+	 *
+	 * @return array
+	 */
+	public function requires_values(): array {
+		return array(
+			'major.minor'       => array( '7.2', '7.2' ),
+			'major.minor.patch' => array( '6.8.1', '6.8.1' ),
+			'padded'            => array( ' 7.0 ', '7.0' ),
+			'number'            => array( 7, '7' ),
+			'missing'           => array( null, null ),
+			'empty string'      => array( '', null ),
+			'pre-release'       => array( '7.2-RC1', '7.2-RC1' ),
+			'empty suffix'      => array( '7.2-', null ),
+			'not a version'     => array( 'latest', null ),
+			'array'             => array( array( '7.0' ), null ),
+		);
+	}
+
+	/**
+	 * @testdox A plugin update item reports the WordPress requirement the update-check response carries: $_dataName.
+	 * @dataProvider requires_values
+	 *
+	 * @param mixed       $requires Raw value the update-check response reports for requires, or null when it reports none.
+	 * @param string|null $expected The requires value the update item should carry, or null for none.
+	 */
+	public function test_transient_update_plugins_passes_requires( $requires, ?string $expected ): void {
+		$filename = $this->mock_local_woo_plugin();
+		$this->mock_update_check_products( 123, false );
+		if ( null !== $requires ) {
+			$this->mocked_updates[123]['requires'] = $requires;
+		}
+
+		add_filter( 'pre_http_request', array( $this, 'mock_helper_api_response' ), 10, 3 );
+		try {
+			$transient = WC_Helper_Updater::transient_update_plugins(
+				(object) array(
+					'response'  => array(),
+					'no_update' => array(),
+				)
+			);
+		} finally {
+			remove_filter( 'pre_http_request', array( $this, 'mock_helper_api_response' ) );
+		}
+
+		$this->assertSame(
+			$expected,
+			( (array) $transient->response[ $filename ] )['requires'] ?? null,
+			'The plugin update item should carry only a valid WordPress requirement'
+		);
+	}
+
+	/**
+	 * @testdox A theme update item reports the WordPress requirement, so core's theme screens can withhold the update.
+	 */
+	public function test_transient_update_themes_passes_requires(): void {
+		$stylesheet = $this->mock_local_woo_theme();
+		$this->mock_update_check_products( 456, false );
+		$this->mocked_updates[456]['requires'] = '7.2';
+
+		add_filter( 'pre_http_request', array( $this, 'mock_helper_api_response' ), 10, 3 );
+		try {
+			$transient = WC_Helper_Updater::transient_update_themes(
+				(object) array(
+					'response' => array(),
+					'checked'  => array(),
+				)
+			);
+		} finally {
+			remove_filter( 'pre_http_request', array( $this, 'mock_helper_api_response' ) );
+		}
+
+		$this->assertSame( '7.2', $transient->response[ $stylesheet ]['requires'] ?? null );
+	}
+
+	/**
+	 * Auto-update decisions for a plugin update offer, and what the filters should leave.
+	 *
+	 * @return array
+	 */
+	public function auto_update_offers(): array {
+		return array(
+			'Woo update needing a newer WordPress'     => array( true, true, '99.0', false ),
+			'Woo update needing a WordPress RC'        => array( true, true, '99.0-RC1', false ),
+			'Woo update the site meets'                => array( true, true, '1.0', true ),
+			'Woo update without a requirement'         => array( true, true, null, true ),
+			'another plugin needing a newer WordPress' => array( false, true, '99.0', true ),
+			'undecided Woo update needing a newer WordPress' => array( true, null, '99.0', null ),
+			'Woo update already turned off'            => array( true, false, '99.0', false ),
+		);
+	}
+
+	/**
+	 * @testdox An auto-update to a WooCommerce.com plugin version that needs a newer WordPress is skipped: $_dataName.
+	 * @dataProvider auto_update_offers
+	 *
+	 * @param bool        $is_woo   Whether the offer is for the local WooCommerce.com plugin.
+	 * @param bool|null   $update   Decision passed into the filter.
+	 * @param string|null $requires WordPress version the offer needs, or null for none.
+	 * @param bool|null   $expected Decision expected after the filters.
+	 */
+	public function test_auto_update_plugin_skips_update_needing_newer_wp( bool $is_woo, ?bool $update, ?string $requires, ?bool $expected ): void {
+		$filename = $this->mock_local_woo_plugin();
+
+		$item = (object) array(
+			'plugin'      => $is_woo ? $filename : 'another-plugin/another-plugin.php',
+			'new_version' => '2.0.0',
+			'autoupdate'  => true,
+		);
+		if ( null !== $requires ) {
+			$item->requires = $requires;
+		}
+
+		$this->assertSame( $expected, WC_Helper_Updater::skip_auto_update_needing_newer_wp( $update, $item ) );
+	}
+
+	/**
+	 * @testdox Another auto_update_plugin callback can't switch back on an update that needs a newer WordPress.
+	 */
+	public function test_auto_update_plugin_skip_runs_after_other_callbacks(): void {
+		$item = (object) array(
+			'plugin'      => $this->mock_local_woo_plugin(),
+			'new_version' => '2.0.0',
+			'requires'    => '99.0',
+			'autoupdate'  => true,
+		);
+
+		add_filter( 'auto_update_plugin', '__return_true', 999 );
+		try {
+			$this->assertFalse( apply_filters( 'auto_update_plugin', true, $item ) );
+		} finally {
+			remove_filter( 'auto_update_plugin', '__return_true', 999 );
+		}
+	}
+
+	/**
+	 * @testdox An auto-update to a WooCommerce.com theme version that needs a newer WordPress is skipped.
+	 */
+	public function test_auto_update_theme_skips_update_needing_newer_wp(): void {
+		$stylesheet = $this->mock_local_woo_theme();
+
+		$item = (object) array(
+			'theme'       => $stylesheet,
+			'new_version' => '2.0.0',
+			'requires'    => '99.0',
+		);
+
+		$this->assertFalse( apply_filters( 'auto_update_theme', true, $item ) );
+	}
+
+	/**
+	 * @testdox The plugin update row explains an update that needs a newer WordPress, with a link for users who can update it.
+	 * @testWith ["administrator", true]
+	 *           ["editor", false]
+	 *
+	 * @param string $role      Role of the current user.
+	 * @param bool   $with_link Whether the Update WordPress link is expected.
+	 */
+	public function test_update_row_explains_update_needing_newer_wp( string $role, bool $with_link ): void {
+		$user_id = self::factory()->user->create( array( 'role' => $role ) );
+		if ( is_multisite() && 'administrator' === $role ) {
+			grant_super_admin( $user_id ); // Only super admins have update_core on multisite.
+		}
+		wp_set_current_user( $user_id );
+
+		ob_start();
+		WC_Helper_Updater::display_notice_for_update_needing_newer_wp( array(), (object) array( 'requires' => '99.0' ) );
+		$output = ob_get_clean();
+
+		$this->assertStringContainsString( 'This update needs WordPress 99.0 or later, and this site runs WordPress ' . wp_get_wp_version() . '.', $output );
+		$this->assertSame( $with_link, str_contains( $output, 'update-core.php' ), 'Only users who can update WordPress should get the link' );
+	}
+
+	/**
+	 * @testdox The plugin update row adds nothing when the site meets the update's WordPress requirement.
+	 * @testWith ["1.0"]
+	 *           [""]
+	 *
+	 * @param string $requires WordPress version the update needs.
+	 */
+	public function test_update_row_is_quiet_when_wp_requirement_is_met( string $requires ): void {
+		ob_start();
+		WC_Helper_Updater::display_notice_for_update_needing_newer_wp( array(), (object) array( 'requires' => $requires ) );
+
+		$this->assertSame( '', ob_get_clean() );
+	}
+
+	/**
+	 * Update downloads for a plugin offer, and whether the download should be stopped.
+	 *
+	 * @return array
+	 */
+	public function pre_download_offers(): array {
+		return array(
+			'Woo update needing a newer WordPress'     => array( true, '99.0', true ),
+			'Woo update the site meets'                => array( true, '1.0', false ),
+			'Woo update without a requirement'         => array( true, null, false ),
+			'another plugin needing a newer WordPress' => array( false, '99.0', false ),
+		);
+	}
+
+	/**
+	 * @testdox Downloading a WooCommerce.com plugin update that needs a newer WordPress is stopped, whichever path runs it: $_dataName.
+	 * @dataProvider pre_download_offers
+	 *
+	 * @param bool        $is_woo       Whether the offer is for the local WooCommerce.com plugin.
+	 * @param string|null $requires     WordPress version the offer needs, or null for none.
+	 * @param bool        $expect_error Whether the download should be stopped with an error.
+	 */
+	public function test_pre_download_blocks_plugin_update_needing_newer_wp( bool $is_woo, ?string $requires, bool $expect_error ): void {
+		$woo_filename   = $this->mock_local_woo_plugin();
+		$other_filename = 'another-plugin/another-plugin.php';
+		$this->mock_update_check_products( 123, false );
+		if ( null !== $requires ) {
+			$this->mocked_updates[123]['requires'] = $requires;
+		}
+
+		add_filter( 'pre_http_request', array( $this, 'mock_helper_api_response' ), 10, 3 );
+		try {
+			set_site_transient(
+				'update_plugins',
+				(object) array(
+					'response'  => array(
+						$other_filename => (object) array(
+							'plugin'      => $other_filename,
+							'new_version' => '2.0.0',
+							'requires'    => $requires,
+						),
+					),
+					'no_update' => array(),
+				)
+			);
+		} finally {
+			remove_filter( 'pre_http_request', array( $this, 'mock_helper_api_response' ) );
+		}
+
+		$reply = apply_filters( 'upgrader_pre_download', false, '', null, array( 'plugin' => $is_woo ? $woo_filename : $other_filename ) );
+
+		if ( $expect_error ) {
+			$this->assertWPError( $reply );
+			$this->assertSame( 'woocommerce_update_needs_newer_wp', $reply->get_error_code() );
+			$this->assertStringContainsString( 'This update needs WordPress 99.0 or later', $reply->get_error_message() );
+		} else {
+			$this->assertFalse( $reply );
+		}
+	}
+
+	/**
+	 * @testdox Downloading a WooCommerce.com theme update that needs a newer WordPress is stopped with a plain-text error.
+	 */
+	public function test_pre_download_blocks_theme_update_needing_newer_wp(): void {
+		$user_id = self::factory()->user->create( array( 'role' => 'administrator' ) );
+		if ( is_multisite() ) {
+			grant_super_admin( $user_id ); // Only super admins have update_core on multisite.
+		}
+		wp_set_current_user( $user_id );
+
+		$stylesheet = $this->mock_local_woo_theme();
+		$this->mock_update_check_products( 456, false );
+		$this->mocked_updates[456]['requires'] = '99.0';
+
+		add_filter( 'pre_http_request', array( $this, 'mock_helper_api_response' ), 10, 3 );
+		try {
+			set_site_transient(
+				'update_themes',
+				(object) array(
+					'response' => array(),
+					'checked'  => array(),
+				)
+			);
+		} finally {
+			remove_filter( 'pre_http_request', array( $this, 'mock_helper_api_response' ) );
+		}
+
+		$reply = apply_filters( 'upgrader_pre_download', false, '', null, array( 'theme' => $stylesheet ) );
+
+		$this->assertWPError( $reply );
+		$this->assertSame( 'woocommerce_update_needs_newer_wp', $reply->get_error_code() );
+		$this->assertSame(
+			sprintf( 'This update needs WordPress 99.0 or later, and this site runs WordPress %s. Update WordPress first.', wp_get_wp_version() ),
+			$reply->get_error_message(),
+			'The error is plain text, since callers may show it as text.'
+		);
+	}
+
+	/**
+	 * @testdox An update that needs a newer WordPress is stopped even when another callback serves the package first.
+	 */
+	public function test_pre_download_blocks_update_before_early_package_callback(): void {
+		$stylesheet = $this->mock_local_woo_theme();
+		$this->mock_update_check_products( 456, false );
+		$this->mocked_updates[456]['requires'] = '99.0';
+
+		add_filter( 'pre_http_request', array( $this, 'mock_helper_api_response' ), 10, 3 );
+		try {
+			set_site_transient(
+				'update_themes',
+				(object) array(
+					'response' => array(),
+					'checked'  => array(),
+				)
+			);
+		} finally {
+			remove_filter( 'pre_http_request', array( $this, 'mock_helper_api_response' ) );
+		}
+
+		$serve_package = static function ( $reply ) {
+			return false === $reply ? '/tmp/served-package.zip' : $reply;
+		};
+		add_filter( 'upgrader_pre_download', $serve_package, 5 );
+		try {
+			$reply = apply_filters( 'upgrader_pre_download', false, '', null, array( 'theme' => $stylesheet ) );
+		} finally {
+			remove_filter( 'upgrader_pre_download', $serve_package, 5 );
+		}
+
+		$this->assertWPError( $reply );
+		$this->assertSame( 'woocommerce_update_needs_newer_wp', $reply->get_error_code() );
+	}
+
+	/**
+	 * @testdox A download that isn't a plugin or theme update, or that another callback already answered, is left alone.
+	 */
+	public function test_pre_download_leaves_other_downloads_alone(): void {
+		$earlier_error = new WP_Error( 'earlier', 'Set by another callback.' );
+
+		$this->assertFalse( WC_Helper_Updater::block_update_needing_newer_wp( false, 'https://example.com/package.zip', null, array( 'type' => 'plugin' ) ) );
+		$this->assertSame( $earlier_error, WC_Helper_Updater::block_update_needing_newer_wp( $earlier_error, 'https://example.com/package.zip', null, array( 'plugin' => 'any/any.php' ) ) );
+	}
+
 	/**
 	 * Makes WC_Helper::get_local_woo_plugins() report a single Woo plugin, without touching the filesystem.
 	 *