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.' );
+ }
}