Products.php — WooCommerce 10.9.4

woocommerce / src / StoreApi / Routes / V1 / Products.php

woocommerce / src / StoreApi / Routes / V1 Last commit date

Products.php

451 lines

1	<?php
2	declare( strict_types = 1 );
3
4	namespace Automattic\WooCommerce\StoreApi\Routes\V1;
5
6	use Automattic\WooCommerce\Enums\ProductType;
7	use Automattic\WooCommerce\Enums\CatalogVisibility;
8	use Automattic\WooCommerce\StoreApi\Utilities\Pagination;
9	use Automattic\WooCommerce\StoreApi\Utilities\ProductQuery;
10	use Automattic\WooCommerce\StoreApi\Utilities\ProductLinksTrait;
11
12	/**
13	* Products class.
14	*/
15	class Products extends AbstractRoute {
16	use ProductLinksTrait;
17
18	/**
19	* The route identifier.
20	*
21	* @var string
22	*/
23	const IDENTIFIER = 'products';
24
25	/**
26	* The routes schema.
27	*
28	* @var string
29	*/
30	const SCHEMA_TYPE = 'product';
31
32	/**
33	* Get the path of this REST route.
34	*
35	* @return string
36	*/
37	public function get_path() {
38	return self::get_path_regex();
39	}
40
41	/**
42	* Get the path of this rest route.
43	*
44	* @return string
45	*/
46	public static function get_path_regex() {
47	return '/products';
48	}
49
50	/**
51	* Get method arguments for this REST route.
52	*
53	* @return array An array of endpoints.
54	*/
55	public function get_args() {
56	return [
57	[
58	'methods' => \WP_REST_Server::READABLE,
59	'callback' => [ $this, 'get_response' ],
60	'permission_callback' => '__return_true',
61	'args' => $this->get_collection_params(),
62	'allow_batch' => [ 'v1' => true ],
63	],
64	'schema' => [ $this->schema, 'get_public_item_schema' ],
65	];
66	}
67
68	/**
69	* Get a collection of posts and add the post title filter option to \WP_Query.
70	*
71	* @param \WP_REST_Request $request Request object.
72	* @return \WP_REST_Response
73	*/
74	protected function get_route_response( \WP_REST_Request $request ) {
75	$response = new \WP_REST_Response();
76	$product_query = new ProductQuery();
77
78	// Only get objects during GET requests.
79	if ( \WP_REST_Server::READABLE === $request->get_method() ) {
80	$query_results = $product_query->get_objects( $request );
81	$response_objects = [];
82
83	foreach ( $query_results['objects'] as $object ) {
84	$data = $this->prepare_item_for_response( $object, $request );
85	$response_objects[] = $this->prepare_response_for_collection( $data );
86	}
87
88	$response->set_data( $response_objects );
89	} else {
90	$query_results = $product_query->get_results( $request );
91	}
92
93	$response = ( new Pagination() )->add_headers( $response, $request, $query_results['total'], $query_results['pages'] );
94	$last_modified = $product_query->get_last_modified();
95	if ( $last_modified ) {
96	$response->header( 'Last-Modified', $last_modified );
97	}
98
99	return $response;
100	}
101
102	/**
103	* Get the query params for collections of products.
104	*
105	* @return array
106	*/
107	public function get_collection_params() {
108	$params = [];
109	$params['context'] = $this->get_context_param();
110	$params['context']['default'] = 'view';
111
112	$params['page'] = array(
113	'description' => __( 'Current page of the collection.', 'woocommerce' ),
114	'type' => 'integer',
115	'default' => 1,
116	'sanitize_callback' => 'absint',
117	'validate_callback' => 'rest_validate_request_arg',
118	'minimum' => 1,
119	);
120
121	$params['per_page'] = array(
122	'description' => __( 'Maximum number of items to be returned in result set.', 'woocommerce' ),
123	'type' => 'integer',
124	'default' => 10,
125	'minimum' => 1,
126	'maximum' => 100,
127	'sanitize_callback' => 'absint',
128	'validate_callback' => 'rest_validate_request_arg',
129	);
130
131	$params['search'] = array(
132	'description' => __( 'Limit results to those matching a string.', 'woocommerce' ),
133	'type' => 'string',
134	'sanitize_callback' => 'sanitize_text_field',
135	'validate_callback' => 'rest_validate_request_arg',
136	);
137
138	$params['slug'] = array(
139	'description' => __( 'Limit result set to products with specific slug(s). Use commas to separate.', 'woocommerce' ),
140	'type' => 'string',
141	'sanitize_callback' => 'sanitize_text_field',
142	'validate_callback' => 'rest_validate_request_arg',
143	);
144
145	$params['after'] = array(
146	'description' => __( 'Limit response to resources created after a given ISO8601 compliant date.', 'woocommerce' ),
147	'type' => 'string',
148	'format' => 'date-time',
149	'validate_callback' => 'rest_validate_request_arg',
150	);
151
152	$params['before'] = array(
153	'description' => __( 'Limit response to resources created before a given ISO8601 compliant date.', 'woocommerce' ),
154	'type' => 'string',
155	'format' => 'date-time',
156	'validate_callback' => 'rest_validate_request_arg',
157	);
158
159	$params['date_column'] = array(
160	'description' => __( 'When limiting response using after/before, which date column to compare against.', 'woocommerce' ),
161	'type' => 'string',
162	'default' => 'date',
163	'enum' => array(
164	'date',
165	'date_gmt',
166	'modified',
167	'modified_gmt',
168	),
169	'validate_callback' => 'rest_validate_request_arg',
170	);
171
172	$params['exclude'] = array(
173	'description' => __( 'Ensure result set excludes specific IDs.', 'woocommerce' ),
174	'type' => 'array',
175	'items' => array(
176	'type' => 'integer',
177	),
178	'default' => [],
179	'sanitize_callback' => 'wp_parse_id_list',
180	);
181
182	$params['include'] = array(
183	'description' => __( 'Limit result set to specific ids.', 'woocommerce' ),
184	'type' => 'array',
185	'items' => array(
186	'type' => 'integer',
187	),
188	'default' => [],
189	'sanitize_callback' => 'wp_parse_id_list',
190	);
191
192	$params['offset'] = array(
193	'description' => __( 'Offset the result set by a specific number of items.', 'woocommerce' ),
194	'type' => 'integer',
195	'sanitize_callback' => 'absint',
196	'validate_callback' => 'rest_validate_request_arg',
197	);
198
199	$params['order'] = array(
200	'description' => __( 'Order sort attribute ascending or descending.', 'woocommerce' ),
201	'type' => 'string',
202	'default' => 'desc',
203	'enum' => array( 'asc', 'desc' ),
204	'validate_callback' => 'rest_validate_request_arg',
205	);
206
207	$params['orderby'] = array(
208	'description' => __( 'Sort collection by object attribute.', 'woocommerce' ),
209	'type' => 'string',
210	'default' => 'date',
211	'enum' => array(
212	'date',
213	'modified',
214	'id',
215	'include',
216	'title',
217	'slug',
218	'price',
219	'popularity',
220	'rating',
221	'menu_order',
222	'comment_count',
223	),
224	'validate_callback' => 'rest_validate_request_arg',
225	);
226
227	$params['parent'] = array(
228	'description' => __( 'Limit result set to those of particular parent IDs.', 'woocommerce' ),
229	'type' => 'array',
230	'items' => array(
231	'type' => 'integer',
232	),
233	'default' => [],
234	'sanitize_callback' => 'wp_parse_id_list',
235	);
236
237	$params['parent_exclude'] = array(
238	'description' => __( 'Limit result set to all items except those of a particular parent ID.', 'woocommerce' ),
239	'type' => 'array',
240	'items' => array(
241	'type' => 'integer',
242	),
243	'sanitize_callback' => 'wp_parse_id_list',
244	'default' => [],
245	);
246
247	$params['type'] = array(
248	'description' => __( 'Limit result set to products assigned a specific type.', 'woocommerce' ),
249	'type' => 'string',
250	'enum' => array_merge( array_keys( wc_get_product_types() ), [ ProductType::VARIATION ] ),
251	'sanitize_callback' => 'sanitize_key',
252	'validate_callback' => 'rest_validate_request_arg',
253	);
254
255	$params['sku'] = array(
256	'description' => __( 'Limit result set to products with specific SKU(s). Use commas to separate.', 'woocommerce' ),
257	'type' => 'string',
258	'sanitize_callback' => 'sanitize_text_field',
259	'validate_callback' => 'rest_validate_request_arg',
260	);
261
262	$params['featured'] = array(
263	'description' => __( 'Limit result set to featured products.', 'woocommerce' ),
264	'type' => 'boolean',
265	'sanitize_callback' => 'wc_string_to_bool',
266	'validate_callback' => 'rest_validate_request_arg',
267	);
268
269	$params['category'] = array(
270	'description' => __( 'Limit result set to products assigned a set of category IDs or slugs, separated by commas.', 'woocommerce' ),
271	'type' => 'string',
272	'sanitize_callback' => 'wp_parse_list',
273	'validate_callback' => 'rest_validate_request_arg',
274	);
275
276	$params['category_operator'] = array(
277	'description' => __( 'Operator to compare product category terms.', 'woocommerce' ),
278	'type' => 'string',
279	'enum' => [ 'in', 'not_in', 'and' ],
280	'default' => 'in',
281	'sanitize_callback' => 'sanitize_key',
282	'validate_callback' => 'rest_validate_request_arg',
283	);
284
285	$params['brand'] = array(
286	'description' => __( 'Limit result set to products assigned a set of brand IDs or slugs, separated by commas.', 'woocommerce' ),
287	'type' => 'string',
288	'sanitize_callback' => 'wp_parse_list',
289	'validate_callback' => 'rest_validate_request_arg',
290	);
291
292	$params['brand_operator'] = array(
293	'description' => __( 'Operator to compare product brand terms.', 'woocommerce' ),
294	'type' => 'string',
295	'enum' => [ 'in', 'not_in', 'and' ],
296	'default' => 'in',
297	'sanitize_callback' => 'sanitize_key',
298	'validate_callback' => 'rest_validate_request_arg',
299	);
300
301	// If the $_REQUEST contains a taxonomy query, add it to the params and sanitize it.
302	foreach ( $_REQUEST as $param => $value ) { // phpcs:ignore WordPress.Security.NonceVerification.Recommended
303	if ( ! is_string( $param ) ) {
304	continue;
305	}
306
307	if ( str_starts_with( $param, '_unstable_tax_' ) && ! str_ends_with( $param, '_operator' ) ) {
308	$params[ $param ] = array(
309	'description' => __( 'Limit result set to products assigned a set of taxonomies IDs or slugs, separated by commas.', 'woocommerce' ),
310	'type' => 'string',
311	'sanitize_callback' => 'wp_parse_list',
312	'validate_callback' => 'rest_validate_request_arg',
313	);
314	}
315	if ( str_starts_with( $param, '_unstable_tax_' ) && str_ends_with( $param, '_operator' ) ) {
316	$params[ $param ] = array(
317	'description' => __( 'Operator to compare product taxonomies terms.', 'woocommerce' ),
318	'type' => 'string',
319	'enum' => [ 'in', 'not_in', 'and' ],
320	'default' => 'in',
321	'sanitize_callback' => 'sanitize_key',
322	'validate_callback' => 'rest_validate_request_arg',
323	);
324	}
325	}
326
327	$params['tag'] = array(
328	'description' => __( 'Limit result set to products assigned a set of tag IDs or slugs, separated by commas.', 'woocommerce' ),
329	'type' => 'string',
330	'sanitize_callback' => 'wp_parse_list',
331	'validate_callback' => 'rest_validate_request_arg',
332	);
333
334	$params['tag_operator'] = array(
335	'description' => __( 'Operator to compare product tags.', 'woocommerce' ),
336	'type' => 'string',
337	'enum' => [ 'in', 'not_in', 'and' ],
338	'default' => 'in',
339	'sanitize_callback' => 'sanitize_key',
340	'validate_callback' => 'rest_validate_request_arg',
341	);
342
343	$params['on_sale'] = array(
344	'description' => __( 'Limit result set to products on sale.', 'woocommerce' ),
345	'type' => 'boolean',
346	'sanitize_callback' => 'wc_string_to_bool',
347	'validate_callback' => 'rest_validate_request_arg',
348	);
349
350	$params['min_price'] = array(
351	'description' => __( 'Limit result set to products based on a minimum price, provided using the smallest unit of the currency.', 'woocommerce' ),
352	'type' => 'string',
353	'sanitize_callback' => 'sanitize_text_field',
354	'validate_callback' => 'rest_validate_request_arg',
355	);
356
357	$params['max_price'] = array(
358	'description' => __( 'Limit result set to products based on a maximum price, provided using the smallest unit of the currency.', 'woocommerce' ),
359	'type' => 'string',
360	'sanitize_callback' => 'sanitize_text_field',
361	'validate_callback' => 'rest_validate_request_arg',
362	);
363
364	$params['stock_status'] = array(
365	'description' => __( 'Limit result set to products with specified stock status.', 'woocommerce' ),
366	'type' => 'array',
367	'items' => array(
368	'type' => 'string',
369	'enum' => array_keys( wc_get_product_stock_status_options() ),
370	'sanitize_callback' => 'sanitize_text_field',
371	'validate_callback' => 'rest_validate_request_arg',
372	),
373	'default' => [],
374	);
375
376	$params['attributes'] = array(
377	'description' => __( 'Limit result set to products with selected global attributes.', 'woocommerce' ),
378	'type' => 'array',
379	'items' => array(
380	'type' => 'object',
381	'properties' => array(
382	'attribute' => array(
383	'description' => __( 'Attribute taxonomy name.', 'woocommerce' ),
384	'type' => 'string',
385	'sanitize_callback' => 'wc_sanitize_taxonomy_name',
386	),
387	'term_id' => array(
388	'description' => __( 'List of attribute term IDs.', 'woocommerce' ),
389	'type' => 'array',
390	'items' => [
391	'type' => 'integer',
392	],
393	'sanitize_callback' => 'wp_parse_id_list',
394	),
395	'slug' => array(
396	'description' => __( 'List of attribute slug(s). If a term ID is provided, this will be ignored.', 'woocommerce' ),
397	'type' => 'array',
398	'items' => [
399	'type' => 'string',
400	],
401	'sanitize_callback' => 'wp_parse_slug_list',
402	),
403	'operator' => array(
404	'description' => __( 'Operator to compare product attribute terms.', 'woocommerce' ),
405	'type' => 'string',
406	'enum' => [ 'in', 'not_in', 'and' ],
407	),
408	),
409	),
410	'default' => [],
411	);
412
413	$params['attribute_relation'] = array(
414	'description' => __( 'The logical relationship between attributes when filtering across multiple at once.', 'woocommerce' ),
415	'type' => 'string',
416	'enum' => [ 'in', 'and' ],
417	'default' => 'and',
418	'sanitize_callback' => 'sanitize_key',
419	'validate_callback' => 'rest_validate_request_arg',
420	);
421
422	$params['catalog_visibility'] = array(
423	'description' => __( 'Determines if hidden or visible catalog products are shown.', 'woocommerce' ),
424	'type' => 'string',
425	'enum' => array( 'any', CatalogVisibility::VISIBLE, CatalogVisibility::CATALOG, CatalogVisibility::SEARCH, CatalogVisibility::HIDDEN ),
426	'sanitize_callback' => 'sanitize_key',
427	'validate_callback' => 'rest_validate_request_arg',
428	);
429
430	$params['rating'] = array(
431	'description' => __( 'Limit result set to products with a certain average rating.', 'woocommerce' ),
432	'type' => 'array',
433	'items' => array(
434	'type' => 'integer',
435	'enum' => range( 1, 5 ),
436	),
437	'default' => [],
438	'sanitize_callback' => 'wp_parse_id_list',
439	);
440
441	$params['related'] = array(
442	'description' => __( 'Limit result set to products related to a specific product ID.', 'woocommerce' ),
443	'type' => 'integer',
444	'sanitize_callback' => 'absint',
445	'validate_callback' => 'rest_validate_request_arg',
446	);
447
448	return $params;
449	}
450	}
451