Commit 7f92e8b129c for woocommerce

commit 7f92e8b129cf7d4393f2a99c5698360366f79076
Author: Luigi Teschio <gigitux@gmail.com>
Date:   Sat Nov 21 19:49:05 2026 +0100

    Match ZIP+4 postcodes against five-digit ZIP rules (#71274)

    * Remove customer passwords from deferred email actions

    Forwardport of 500-gh-Automattic/woocommerce.

    Keep the 11.3.1 migration registration and callback names from the shipped migration fix.

    * Match ZIP+4 postcodes against five-digit ZIP rules

    Forwardport of 515-gh-Automattic/woocommerce.

    Keep the 11.3.1 migration registration and callback names from the shipped migration fix.

    ---------

    Co-authored-by: Tom Cafferkey <tjcafferkey@gmail.com>
    Co-authored-by: Sam Najian <dev.samnajian@gmail.com>
    Co-authored-by: Taha Paksu <3295+tpaksu@users.noreply.github.com>

diff --git a/plugins/woocommerce/includes/class-wc-install.php b/plugins/woocommerce/includes/class-wc-install.php
index 1752c51daec..83cbe086fae 100644
--- a/plugins/woocommerce/includes/class-wc-install.php
+++ b/plugins/woocommerce/includes/class-wc-install.php
@@ -377,6 +377,7 @@ class WC_Install {
 		),
 		'11.3.1'   => array(
 			'wc_update_1131_redact_deferred_customer_passwords',
+			'wc_update_1131_invalidate_postcode_match_caches',
 		),
 		'11.4.0'   => array(
 			'wc_update_1140_re_enable_autoload_options',
diff --git a/plugins/woocommerce/includes/wc-core-functions.php b/plugins/woocommerce/includes/wc-core-functions.php
index 6b285bce9e8..27311eb66f9 100644
--- a/plugins/woocommerce/includes/wc-core-functions.php
+++ b/plugins/woocommerce/includes/wc-core-functions.php
@@ -15,6 +15,7 @@ use Automattic\WooCommerce\Internal\Utilities\SiteLocale;
 use Automattic\WooCommerce\Utilities\NumberUtil;
 use Automattic\WooCommerce\Internal\Logging\OrderLogsCleanupHelper;
 use Automattic\WooCommerce\Internal\Utilities\DatabaseTransaction;
+use Automattic\WooCommerce\Internal\Utilities\PostcodeValidation;

 if ( ! defined( 'ABSPATH' ) ) {
 	exit;
@@ -1622,6 +1623,12 @@ function wc_get_wildcard_postcodes( $postcode, $country = '' ) {
 		$postcodes[] = ( function_exists( 'mb_substr' ) ? mb_substr( $formatted_postcode, 0, ( $i + 1 ) * -1 ) : substr( $formatted_postcode, 0, ( $i + 1 ) * -1 ) ) . '*';
 	}

+	// A ZIP+4 code lies within its 5-digit ZIP code, so it also matches rules written as that ZIP code.
+	$zip_code = PostcodeValidation::get_zip_code_from_zip_plus_four( (string) $postcode, (string) $country );
+	if ( '' !== $zip_code ) {
+		$postcodes[] = $zip_code;
+	}
+
 	return $postcodes;
 }

@@ -1640,6 +1647,7 @@ function wc_get_wildcard_postcodes( $postcode, $country = '' ) {
 function wc_postcode_location_matcher( $postcode, $objects, $object_id_key, $object_compare_key, $country = '' ) {
 	$postcode           = wc_normalize_postcode( $postcode );
 	$wildcard_postcodes = array_map( 'wc_clean', wc_get_wildcard_postcodes( $postcode, $country ) );
+	$zip_code           = PostcodeValidation::get_zip_code_from_zip_plus_four( (string) $postcode, (string) $country );
 	$matches            = array();

 	foreach ( $objects as $object ) {
@@ -1661,6 +1669,10 @@ function wc_postcode_location_matcher( $postcode, $objects, $object_id_key, $obj
 				$compare = wc_make_numeric_postcode( $postcode );
 				$min     = str_pad( wc_make_numeric_postcode( $min ), strlen( $compare ), '0' );
 				$max     = str_pad( wc_make_numeric_postcode( $max ), strlen( $compare ), '0' );
+			} elseif ( '' !== $zip_code && (int) $max < 100000 ) {
+				// Compare a ZIP+4 code with a range of 5-digit ZIP codes by its 5-digit part. The bound's
+				// value decides this, not its length: a ZIP+4 range may omit its leading zeroes.
+				$compare = $zip_code;
 			} else {
 				$compare = $postcode;
 			}
diff --git a/plugins/woocommerce/includes/wc-update-functions.php b/plugins/woocommerce/includes/wc-update-functions.php
index 0accc208690..de4626319be 100644
--- a/plugins/woocommerce/includes/wc-update-functions.php
+++ b/plugins/woocommerce/includes/wc-update-functions.php
@@ -4451,3 +4451,18 @@ function wc_update_1122_remove_objects_from_default_attributes(): void {
 		);
 	}
 }
+
+/**
+ * Clear cached shipping zone and tax rate matches, so ZIP+4 postcodes cached before 11.3.1
+ * are matched again against rules for their 5-digit ZIP code.
+ *
+ * The shipping transient version is bumped too, so shipping rates stored in a cart session
+ * before the update are calculated again.
+ *
+ * @since 11.3.1
+ */
+function wc_update_1131_invalidate_postcode_match_caches(): void {
+	WC_Cache_Helper::invalidate_cache_group( 'shipping_zones' );
+	WC_Cache_Helper::invalidate_cache_group( 'taxes' );
+	WC_Cache_Helper::get_transient_version( 'shipping', true );
+}
diff --git a/plugins/woocommerce/src/Internal/Utilities/PostcodeValidation.php b/plugins/woocommerce/src/Internal/Utilities/PostcodeValidation.php
index bd475b0bf27..1275d660f10 100644
--- a/plugins/woocommerce/src/Internal/Utilities/PostcodeValidation.php
+++ b/plugins/woocommerce/src/Internal/Utilities/PostcodeValidation.php
@@ -74,4 +74,25 @@ final class PostcodeValidation {

 		return false === $matched ? null : 1 === $matched;
 	}
+
+	/**
+	 * Get the 5-digit ZIP code of a ZIP+4 postcode.
+	 *
+	 * Covers the countries wc_format_postcode() formats as ZIP+4.
+	 *
+	 * @since 11.4.0
+	 *
+	 * @param string $postcode Postcode, with or without the hyphen.
+	 * @param string $country  Country code.
+	 * @return string The 5-digit ZIP code, or an empty string if the postcode is not a ZIP+4 code.
+	 */
+	public static function get_zip_code_from_zip_plus_four( string $postcode, string $country ): string {
+		$postcode = wc_normalize_postcode( $postcode );
+
+		if ( ! in_array( $country, array( 'US', 'PR', 'MN' ), true ) || ! preg_match( '/^\d{9}$/', $postcode ) ) {
+			return '';
+		}
+
+		return substr( $postcode, 0, 5 );
+	}
 }
diff --git a/plugins/woocommerce/tests/php/includes/class-wc-shipping-zones-test.php b/plugins/woocommerce/tests/php/includes/class-wc-shipping-zones-test.php
index 11b8365d319..02d7874c3f3 100644
--- a/plugins/woocommerce/tests/php/includes/class-wc-shipping-zones-test.php
+++ b/plugins/woocommerce/tests/php/includes/class-wc-shipping-zones-test.php
@@ -134,6 +134,36 @@ class WC_Shipping_Zones_Test extends WC_Unit_Test_Case {
 		);
 	}

+	/**
+	 * A ZIP+4 code lies within its 5-digit ZIP code, so it lands in a zone limited to that ZIP code
+	 * or to a range of 5-digit ZIP codes rather than falling through to a wider zone.
+	 *
+	 * @testdox A ZIP+4 postcode matches zones limited to its 5-digit ZIP code or a range of them.
+	 *
+	 * @testWith ["96701...96898"]
+	 *           ["96801"]
+	 *
+	 * @param string $rule Postcode rule of the zone.
+	 */
+	public function test_a_zip_plus_four_postcode_matches_its_zip_code_zone( string $rule ): void {
+		$this->zone_with( 'Hawaii', $rule, 'postcode' );
+		$this->zone_with( 'United States', 'US', 'country', 2 );
+
+		foreach ( array( '96801', '96801-1234', '968011234' ) as $postcode ) {
+			$this->assertSame(
+				'Hawaii',
+				$this->matched_zone_name(
+					array(
+						'country'  => 'US',
+						'state'    => 'HI',
+						'postcode' => $postcode,
+					)
+				),
+				"{$postcode} should land in the zone limited to {$rule}."
+			);
+		}
+	}
+
 	/**
 	 * A range whose bounds are not plain numbers is compared by turning each into a number, so a
 	 * range written with letters still contains the codes between its ends.
diff --git a/plugins/woocommerce/tests/php/includes/class-wc-tax-test.php b/plugins/woocommerce/tests/php/includes/class-wc-tax-test.php
index ecb785c3974..471677f7aef 100644
--- a/plugins/woocommerce/tests/php/includes/class-wc-tax-test.php
+++ b/plugins/woocommerce/tests/php/includes/class-wc-tax-test.php
@@ -920,4 +920,55 @@ class WC_Tax_Test extends WC_Unit_Test_Case {
 		$this->assertEqualsWithDelta( 2.00, $total_tax, 0.02, 'Tax taken from 12.00 should be about 2.00' );
 		$this->assertEqualsWithDelta( 10.00, $net_cost, 0.02, 'Net cost should be 10.00' );
 	}
+
+	/**
+	 * @testdox find_rates applies a rate limited to a 5-digit ZIP code, or a range of them, to a ZIP+4 postcode.
+	 *
+	 * @testWith ["10001"]
+	 *           ["10000...10099"]
+	 *
+	 * @param string $rule Postcode rule of the tax rate.
+	 */
+	public function test_find_rates_matches_zip_plus_four_postcode( string $rule ): void {
+		$tax_rate_id = WC_Tax::_insert_tax_rate(
+			array(
+				'tax_rate_country'  => 'US',
+				'tax_rate_state'    => '',
+				'tax_rate'          => '10.0000',
+				'tax_rate_name'     => 'ZIP code tax',
+				'tax_rate_priority' => '1',
+				'tax_rate_compound' => '0',
+				'tax_rate_shipping' => '1',
+				'tax_rate_order'    => '1',
+				'tax_rate_class'    => '',
+			)
+		);
+		WC_Tax::_update_tax_rate_postcodes( $tax_rate_id, $rule );
+
+		foreach ( array( '10001', '10001-1234' ) as $postcode ) {
+			$rates = WC_Tax::find_rates(
+				array(
+					'country'   => 'US',
+					'state'     => 'NY',
+					'postcode'  => $postcode,
+					'city'      => '',
+					'tax_class' => '',
+				)
+			);
+
+			$this->assertArrayHasKey( $tax_rate_id, $rates, "{$postcode} should get the rate limited to {$rule}." );
+		}
+
+		$rates = WC_Tax::find_rates(
+			array(
+				'country'   => 'US',
+				'state'     => 'NY',
+				'postcode'  => '10101-1234',
+				'city'      => '',
+				'tax_class' => '',
+			)
+		);
+
+		$this->assertArrayNotHasKey( $tax_rate_id, $rates, "A ZIP+4 code outside {$rule} should not get the rate." );
+	}
 }
diff --git a/plugins/woocommerce/tests/php/includes/wc-core-functions-test.php b/plugins/woocommerce/tests/php/includes/wc-core-functions-test.php
index d6a6fbf3e44..aa23075bde2 100644
--- a/plugins/woocommerce/tests/php/includes/wc-core-functions-test.php
+++ b/plugins/woocommerce/tests/php/includes/wc-core-functions-test.php
@@ -547,6 +547,58 @@ class WC_Core_Functions_Test extends \WC_Unit_Test_Case {
 		$this->assertSame( array( 'Afghanistan', 'Åland Islands', 'Espagne', 'Éthiopie' ), array_values( $sorted_values ) );
 	}

+	/**
+	 * @testdox wc_postcode_location_matcher matches a ZIP+4 code against rules written for its 5-digit ZIP code.
+	 *
+	 * @testWith ["96801-1234", "US", "96701...96898", true]
+	 *           ["968011234", "US", "96701...96898", true]
+	 *           ["96801-1234", "US", "96801", true]
+	 *           ["00901-1234", "PR", "00901...00999", true]
+	 *           ["00901-1234", "PR", "901...999", true]
+	 *           ["00901-1234", "PR", "9010000...9019999", true]
+	 *           ["96801-1234", "US", "96801*", true]
+	 *           ["96801-1234", "US", "967010000...968989999", true]
+	 *           ["96801-1234", "US", "96801-1234", true]
+	 *           ["96900-1234", "US", "96701...96898", false]
+	 *           ["96801-1234", "US", "96802", false]
+	 *           ["96801-1234", "US", "96801-5678", false]
+	 *           ["96801", "US", "967010000...968989999", false]
+	 *           ["00901-1234", "PR", "9020000...9029999", false]
+	 *           ["968011234", "DE", "96701...96898", false]
+	 *           ["968011234", "DE", "96801", false]
+	 *
+	 * @param string $postcode Postcode entered by the shopper.
+	 * @param string $country  Country of the address.
+	 * @param string $rule     Postcode rule as stored for a zone or tax rate.
+	 * @param bool   $expected Whether the rule should match.
+	 */
+	public function test_wc_postcode_location_matcher_matches_zip_plus_four( string $postcode, string $country, string $rule, bool $expected ): void {
+		$rules = array(
+			(object) array(
+				'id'   => 1,
+				'code' => $rule,
+			),
+		);
+
+		$matches = wc_postcode_location_matcher( $postcode, $rules, 'id', 'code', $country );
+
+		$this->assertSame( $expected, isset( $matches[1] ), sprintf( '%s (%s) against rule %s', $postcode, $country, $rule ) );
+	}
+
+	/**
+	 * @testdox wc_get_wildcard_postcodes adds the 5-digit ZIP code for a ZIP+4 code, and only for ZIP+4 countries.
+	 */
+	public function test_wc_get_wildcard_postcodes_adds_zip_code_for_zip_plus_four(): void {
+		$this->assertContains( '96801', wc_get_wildcard_postcodes( '968011234', 'US' ), 'A normalized ZIP+4 code should include its ZIP code.' );
+		$this->assertContains( '96801', wc_get_wildcard_postcodes( '96801-1234', 'US' ), 'A hyphenated ZIP+4 code should include its ZIP code.' );
+		$this->assertNotContains( '96801', wc_get_wildcard_postcodes( '968011234', 'DE' ), 'A 9-digit postcode outside ZIP+4 countries should not.' );
+		$this->assertSame(
+			array( '96801', '96801', '96801*', '9680*', '968*', '96*', '9*', '*' ),
+			wc_get_wildcard_postcodes( '96801', 'US' ),
+			'A 5-digit ZIP code should be unchanged.'
+		);
+	}
+
 	/**
 	 * @testdDox wc_get_rounding_precision returns the value of wc_get_price_decimals()+2, but with a minimum of WC_ROUNDING_PRECISION (6)
 	 *
diff --git a/plugins/woocommerce/tests/php/includes/wc-update-functions-test.php b/plugins/woocommerce/tests/php/includes/wc-update-functions-test.php
index 7d68fc7efe8..22bffaaf2bc 100644
--- a/plugins/woocommerce/tests/php/includes/wc-update-functions-test.php
+++ b/plugins/woocommerce/tests/php/includes/wc-update-functions-test.php
@@ -1450,4 +1450,80 @@ class WC_Update_Functions_Test extends \WC_Unit_Test_Case {
 		$this->assertSame( serialize( array( 'pa_color' => 'blue' ) ), $read( 'nested' ), 'Objects nested in arrays are removed' ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.serialize_serialize
 		$this->assertSame( $stored['recursive'], $read( 'recursive' ), 'A self-referencing row without objects is kept, and does not stop the migration' );
 	}
+
+	/**
+	 * @testdox wc_update_1131_invalidate_postcode_match_caches makes ZIP+4 postcodes match zones and tax rates cached before the fix.
+	 */
+	public function test_wc_update_1131_invalidate_postcode_match_caches(): void {
+		include_once WC_ABSPATH . 'includes/wc-update-functions.php';
+
+		$zone = new WC_Shipping_Zone();
+		$zone->set_zone_name( 'Honolulu' );
+		$zone->add_location( 'US', 'country' );
+		$zone->add_location( '96801', 'postcode' );
+		$zone->save();
+
+		$rate_id = WC_Tax::_insert_tax_rate(
+			array(
+				'tax_rate_country'  => 'US',
+				'tax_rate'          => '10.0000',
+				'tax_rate_name'     => 'Honolulu',
+				'tax_rate_priority' => '1',
+				'tax_rate_order'    => '1',
+			)
+		);
+		WC_Tax::_update_tax_rate_postcodes( $rate_id, '96801' );
+
+		// What a lookup before the fix cached for a ZIP+4 postcode: the fallback zone and no tax rate.
+		wp_cache_set( WC_Cache_Helper::get_cache_prefix( 'shipping_zones' ) . 'wc_shipping_zone_' . md5( 'US++968011234' ), 0, 'shipping_zones' );
+		wp_cache_set( WC_Cache_Helper::get_cache_prefix( 'taxes' ) . 'wc_tax_rates_' . md5( 'US+++968011234+' ), array(), 'taxes' );
+
+		$package      = array(
+			'destination' => array(
+				'country'  => 'US',
+				'state'    => '',
+				'postcode' => '96801-1234',
+			),
+		);
+		$tax_location = array(
+			'country'  => 'US',
+			'postcode' => '96801-1234',
+		);
+
+		$this->assertSame( 0, WC_Shipping_Zones::get_zone_matching_package( $package )->get_id(), 'The stale zone match is served before the update.' );
+		$this->assertSame( array(), WC_Tax::find_rates( $tax_location ), 'The stale tax match is served before the update.' );
+
+		wc_update_1131_invalidate_postcode_match_caches();
+
+		$this->assertSame( $zone->get_id(), WC_Shipping_Zones::get_zone_matching_package( $package )->get_id() );
+		$this->assertArrayHasKey( $rate_id, WC_Tax::find_rates( $tax_location ) );
+	}
+
+	/**
+	 * @testdox wc_update_1131_invalidate_postcode_match_caches makes a cart calculate again the shipping rates it stored before the fix.
+	 */
+	public function test_wc_update_1131_invalidate_postcode_match_caches_recalculates_stored_package_rates(): void {
+		include_once WC_ABSPATH . 'includes/wc-update-functions.php';
+
+		$package = array(
+			'contents'    => array(),
+			'destination' => array(
+				'country'  => 'US',
+				'state'    => '',
+				'postcode' => '96801-1234',
+			),
+		);
+
+		// What a cart session stored before the fix: a rate from the zone the ZIP+4 postcode fell back to.
+		WC()->shipping()->calculate_shipping_for_package( $package );
+		$stored_rates          = WC()->session->get( 'shipping_for_package_0' );
+		$stored_rates['rates'] = array( 'flat_rate:99' => new WC_Shipping_Rate( 'flat_rate:99', 'Fallback rate', 10, array(), 'flat_rate' ) );
+		WC()->session->set( 'shipping_for_package_0', $stored_rates );
+
+		$this->assertArrayHasKey( 'flat_rate:99', WC()->shipping()->calculate_shipping_for_package( $package )['rates'], 'The stored rate is served before the update.' );
+
+		wc_update_1131_invalidate_postcode_match_caches();
+
+		$this->assertArrayNotHasKey( 'flat_rate:99', WC()->shipping()->calculate_shipping_for_package( $package )['rates'], 'The rates are calculated again after the update.' );
+	}
 }