CanadaPostShippingProvider.php — WooCommerce 10.9.4

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

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

CanadaPostShippingProvider.php

213 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	* Canada Post Shipping Provider class.
9	*
10	* Provides Canada Post tracking number validation, supported countries, and tracking URL generation.
11	*/
12	class CanadaPostShippingProvider extends AbstractShippingProvider {
13
14	/**
15	* Canada Post tracking number patterns with service differentiation.
16	*
17	* @var array<string, array{patterns: array<int, string>, confidence: int}>
18	*/
19	private const TRACKING_PATTERNS = array(
20	'CA' => array( // Canada.
21	'patterns' => array(
22	// UPU S10 international format (outbound).
23	'/^[A-Z]{2}\d{9}CA$/', // Standard format: XX#########CA.
24	// UPU S10 international (inbound/other countries, fallback).
25	'/^[A-Z]{2}\d{9}[A-Z]{2}$/', // Any S10/UPU code.
26	// Domestic numeric formats.
27	'/^\d{16}$/', // 16-digit domestic tracking.
28	'/^\d{15}$/', // 15-digit legacy/partner/returns.
29	'/^\d{14}$/', // 14-digit legacy/partner/returns.
30	'/^\d{13}$/', // 13-digit domestic (most common).
31	'/^\d{12}$/', // 12-digit domestic.
32	'/^\d{10}$/', // 10-digit legacy.
33	'/^\d{9}$/', // 9-digit legacy.
34	'/^\d{8}$/', // 8-digit calling card/legacy.
35	// Service-specific patterns.
36	'/^XP\d{9}CA$/', // Xpresspost International.
37	'/^EX\d{9}CA$/', // Express International.
38	'/^PR\d{9}CA$/', // Priority.
39	'/^RG\d{9}CA$/', // Regular (deprecated, legacy).
40	'/^RM\d{9}CA$/', // Registered Mail.
41	'/^CM\d{9}CA$/', // Certified Mail.
42	'/^[A-Z]{2}\d{7}[A-Z]{2}$/', // International format: XX#######XX.
43	'/^[A-Z]{1}\d{9}[A-Z]{1}$/', // Domestic formats: X#########X.
44	'/^FD\d{10,12}$/', // FlexDelivery.
45	'/^PO\d{10,12}$/', // Post Office Box service.
46	'/^CP\d{10,14}$/', // Canada Post business.
47	'/^SM\d{10,14}$/', // Small packet.
48	// Legacy and alternative formats.
49	'/^[0-9]{13}[A-Z]{1}$/', // 13 digits + 1 letter.
50	),
51	'confidence' => 92,
52	),
53	);
54
55	/**
56	* Get the unique key for this shipping provider.
57	*
58	* @return string Unique key.
59	*/
60	public function get_key(): string {
61	return 'canada-post';
62	}
63
64	/**
65	* Get the name of this shipping provider.
66	*
67	* @return string Name of the shipping provider.
68	*/
69	public function get_name(): string {
70	return 'Canada Post';
71	}
72
73	/**
74	* Get the icon URL for this shipping provider.
75	*
76	* @return string URL of the shipping provider icon.
77	*/
78	public function get_icon(): string {
79	return esc_url( WC()->plugin_url() ) . '/assets/images/shipping_providers/canada-post.png';
80	}
81
82	/**
83	* Get the countries this shipping provider can ship from.
84	*
85	* @return array List of country codes.
86	*/
87	public function get_shipping_from_countries(): array {
88	return array_keys( self::TRACKING_PATTERNS );
89	}
90
91	/**
92	* Get the countries this shipping provider can ship to.
93	*
94	* Canada Post ships internationally, so we return a comprehensive list.
95	*
96	* @return array List of country codes.
97	*/
98	public function get_shipping_to_countries(): array {
99	return array( 'AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AQ', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', 'BJ', 'BL', 'BM', 'BN', 'BO', 'BQ', 'BR', 'BS', 'BT', 'BV', 'BW', 'BY', 'BZ', 'CA', 'CC', 'CD', 'CF', 'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN', 'CO', 'CR', 'CU', 'CV', 'CW', 'CX', 'CY', 'CZ', 'DE', 'DJ', 'DK', 'DM', 'DO', 'DZ', 'EC', 'EE', 'EG', 'EH', 'ER', 'ES', 'ET', 'FI', 'FJ', 'FK', 'FM', 'FO', 'FR', 'GA', 'GB', 'GD', 'GE', 'GF', 'GG', 'GH', 'GI', 'GL', 'GM', 'GN', 'GP', 'GQ', 'GR', 'GS', 'GT', 'GU', 'GW', 'GY', 'HK', 'HM', 'HN', 'HR', 'HT', 'HU', 'ID', 'IE', 'IL', 'IM', 'IN', 'IO', 'IQ', 'IR', 'IS', 'IT', 'JE', 'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', 'KP', 'KR', 'KW', 'KY', 'KZ', 'LA', 'LB', 'LC', 'LI', 'LK', 'LR', 'LS', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'ME', 'MF', 'MG', 'MH', 'MK', 'ML', 'MM', 'MN', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT', 'MU', 'MV', 'MW', 'MX', 'MY', 'MZ', 'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NL', 'NO', 'NP', 'NR', 'NU', 'NZ', 'OM', 'PA', 'PE', 'PF', 'PG', 'PH', 'PK', 'PL', 'PM', 'PN', 'PR', 'PS', 'PT', 'PW', 'PY', 'QA', 'RE', 'RO', 'RS', 'RU', 'RW', 'SA', 'SB', 'SC', 'SD', 'SE', 'SG', 'SH', 'SI', 'SJ', 'SK', 'SL', 'SM', 'SN', 'SO', 'SR', 'SS', 'ST', 'SV', 'SX', 'SY', 'SZ', 'TC', 'TD', 'TF', 'TG', 'TH', 'TJ', 'TK', 'TL', 'TM', 'TN', 'TO', 'TR', 'TT', 'TV', 'TW', 'TZ', 'UA', 'UG', 'UM', 'US', 'UY', 'UZ', 'VA', 'VC', 'VE', 'VG', 'VI', 'VN', 'VU', 'WF', 'WS', 'YE', 'YT', 'ZA', 'ZM', 'ZW' );
100	}
101
102	/**
103	* Get the tracking URL for a given tracking number.
104	*
105	* @param string $tracking_number The tracking number to generate the URL for.
106	* @return string The tracking URL.
107	*/
108	public function get_tracking_url( string $tracking_number ): string {
109	return 'https://www.canadapost-postescanada.ca/track-reperage/en#/search?searchFor=' . rawurlencode( $tracking_number );
110	}
111
112	/**
113	* Validate tracking number against country-specific patterns.
114	*
115	* @param string $tracking_number The tracking number to validate.
116	* @param string $country_code The country code for the shipment.
117	* @return bool True if valid, false otherwise.
118	*/
119	private function validate_country_pattern( string $tracking_number, string $country_code ): bool {
120	if ( ! isset( self::TRACKING_PATTERNS[ $country_code ] ) ) {
121	return false;
122	}
123
124	foreach ( self::TRACKING_PATTERNS[ $country_code ]['patterns'] as $pattern ) {
125	if ( preg_match( $pattern, $tracking_number ) ) {
126	return true;
127	}
128	}
129	return false;
130	}
131
132	/**
133	* Try to parse a Canada Post tracking number.
134	*
135	* @param string $tracking_number The tracking number to parse.
136	* @param string $shipping_from The country code of the shipping origin.
137	* @param string $shipping_to The country code of the shipping destination.
138	* @return array\|null An array with 'url' and 'ambiguity_score' if valid, null otherwise.
139	*/
140	public function try_parse_tracking_number(
141	string $tracking_number,
142	string $shipping_from,
143	string $shipping_to
144	): ?array {
145	if ( empty( $tracking_number ) \|\| empty( $shipping_from ) \|\| empty( $shipping_to ) ) {
146	return null;
147	}
148
149	$normalized = strtoupper( preg_replace( '/\s+/', '', $tracking_number ) ); // Normalize input.
150	if ( empty( $normalized ) ) {
151	return null;
152	}
153
154	$shipping_from = strtoupper( $shipping_from );
155	$shipping_to = strtoupper( $shipping_to );
156
157	// Check if shipping from Canada.
158	if ( 'CA' !== $shipping_from ) {
159	return null;
160	}
161
162	// Check country-specific patterns with enhanced validation.
163	if ( $this->validate_country_pattern( $normalized, $shipping_from ) ) {
164	$confidence = self::TRACKING_PATTERNS[ $shipping_from ]['confidence'];
165
166	// Apply UPU S10 validation for international formats.
167	if ( preg_match( '/^[A-Z]{2}\d{9}CA$/', $normalized ) ) {
168	if ( FulfillmentUtils::check_s10_upu_format( $normalized ) ) {
169	$confidence = min( 98, $confidence + 6 ); // Strong boost for valid UPU.
170	}
171	} elseif ( preg_match( '/^[A-Z]{2}\d{9}[A-Z]{2}$/', $normalized ) ) {
172	// Apply S10/UPU fallback with lower confidence.
173	if ( FulfillmentUtils::check_s10_upu_format( $normalized ) ) {
174	$confidence = min( 94, $confidence + 2 ); // Lower boost for inbound S10.
175	}
176	}
177
178	// Apply check digit validation for numeric formats.
179	if ( preg_match( '/^\d{12,16}$/', $normalized ) ) {
180	if ( FulfillmentUtils::validate_mod10_check_digit( $normalized ) ) {
181	$confidence = min( 96, $confidence + 4 ); // Boost for valid check digit.
182	}
183	}
184
185	// Service-specific confidence boosts.
186	if ( preg_match( '/^(XP\|EX\|PR)\d+/', $normalized ) ) {
187	$confidence = min( 96, $confidence + 4 ); // Express/Priority services.
188	} elseif ( preg_match( '/^(RM\|CM)\d+/', $normalized ) ) {
189	$confidence = min( 95, $confidence + 3 ); // Registered/Certified.
190	} elseif ( preg_match( '/^(FD\|PO\|CP\|SM)\d+/', $normalized ) ) {
191	$confidence = min( 94, $confidence + 2 ); // Special services.
192	}
193
194	// Boost confidence for domestic shipments.
195	if ( 'CA' === $shipping_to ) {
196	$confidence = min( 98, $confidence + 3 );
197	}
198
199	// Boost for North American destinations.
200	if ( in_array( $shipping_to, array( 'US', 'MX' ), true ) ) {
201	$confidence = min( 95, $confidence + 2 );
202	}
203
204	return array(
205	'url' => $this->get_tracking_url( $normalized ),
206	'ambiguity_score' => $confidence,
207	);
208	}
209
210	return null;
211	}
212	}
213