USPSShippingProvider.php — WooCommerce 10.9.4

woocommerce / src / Admin / Features / Fulfillments / Providers / USPSShippingProvider.php

woocommerce / src / Admin / Features / Fulfillments / Providers Last commit date

USPSShippingProvider.php

170 lines

1	<?php declare(strict_types=1);
2
3	namespace Automattic\WooCommerce\Admin\Features\Fulfillments\Providers;
4
5	use Automattic\WooCommerce\Admin\Features\Fulfillments\FulfillmentUtils;
6
7	/**
8	* USPS Shipping Provider implementation.
9	*
10	* Handles USPS tracking number detection and validation for both domestic and international shipments.
11	*/
12	class USPSShippingProvider extends AbstractShippingProvider {
13	/**
14	* List of countries/territories where USPS offers domestic service.
15	*
16	* @var array<string>
17	*/
18	private array $domestic_countries = array( 'US', 'PR', 'GU', 'AS', 'VI', 'MP', 'FM', 'MH', 'PW' );
19
20	/**
21	* Gets the unique provider key.
22	*
23	* @return string The provider key 'usps'.
24	*/
25	public function get_key(): string {
26	return 'usps';
27	}
28
29	/**
30	* Gets the display name of the provider.
31	*
32	* @return string The provider name 'USPS'.
33	*/
34	public function get_name(): string {
35	return 'USPS';
36	}
37
38	/**
39	* Gets the path to the provider's icon.
40	*
41	* @return string URL to the USPS logo image.
42	*/
43	public function get_icon(): string {
44	return esc_url( WC()->plugin_url() ) . '/assets/images/shipping_providers/usps.png';
45	}
46
47	/**
48	* Generates the tracking URL for a given tracking number.
49	*
50	* @param string $tracking_number The tracking number to generate URL for.
51	* @return string The complete tracking URL.
52	*/
53	public function get_tracking_url( string $tracking_number ): string {
54	return 'https://tools.usps.com/go/TrackConfirmAction?tLabels=' . rawurlencode( $tracking_number );
55	}
56
57	/**
58	* Gets the list of origin countries supported by USPS.
59	*
60	* @return array<string> Array of country codes (only 'US').
61	*/
62	public function get_shipping_from_countries(): array {
63	return array( 'US' ); // USPS only ships from the United States.
64	}
65
66	/**
67	* Gets the list of destination countries supported by USPS.
68	*
69	* @return array<string> Array of country codes including domestic and international.
70	*/
71	public function get_shipping_to_countries(): array {
72	return array_merge(
73	$this->domestic_countries,
74	explode( ' ', 'AD AE AF AG AI AL AM AO AR AT AU AW AZ BA BB BD BE BF BG BH BI BJ BM BN BO BR BS BT BW BY BZ CA CD CF CG CH CI CL CM CN CO CR CU CV CY CZ DE DJ DK DM DO DZ EC EE EG ER ES ET FI FJ FR GA GB GD GE GH GI GM GN GQ GR GT GW GY HK HN HR HT HU ID IE IL IN IQ IR IS IT JM JO JP KE KG KH KI KM KN KP KR KW KZ LA LB LC LK LR LS LT LU LV LY MA MC MD ME MG MK ML MM MN MO MR MT MU MV MW MX MY MZ NA NE NG NI NL NO NP NZ OM PA PE PG PH PK PL PT PY QA RO RS RU RW SA SB SC SD SE SG SI SK SL SM SN SO SR ST SV SY SZ TD TG TH TJ TL TM TN TO TR TT TV TW TZ UA UG UK UY UZ VC VE VN VU WS YE ZA ZM ZW' )
75	);
76	}
77
78	/**
79	* Checks if USPS can ship from and to the specified countries.
80	*
81	* @param string $shipping_from Origin country code.
82	* @param string $shipping_to Destination country code.
83	* @return bool
84	*/
85	public function can_ship_from_to( string $shipping_from, string $shipping_to ): bool {
86	return in_array( $shipping_from, $this->get_shipping_from_countries(), true )
87	&& in_array( $shipping_to, $this->get_shipping_to_countries(), true );
88	}
89
90	/**
91	* Attempts to parse and validate a USPS tracking number.
92	*
93	* @param string $tracking_number The tracking number to validate.
94	* @param string $shipping_from Origin country code.
95	* @param string $shipping_to Destination country code.
96	* @return array\|null Array with tracking URL and score, or null if invalid.
97	*/
98	public function try_parse_tracking_number( string $tracking_number, string $shipping_from, string $shipping_to ): ?array {
99	if ( empty( $tracking_number ) \|\| ! $this->can_ship_from_to( $shipping_from, $shipping_to ) ) {
100	return null;
101	}
102
103	// Remove spaces and uppercase for consistency.
104	$tracking_number = strtoupper( preg_replace( '/\s+/', '', $tracking_number ) );
105	$is_domestic = in_array( $shipping_to, $this->domestic_countries, true );
106
107	// USPS tracking number patterns (ordered by confidence).
108	$patterns = array(
109	// 22-digit, 20-digit, and 26-34 digit numeric (domestic and third-party)
110	'/^(94\|93\|92\|95\|96\|94\|94\|94\|94)\d{18,22}$/' => function () use ( $tracking_number ) {
111	// Most common domestic, check digit validation.
112	return FulfillmentUtils::validate_mod10_check_digit( $tracking_number ) ? 100 : 95;
113	},
114
115	// S10/UPU international (2 letters, 9 digits, 2 letters, e.g., EC123456789US).
116	'/^[A-Z]{2}\d{9}[A-Z]{2}$/' => function () use ( $tracking_number ) {
117	return FulfillmentUtils::check_s10_upu_format( $tracking_number ) ? 98 : 90;
118	},
119
120	// Global Express Guaranteed (10 or 11 digits, starts with 82).
121	'/^82\d{8,9}$/' => 95,
122
123	// 26-34 digit numeric (Parcel Pool, third-party, starts with 420)
124	'/^420\d{23,31}$/' => 90,
125
126	// 20-22 digit numeric (fallback, domestic)
127	'/^\d{20,22}$/' => 80,
128
129	// 9x... (fallback, 22-34 digits, numeric)
130	'/^9\d{21,33}$/' => 75,
131
132	// Legacy/Express/other.
133	'/^91\d{18,20}$/' => function () use ( $tracking_number ) {
134	return FulfillmentUtils::validate_mod10_check_digit( $tracking_number ) ? 90 : 80;
135	},
136	'/^030[67]\d{16,20}$/' => function () use ( $tracking_number ) {
137	return FulfillmentUtils::validate_mod10_check_digit( $tracking_number ) ? 88 : 80;
138	},
139	);
140
141	foreach ( $patterns as $pattern => $score ) {
142	if ( preg_match( $pattern, $tracking_number ) ) {
143	$ambiguity_score = is_callable( $score ) ? $score() : $score;
144	return array(
145	'url' => $this->get_tracking_url( $tracking_number ),
146	'ambiguity_score' => $ambiguity_score,
147	);
148	}
149	}
150
151	// Fallback: Accept any 13-char S10/UPU format ending with "US".
152	if ( preg_match( '/^[A-Z]{2}\d{9}US$/', $tracking_number ) ) {
153	return array(
154	'url' => $this->get_tracking_url( $tracking_number ),
155	'ambiguity_score' => 80,
156	);
157	}
158
159	// Fallback: Accept any 20-34 digit numeric string (very low confidence).
160	if ( preg_match( '/^\d{20,34}$/', $tracking_number ) ) {
161	return array(
162	'url' => $this->get_tracking_url( $tracking_number ),
163	'ambiguity_score' => 60,
164	);
165	}
166
167	return null; // No matching pattern found.
168	}
169	}
170