class-wc-rest-data-countries-controller.php at 11.1.0 · WooCommerce

woocommerce / includes / rest-api / Controllers / Version3 / class-wc-rest-data-countries-controller.php

class-wc-rest-data-countries-controller.php

319 lines 9.4 KB

Raw Download Zip

1	<?php
2	/**
3	* REST API Data countries controller.
4	*
5	* Handles requests to the /data/countries endpoint.
6	*
7	* @package WooCommerce\RestApi
8	* @since 3.5.0
9	*/
10
11	use Automattic\WooCommerce\Internal\Traits\RestApiCache;
12
13	defined( 'ABSPATH' ) \|\| exit;
14
15	/**
16	* REST API Data countries controller class.
17	*
18	* @package WooCommerce\RestApi
19	* @extends WC_REST_Controller
20	*/
21	class WC_REST_Data_Countries_Controller extends WC_REST_Data_Controller {
22
23	use RestApiCache;
24
25	/**
26	* Endpoint namespace.
27	*
28	* @var string
29	*/
30	protected $namespace = 'wc/v3';
31
32	/**
33	* Route base.
34	*
35	* @var string
36	*/
37	protected $rest_base = 'data/countries';
38
39	/**
40	* Constructor.
41	*/
42	public function __construct() {
43	$this->initialize_rest_api_cache();
44	}
45
46	/**
47	* Register routes.
48	*
49	* @since 3.5.0
50	*/
51	public function register_routes() {
52	register_rest_route(
53	$this->namespace,
54	'/' . $this->rest_base,
55	array(
56	array(
57	'methods' => WP_REST_Server::READABLE,
58	'callback' => $this->with_cache( array( $this, 'get_items' ) ),
59	'permission_callback' => array( $this, 'get_items_permissions_check' ),
60	),
61	'schema' => array( $this, 'get_public_item_schema' ),
62	)
63	);
64	register_rest_route(
65	$this->namespace,
66	'/' . $this->rest_base . '/(?P<location>[\w-]+)',
67	array(
68	array(
69	'methods' => WP_REST_Server::READABLE,
70	'callback' => $this->with_cache( array( $this, 'get_item' ) ),
71	'permission_callback' => array( $this, 'get_items_permissions_check' ),
72	'args' => array(
73	'location' => array(
74	'description' => __( 'ISO3166 alpha-2 country code.', 'woocommerce' ),
75	'type' => 'string',
76	),
77	),
78	),
79	'schema' => array( $this, 'get_public_item_schema' ),
80	)
81	);
82	}
83
84	/**
85	* Get a list of countries and states.
86	*
87	* @param string $country_code Country code.
88	* @param WP_REST_Request $request Request data.
89	* @return array\|mixed Response data, ready for insertion into collection data.
90	*/
91	public function get_country( $country_code, $request ) {
92	$countries = WC()->countries->get_countries();
93	$states = WC()->countries->get_states();
94	$data = array();
95
96	if ( ! array_key_exists( $country_code, $countries ) ) {
97	return false;
98	}
99
100	$country = array(
101	'code' => $country_code,
102	'name' => $countries[ $country_code ],
103	);
104
105	$local_states = array();
106	if ( isset( $states[ $country_code ] ) ) {
107	foreach ( $states[ $country_code ] as $state_code => $state_name ) {
108	$local_states[] = array(
109	'code' => $state_code,
110	'name' => $state_name,
111	);
112	}
113	}
114	$country['states'] = $local_states;
115	return $country;
116	}
117
118	/**
119	* Return the list of states for all countries.
120	*
121	* @since 3.5.0
122	* @param WP_REST_Request $request Request data.
123	* @return WP_Error\|WP_REST_Response
124	*/
125	public function get_items( $request ) {
126	$countries = WC()->countries->get_countries();
127	$data = array();
128
129	foreach ( array_keys( $countries ) as $country_code ) {
130	$country = $this->get_country( $country_code, $request );
131	$response = $this->prepare_item_for_response( $country, $request );
132	$data[] = $this->prepare_response_for_collection( $response );
133	}
134
135	return rest_ensure_response( $data );
136	}
137
138	/**
139	* Return the list of states for a given country.
140	*
141	* @since 3.5.0
142	* @param WP_REST_Request $request Request data.
143	* @return WP_Error\|WP_REST_Response
144	*/
145	public function get_item( $request ) {
146	$data = $this->get_country( strtoupper( $request['location'] ), $request );
147	if ( empty( $data ) ) {
148	return new WP_Error( 'woocommerce_rest_data_invalid_location', __( 'There are no locations matching these parameters.', 'woocommerce' ), array( 'status' => 404 ) );
149	}
150	return $this->prepare_item_for_response( $data, $request );
151	}
152
153	/**
154	* Prepare the data object for response.
155	*
156	* @since 3.5.0
157	* @param object $item Data object.
158	* @param WP_REST_Request $request Request object.
159	* @return WP_REST_Response $response Response data.
160	*/
161	public function prepare_item_for_response( $item, $request ) {
162	$data = $this->add_additional_fields_to_object( $item, $request );
163	$data = $this->filter_response_by_context( $data, 'view' );
164	$response = rest_ensure_response( $data );
165
166	$response->add_links( $this->prepare_links( $item ) );
167
168	/**
169	* Filter the states list for a country returned from the API.
170	*
171	* Allows modification of the location data right before it is returned.
172	*
173	* @since 3.5.0
174	*
175	* @param WP_REST_Response $response The response object.
176	* @param array $data The original country's states list.
177	* @param WP_REST_Request $request Request used to generate the response.
178	*/
179	return apply_filters( 'woocommerce_rest_prepare_data_country', $response, $item, $request );
180	}
181
182	/**
183	* Prepare links for the request.
184	*
185	* @param object $item Data object.
186	* @return array Links for the given country.
187	*/
188	protected function prepare_links( $item ) {
189	$country_code = strtolower( $item['code'] );
190	$links = array(
191	'self' => array(
192	'href' => rest_url( sprintf( '/%s/%s/%s', $this->namespace, $this->rest_base, $country_code ) ),
193	),
194	'collection' => array(
195	'href' => rest_url( sprintf( '/%s/%s', $this->namespace, $this->rest_base ) ),
196	),
197	);
198
199	return $links;
200	}
201
202
203	/**
204	* Get the location schema, conforming to JSON Schema.
205	*
206	* @since 3.5.0
207	* @return array
208	*/
209	public function get_item_schema() {
210	$schema = array(
211	'$schema' => 'http://json-schema.org/draft-04/schema#',
212	'title' => 'data_countries',
213	'type' => 'object',
214	'properties' => array(
215	'code' => array(
216	'type' => 'string',
217	'description' => __( 'ISO3166 alpha-2 country code.', 'woocommerce' ),
218	'context' => array( 'view' ),
219	'readonly' => true,
220	),
221	'name' => array(
222	'type' => 'string',
223	'description' => __( 'Full name of country.', 'woocommerce' ),
224	'context' => array( 'view' ),
225	'readonly' => true,
226	),
227	'states' => array(
228	'type' => 'array',
229	'description' => __( 'List of states in this country.', 'woocommerce' ),
230	'context' => array( 'view' ),
231	'readonly' => true,
232	'items' => array(
233	'type' => 'object',
234	'context' => array( 'view' ),
235	'readonly' => true,
236	'properties' => array(
237	'code' => array(
238	'type' => 'string',
239	'description' => __( 'State code.', 'woocommerce' ),
240	'context' => array( 'view' ),
241	'readonly' => true,
242	),
243	'name' => array(
244	'type' => 'string',
245	'description' => __( 'Full name of state.', 'woocommerce' ),
246	'context' => array( 'view' ),
247	'readonly' => true,
248	),
249	),
250	),
251	),
252	),
253	);
254
255	return $this->add_additional_fields_schema( $schema );
256	}
257
258	/**
259	* Get the default entity type for response caching.
260	*
261	* @return string\|null The entity type.
262	*/
263	protected function get_default_response_entity_type(): ?string {
264	return 'country';
265	}
266
267	/**
268	* Get the files relevant to response caching.
269	*
270	* @param WP_REST_Request<array<string, mixed>> $request The request object.
271	* @param string\|null $endpoint_id Optional endpoint identifier.
272	* @return array Array of file paths to track for cache invalidation.
273	*/
274	protected function get_files_relevant_to_response_caching( WP_REST_Request $request, ?string $endpoint_id = null ): array { // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
275	return array( 'i18n/countries.php', 'i18n/states.php' );
276	}
277
278	/**
279	* Get the hooks relevant to response caching.
280	*
281	* @param WP_REST_Request<array<string, mixed>> $request The request object.
282	* @param string\|null $endpoint_id Optional endpoint identifier.
283	* @return array Array of hook names to track for cache invalidation.
284	*/
285	protected function get_hooks_relevant_to_caching( WP_REST_Request $request, ?string $endpoint_id = null ): array { // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
286	return array(
287	'woocommerce_countries',
288	'woocommerce_states',
289	'woocommerce_sort_countries',
290	'woocommerce_rest_prepare_data_country',
291	);
292	}
293
294	/**
295	* Whether the response cache should vary by user.
296	*
297	* @param WP_REST_Request<array<string, mixed>> $request The request object.
298	* @param string\|null $endpoint_id Optional endpoint identifier.
299	* @return bool False since country data doesn't vary by user.
300	*/
301	protected function response_cache_vary_by_user( WP_REST_Request $request, ?string $endpoint_id = null ): bool { // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
302	return false;
303	}
304
305	/**
306	* Extract entity IDs from response data.
307	*
308	* Countries don't have entity IDs, cache invalidation is file-based.
309	*
310	* @param array $response_data Response data.
311	* @param WP_REST_Request<array<string, mixed>> $request The request object.
312	* @param string\|null $endpoint_id Optional endpoint identifier.
313	* @return array Empty array since countries don't have entity IDs.
314	*/
315	protected function extract_entity_ids_from_response( array $response_data, WP_REST_Request $request, ?string $endpoint_id = null ): array { // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
316	return array();
317	}
318	}
319