CustomShippingProvider.php — WooCommerce 10.9.4

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

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

CustomShippingProvider.php

115 lines

1	<?php declare(strict_types=1);
2
3	namespace Automattic\WooCommerce\Admin\Features\Fulfillments\Providers;
4
5	/**
6	* Custom shipping provider loaded from the wc_fulfillment_shipping_provider taxonomy.
7	*
8	* Unlike built-in providers, custom providers do not support automatic tracking
9	* number parsing; they rely on user-supplied tracking URL templates.
10	*
11	* @since 10.7.0
12	*/
13	class CustomShippingProvider extends AbstractShippingProvider {
14
15	/**
16	* The provider key (taxonomy term slug).
17	*
18	* @var string
19	*/
20	private string $key;
21
22	/**
23	* The provider display name.
24	*
25	* @var string
26	*/
27	private string $name;
28
29	/**
30	* The provider icon URL.
31	*
32	* @var string
33	*/
34	private string $icon;
35
36	/**
37	* The tracking URL template containing __PLACEHOLDER__ for the tracking number.
38	*
39	* @var string
40	*/
41	private string $tracking_url_template;
42
43	/**
44	* Constructor.
45	*
46	* @param string $key The provider key (term slug).
47	* @param string $name The provider display name.
48	* @param string $icon The provider icon URL.
49	* @param string $tracking_url_template The tracking URL template.
50	*/
51	public function __construct( string $key, string $name, string $icon, string $tracking_url_template ) {
52	$this->key = $key;
53	$this->name = $name;
54	$this->icon = $icon;
55	$this->tracking_url_template = $tracking_url_template;
56	}
57
58	/**
59	* Get the key of the shipping provider.
60	*
61	* @return string
62	*/
63	public function get_key(): string {
64	return $this->key;
65	}
66
67	/**
68	* Get the name of the shipping provider.
69	*
70	* @return string
71	*/
72	public function get_name(): string {
73	return $this->name;
74	}
75
76	/**
77	* Get the icon URL of the shipping provider.
78	*
79	* @return string
80	*/
81	public function get_icon(): string {
82	return $this->icon;
83	}
84
85	/**
86	* Get the tracking URL for a given tracking number.
87	*
88	* Replaces __PLACEHOLDER__ in the template with the actual tracking number.
89	*
90	* @param string $tracking_number The tracking number.
91	* @return string The tracking URL with the placeholder replaced.
92	*/
93	public function get_tracking_url( string $tracking_number ): string {
94	if ( empty( $this->tracking_url_template ) ) {
95	return '';
96	}
97
98	return str_replace( '__PLACEHOLDER__', rawurlencode( $tracking_number ), $this->tracking_url_template );
99	}
100
101	/**
102	* Custom providers do not support automatic tracking number parsing.
103	*
104	* @param string $tracking_number The tracking number.
105	* @param string $shipping_from The country code from which the shipment is sent.
106	* @param string $shipping_to The country code to which the shipment is sent.
107	* @return array\|null Always returns null for custom providers.
108	*
109	* phpcs:disable Generic.CodeAnalysis.UnusedFunctionParameter
110	*/
111	public function try_parse_tracking_number( string $tracking_number, string $shipping_from, string $shipping_to ): ?array {
112	return null;
113	}
114	}
115