FedExShippingProvider.php — WooCommerce 10.9.4

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

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

FedExShippingProvider.php

190 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	* FedEx Shipping Provider implementation.
9	*
10	* Handles FedEx tracking number detection and validation for all FedEx services.
11	*/
12	class FedExShippingProvider extends AbstractShippingProvider {
13	/**
14	* List of countries where FedEx has significant operations.
15	*
16	* @var array<string>
17	*/
18	private array $supported_countries = array( 'US', 'CA', 'GB', 'DE', 'FR', 'AU', 'JP', 'MX', 'CN', 'IN', 'IT', 'ES', 'NL', 'BE', 'CH', 'AT', 'BR', 'SG' );
19
20	/**
21	* Gets the unique provider key.
22	*
23	* @return string The provider key 'fedex'.
24	*/
25	public function get_key(): string {
26	return 'fedex';
27	}
28
29	/**
30	* Gets the display name of the provider.
31	*
32	* @return string The provider name 'FedEx'.
33	*/
34	public function get_name(): string {
35	return 'FedEx';
36	}
37
38	/**
39	* Gets the path to the provider's icon.
40	*
41	* @return string URL to the FedEx logo image.
42	*/
43	public function get_icon(): string {
44	return esc_url( WC()->plugin_url() ) . '/assets/images/shipping_providers/fedex.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://www.fedex.com/fedextrack/?tracknumbers=' . rawurlencode( $tracking_number );
55	}
56
57	/**
58	* Gets the list of origin countries supported by FedEx.
59	*
60	* @return array<string> Array of country codes.
61	*/
62	public function get_shipping_from_countries(): array {
63	return $this->supported_countries;
64	}
65
66	/**
67	* Gets the list of destination countries supported by FedEx.
68	*
69	* @return array<string> Array of country codes.
70	*/
71	public function get_shipping_to_countries(): array {
72	return $this->supported_countries;
73	}
74
75	/**
76	* Checks if FedEx can ship between two countries.
77	*
78	* @param string $shipping_from Origin country code.
79	* @param string $shipping_to Destination country code.
80	* @return bool True if shipping route is supported.
81	*/
82	public function can_ship_from_to( string $shipping_from, string $shipping_to ): bool {
83	return in_array( $shipping_from, $this->supported_countries, true ) &&
84	in_array( $shipping_to, $this->supported_countries, true );
85	}
86
87	/**
88	* Validates and parses a FedEx tracking number.
89	*
90	* @param string $tracking_number The tracking number to validate.
91	* @param string $shipping_from Origin country code.
92	* @param string $shipping_to Destination country code.
93	* @return array\|null Array with tracking URL and score, or null if invalid.
94	*/
95	public function try_parse_tracking_number( string $tracking_number, string $shipping_from, string $shipping_to ): ?array {
96	if ( empty( $tracking_number ) \|\| ! $this->can_ship_from_to( $shipping_from, $shipping_to ) ) {
97	return null;
98	}
99
100	$tracking_number = strtoupper( preg_replace( '/\s+/', '', $tracking_number ) ); // Remove spaces and uppercase for consistency.
101	$is_north_america = in_array( $shipping_from, array( 'US', 'CA' ), true ); // North America flag for scoring.
102	$is_us_domestic = 'US' === $shipping_from && 'US' === $shipping_to; // US domestic flag for scoring.
103
104	// FedEx tracking number patterns with enhanced validation and comments.
105	$patterns = array(
106	// FedEx Door Tag: DT + 12 digits (US/CA only).
107	'/^DT\d{12}$/' => $is_north_america ? 90 : 0,
108
109	// FedEx Custom Critical: 0 or 1 followed by 13-23 digits (very rare, highest confidence).
110	'/^0[01]\d{13,23}$/' => 98,
111
112	// FedEx SmartPost: 023 + 17 digits (US only, SmartPost).
113	'/^023\d{17}$/' => 97,
114
115	// FedEx SmartPost: 58 + 17-19 digits (older SmartPost).
116	'/^58\d{17,19}$/' => 96,
117
118	// FedEx Express: 12 digits (most common, with check digit validation).
119	'/^\d{12}$/' => function () use ( $tracking_number, $is_north_america, $is_us_domestic ) {
120	if ( FulfillmentUtils::validate_fedex_check_digit( $tracking_number ) ) {
121	return $is_north_america \|\| $is_us_domestic ? 98 : 85; // High confidence if check digit valid.
122	}
123	return $is_north_america ? ( $is_us_domestic ? 98 : 85 ) : 70; // Lower if check digit invalid.
124	},
125
126	// FedEx Express: 15 digits (less common, with check digit validation).
127	'/^\d{15}$/' => function () use ( $tracking_number, $is_north_america ) {
128	if ( FulfillmentUtils::validate_fedex_check_digit( $tracking_number ) ) {
129	return $is_north_america ? 96 : 80; // High confidence if check digit valid.
130	}
131	return $is_north_america ? 80 : 65; // Lower if check digit invalid.
132	},
133
134	// FedEx Express: 14 digits (with check digit validation).
135	'/^\d{14}$/' => function () use ( $tracking_number, $is_north_america ) {
136	if ( FulfillmentUtils::validate_fedex_check_digit( $tracking_number ) ) {
137	return $is_north_america ? 95 : 78; // High confidence if check digit valid.
138	}
139	return $is_north_america ? 78 : 60; // Lower if check digit invalid.
140	},
141
142	// FedEx Express: 34 digits (rare, international bulk shipments).
143	'/^\d{34}$/' => 90,
144
145	// FedEx Ground: 96 + 18-20 digits (US/CA only).
146	'/^96\d{18,20}$/' => $is_north_america ? 95 : 60,
147
148	// FedEx Ground: 7 + 11-20 digits (US/CA only, legacy).
149	'/^7\d{11,20}$/' => $is_north_america ? 90 : 75,
150
151	// FedEx Freight: 97 + 13-23 digits (Freight/LTL).
152	'/^97\d{13,23}$/' => 93,
153
154	// FedEx Express International: 3 + 10-14 digits (Europe/Asia).
155	'/^3\d{10,14}$/' => 92,
156
157	// FedEx International Priority: 8 + 8-14 digits (Europe/Asia).
158	'/^8\d{8,14}$/' => function () use ( $shipping_from ) {
159	return in_array( $shipping_from, array( 'GB', 'DE', 'FR', 'IT', 'ES', 'NL' ), true ) ? 93 : 75;
160	},
161
162	// FedEx Express Next Flight Out: NFO + 10-15 digits.
163	'/^NFO\d{10,15}$/' => 92,
164
165	// FedEx SameDay: SD + 10-15 digits.
166	'/^SD\d{10,15}$/' => 90,
167
168	// Fallback: 20 digit numeric (used by some international and legacy services).
169	'/^\d{20}$/' => 70,
170
171	// Fallback: 22 digit numeric (rare, legacy).
172	'/^\d{22}$/' => 65,
173	);
174
175	foreach ( $patterns as $pattern => $base_score ) {
176	if ( preg_match( $pattern, $tracking_number ) ) {
177	$score = is_callable( $base_score ) ? $base_score() : $base_score;
178	if ( $score > 0 ) {
179	return array(
180	'url' => $this->get_tracking_url( $tracking_number ),
181	'ambiguity_score' => $score,
182	);
183	}
184	}
185	}
186
187	return null; // No matching pattern found.
188	}
189	}
190