DHLShippingProvider.php — WooCommerce 10.9.4

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

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

DHLShippingProvider.php

196 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	* DHL Shipping Provider implementation.
9	*
10	* Handles DHL tracking number detection and validation for all DHL services.
11	*/
12	class DHLShippingProvider extends AbstractShippingProvider {
13	/**
14	* List of countries where DHL has significant operations.
15	*
16	* @var array<string>
17	*/
18	private array $major_operation_countries = array( 'DE', 'US', 'CA', 'GB', 'SG', 'JP', 'HK', 'NL', 'FR', 'IT', 'AU', 'CN', 'IN', 'ES', 'BE', 'CH', 'AT', 'SE', 'DK', 'NO', 'PL', 'CZ', 'FI', 'IE', 'PT', 'GR', 'HU', 'RO', 'BG', 'HR', 'SK', 'SI', 'LT', 'LV', 'EE', 'CY', 'MT', 'LU' );
19
20	/**
21	* Gets the unique provider key.
22	*
23	* @return string The provider key 'dhl'.
24	*/
25	public function get_key(): string {
26	return 'dhl';
27	}
28
29	/**
30	* Gets the display name of the provider.
31	*
32	* @return string The provider name 'DHL'.
33	*/
34	public function get_name(): string {
35	return 'DHL';
36	}
37
38	/**
39	* Gets the path to the provider's icon.
40	*
41	* @return string URL to the DHL logo image.
42	*/
43	public function get_icon(): string {
44	return esc_url( WC()->plugin_url() ) . '/assets/images/shipping_providers/dhl.png';
45	}
46
47	/**
48	* Generates the appropriate tracking URL based on DHL service type.
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	$tracking_number = strtoupper( $tracking_number ); // Uppercase for consistency.
55
56	// DHL Global Mail and eCommerce prefixes.
57	if ( preg_match( '/^(GM\|LX\|RX\|CN\|SG\|MY\|HK\|AU\|TH\|420)/', $tracking_number ) ) {
58	return 'https://webtrack.dhlglobalmail.com/?trackingnumber=' . rawurlencode( $tracking_number );
59	}
60
61	// DHL Paket Germany (3S...).
62	if ( preg_match( '/^3S[A-Z0-9]{8,12}$/', $tracking_number ) ) {
63	return 'https://www.dhl.de/en/privatkunden/dhl-sendungsverfolgung.html?piececode=' . rawurlencode( $tracking_number );
64	}
65
66	// Standard DHL Express tracking.
67	return 'https://www.dhl.com/en/express/tracking.html?AWB=' . rawurlencode( $tracking_number );
68	}
69
70	/**
71	* Gets the list of origin countries supported by DHL.
72	*
73	* @return array<string> Array of country codes.
74	*/
75	public function get_shipping_from_countries(): array {
76	return $this->major_operation_countries;
77	}
78
79	/**
80	* Gets the list of destination countries supported by DHL.
81	*
82	* @return array<string> Array of country codes.
83	*/
84	public function get_shipping_to_countries(): array {
85	return array_keys( wc()->countries->get_countries() );
86	}
87
88	/**
89	* Checks if DHL can ship between two countries.
90	*
91	* @param string $shipping_from Origin country code.
92	* @param string $shipping_to Destination country code.
93	* @return bool True if shipping route is supported.
94	*/
95	public function can_ship_from_to( string $shipping_from, string $shipping_to ): bool {
96	return in_array( $shipping_from, $this->get_shipping_from_countries(), true ) &&
97	in_array( $shipping_to, $this->get_shipping_to_countries(), true );
98	}
99
100	/**
101	* Validates and parses a DHL tracking number.
102	*
103	* @param string $tracking_number The tracking number to validate.
104	* @param string $shipping_from Origin country code.
105	* @param string $shipping_to Destination country code.
106	* @return array\|null Array with tracking URL and score, or null if invalid.
107	*/
108	public function try_parse_tracking_number( string $tracking_number, string $shipping_from, string $shipping_to ): ?array {
109	if ( empty( $tracking_number ) \|\| ! $this->can_ship_from_to( $shipping_from, $shipping_to ) ) {
110	return null;
111	}
112
113	$tracking_number = strtoupper( preg_replace( '/\s+/', '', $tracking_number ) ); // Remove spaces and uppercase for consistency.
114	$is_major_country = in_array( $shipping_from, $this->major_operation_countries, true ); // Major operation region flag.
115
116	// DHL tracking number patterns with enhanced validation and comments.
117	$patterns = array(
118	// DHL Express Air Waybill: 10 or 11 digits, with check digit validation.
119	'/^\d{10}$/' => function () use ( $tracking_number ) {
120	return FulfillmentUtils::validate_mod11_check_digit( $tracking_number ) ? 98 : 90;
121	},
122	'/^\d{11}$/' => function () use ( $tracking_number ) {
123	return FulfillmentUtils::validate_mod11_check_digit( $tracking_number ) ? 98 : 90;
124	},
125
126	// DHL Express JJD and JVGL formats.
127	'/^JJD\d{10}$/' => 98,
128	'/^JVGL\d{10}$/' => 98,
129
130	// DHL Paket Germany: 12, 14, or 20 digits.
131	// Only match 12/14-digit numeric for DHL if both from and to are DE (Germany).
132	'/^\d{12}$/' => function () use ( $shipping_from, $shipping_to ) {
133	return ( 'DE' === $shipping_from && 'DE' === $shipping_to ) ? 92 : 60;
134	},
135	'/^\d{14}$/' => function () use ( $shipping_from, $shipping_to ) {
136	return ( 'DE' === $shipping_from && 'DE' === $shipping_to ) ? 92 : 60;
137	},
138	'/^\d{20}$/' => 90,
139
140	// DHL Paket Germany: 3S + 8–12 alphanumeric.
141	'/^3S[A-Z0-9]{8,12}$/' => 95,
142
143	// DHL eCommerce North America: GM + 16–20 digits.
144	'/^GM\d{16,20}$/' => function () use ( $shipping_from ) {
145	return in_array( $shipping_from, array( 'US', 'CA' ), true ) ? 95 : 80;
146	},
147
148	// DHL eCommerce Asia-Pacific: LX, RX, CN, SG, MY, HK, AU, TH + 9 digits + 2 letters.
149	'/^(LX\|RX\|CN\|SG\|MY\|HK\|AU\|TH)\d{9}[A-Z]{2}$/' => 92,
150
151	// DHL eCommerce US consolidator: 420 + 27–31 digits.
152	'/^420\d{23,31}$/' => 90,
153
154	// DHL Global Forwarding: 7, 8, or 9 digits (numeric only).
155	'/^\d{7,9}$/' => 88,
156
157	// DHL Global Forwarding: 1 digit + 2 letters + 4–6 digits.
158	'/^\d[A-Z]{2}\d{4,6}$/' => 90,
159
160	// DHL Global Forwarding: 3–4 letters + 4–8 digits.
161	'/^[A-Z]{3,4}\d{4,8}$/' => 88,
162
163	// DHL Same Day: DSD + 8–12 digits.
164	'/^DSD\d{8,12}$/' => 92,
165
166	// DHL Piece Numbers: JD + 11 digits.
167	'/^JD\d{11}$/' => 90,
168
169	// DHL Supply Chain: DSC + 10–15 digits.
170	'/^DSC\d{10,15}$/' => 85,
171
172	// S10/UPU format: 2 letters + 9 digits + 2 letters (used for DHL eCommerce and Packet International).
173	'/^[A-Z]{2}\d{9}[A-Z]{2}$/' => function () use ( $tracking_number ) {
174	return FulfillmentUtils::check_s10_upu_format( $tracking_number ) ? 88 : 75;
175	},
176
177	// Fallback: 22 digit numeric (legacy/rare).
178	'/^\d{22}$/' => 70,
179	);
180
181	foreach ( $patterns as $pattern => $base_score ) {
182	if ( preg_match( $pattern, $tracking_number ) ) {
183	$score = is_callable( $base_score ) ? $base_score() : $base_score;
184	if ( $score > 0 ) {
185	return array(
186	'url' => $this->get_tracking_url( $tracking_number ),
187	'ambiguity_score' => $score,
188	);
189	}
190	}
191	}
192
193	return null;
194	}
195	}
196