AbstractSchema.php — WooCommerce 10.9.4

woocommerce / src / StoreApi / Schemas / V1 / AbstractSchema.php

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

AbstractSchema.php

416 lines

1	<?php
2	namespace Automattic\WooCommerce\StoreApi\Schemas\V1;
3
4	use Automattic\WooCommerce\StoreApi\SchemaController;
5	use Automattic\WooCommerce\StoreApi\Schemas\ExtendSchema;
6	use Automattic\WooCommerce\Blocks\Domain\Services\CheckoutFields;
7	use Automattic\WooCommerce\Blocks\Package;
8
9	/**
10	* AbstractSchema class.
11	*
12	* For REST Route Schemas
13	*/
14	abstract class AbstractSchema {
15	/**
16	* The schema item name.
17	*
18	* @var string
19	*/
20	protected $title = 'Schema';
21
22	/**
23	* Rest extend instance.
24	*
25	* @var ExtendSchema
26	*/
27	protected $extend;
28
29	/**
30	* Schema Controller instance.
31	*
32	* @var SchemaController
33	*/
34	protected $controller;
35
36	/**
37	* Extending key that gets added to endpoint.
38	*
39	* @var string
40	*/
41	const EXTENDING_KEY = 'extensions';
42
43	/**
44	* Constructor.
45	*
46	* @param ExtendSchema $extend Rest Extending instance.
47	* @param SchemaController $controller Schema Controller instance.
48	*/
49	public function __construct( ExtendSchema $extend, SchemaController $controller ) {
50	$this->extend = $extend;
51	$this->controller = $controller;
52	}
53
54	/**
55	* Returns the full item schema.
56	*
57	* @return array
58	*/
59	public function get_item_schema() {
60	return array(
61	'$schema' => 'http://json-schema.org/draft-04/schema#',
62	'title' => $this->title,
63	'type' => 'object',
64	'properties' => $this->get_properties(),
65	);
66	}
67
68	/**
69	* Returns the full item response.
70	*
71	* @param mixed $item Item to get response for.
72	* @return array\|stdClass
73	*/
74	public function get_item_response( $item ) {
75	return [];
76	}
77
78	/**
79	* Return schema properties.
80	*
81	* @return array
82	*/
83	abstract public function get_properties();
84
85	/**
86	* Recursive removal of arg_options.
87	*
88	* @param array $properties Schema properties.
89	*/
90	protected function remove_arg_options( $properties ) {
91	return array_map(
92	function( $property ) {
93	if ( ! is_array( $property ) ) {
94	return $property;
95	}
96	if ( isset( $property['properties'] ) ) {
97	$property['properties'] = $this->remove_arg_options( $property['properties'] );
98	} elseif ( isset( $property['items']['properties'] ) ) {
99	$property['items']['properties'] = $this->remove_arg_options( $property['items']['properties'] );
100	}
101	unset( $property['arg_options'] );
102	return $property;
103	},
104	(array) $properties
105	);
106	}
107
108	/**
109	* Returns the public schema.
110	*
111	* @return array
112	*/
113	public function get_public_item_schema() {
114	$schema = $this->get_item_schema();
115
116	if ( isset( $schema['properties'] ) ) {
117	$schema['properties'] = $this->remove_arg_options( $schema['properties'] );
118	}
119
120	return $schema;
121	}
122
123	/**
124	* Returns extended data for a specific endpoint.
125	*
126	* @param string $endpoint The endpoint identifier.
127	* @param array ...$passed_args An array of arguments to be passed to callbacks.
128	* @return object the data that will get added.
129	*/
130	protected function get_extended_data( $endpoint, ...$passed_args ) {
131	return $this->extend->get_endpoint_data( $endpoint, $passed_args );
132	}
133
134	/**
135	* Gets an array of schema defaults recursively.
136	*
137	* @param array $properties Schema property data.
138	* @return array Array of defaults, pulled from arg_options
139	*/
140	protected function get_recursive_schema_property_defaults( $properties ) {
141	$defaults = [];
142
143	foreach ( $properties as $property_key => $property_value ) {
144	if ( isset( $property_value['arg_options']['default'] ) ) {
145	$defaults[ $property_key ] = $property_value['arg_options']['default'];
146	} elseif ( isset( $property_value['properties'] ) ) {
147	$defaults[ $property_key ] = $this->get_recursive_schema_property_defaults( $property_value['properties'] );
148	}
149	}
150
151	return $defaults;
152	}
153
154	/**
155	* Gets a function that validates recursively.
156	*
157	* @param array $properties Schema property data.
158	* @return function Anonymous validation callback.
159	*/
160	protected function get_recursive_validate_callback( $properties ) {
161	/**
162	* Validate a request argument based on details registered to the route.
163	*
164	* @param mixed $values
165	* @param \WP_REST_Request $request
166	* @param string $param
167	* @return true\|\WP_Error
168	*/
169	return function ( $values, $request, $param ) use ( $properties ) {
170	foreach ( $properties as $property_key => $property_value ) {
171	$current_value = isset( $values[ $property_key ] ) ? $values[ $property_key ] : null;
172
173	$property_type = is_array( $property_value['type'] ) ? $property_value['type'] : [ $property_value['type'] ];
174	if ( empty( $current_value ) && in_array( 'null', $property_type, true ) ) {
175	// If the value is null and the schema allows null, we can skip validation for children.
176	continue;
177	}
178
179	if ( isset( $property_value['arg_options']['validate_callback'] ) ) {
180	$callback = $property_value['arg_options']['validate_callback'];
181	$result = is_callable( $callback ) ? $callback( $current_value, $request, $param ) : false;
182	} else {
183	$result = rest_validate_value_from_schema( $current_value, $property_value, $param . ' > ' . $property_key );
184	}
185
186	if ( ! $result \|\| is_wp_error( $result ) ) {
187	// If schema validation fails, we return here as we don't need to validate any deeper.
188	return $result;
189	}
190
191	if ( isset( $property_value['properties'] ) ) {
192	$validate_callback = $this->get_recursive_validate_callback( $property_value['properties'] );
193	$result = $validate_callback( $current_value, $request, $param . ' > ' . $property_key );
194
195	if ( ! $result \|\| is_wp_error( $result ) ) {
196	// If schema validation fails, we return here as we don't need to validate any deeper.
197	return $result;
198	}
199	}
200	}
201
202	return true;
203	};
204	}
205
206	/**
207	* Gets a function that sanitizes recursively.
208	*
209	* @param array $properties Schema property data.
210	* @return function Anonymous validation callback.
211	*/
212	protected function get_recursive_sanitize_callback( $properties ) {
213	/**
214	* Validate a request argument based on details registered to the route.
215	*
216	* @param mixed $values
217	* @param \WP_REST_Request $request
218	* @param string $param
219	* @return true\|\WP_Error
220	*/
221	return function ( $values, $request, $param ) use ( $properties ) {
222	$sanitized_values = [];
223
224	foreach ( $properties as $property_key => $property_value ) {
225	$current_value = isset( $values[ $property_key ] ) ? $values[ $property_key ] : null;
226
227	if ( isset( $property_value['arg_options']['sanitize_callback'] ) ) {
228	$callback = $property_value['arg_options']['sanitize_callback'];
229	$current_value = is_callable( $callback ) ? $callback( $current_value, $request, $param ) : $current_value;
230	} else {
231	$current_value = rest_sanitize_value_from_schema( $current_value, $property_value, $param . ' > ' . $property_key );
232	}
233
234	// If sanitization failed, return the WP_Error object straight away.
235	if ( is_wp_error( $current_value ) ) {
236	return $current_value;
237	}
238
239	if ( isset( $property_value['properties'] ) ) {
240	$sanitize_callback = $this->get_recursive_sanitize_callback( $property_value['properties'] );
241	$sanitized_values[ $property_key ] = $sanitize_callback( $current_value, $request, $param . ' > ' . $property_key );
242	} else {
243	$sanitized_values[ $property_key ] = $current_value;
244	}
245	}
246
247	return $sanitized_values;
248	};
249	}
250
251	/**
252	* Returns extended schema for a specific endpoint.
253	*
254	* @param string $endpoint The endpoint identifier.
255	* @param array ...$passed_args An array of arguments to be passed to callbacks.
256	* @return array the data that will get added.
257	*/
258	protected function get_extended_schema( $endpoint, ...$passed_args ) {
259	$extended_schema = $this->extend->get_endpoint_schema( $endpoint, $passed_args );
260	$defaults = $this->get_recursive_schema_property_defaults( $extended_schema );
261
262	return [
263	'type' => 'object',
264	'context' => [ 'view', 'edit', 'embed' ],
265	'arg_options' => [
266	'default' => $defaults,
267	'validate_callback' => $this->get_recursive_validate_callback( $extended_schema ),
268	'sanitize_callback' => $this->get_recursive_sanitize_callback( $extended_schema ),
269	],
270	'properties' => $extended_schema,
271	];
272	}
273
274	/**
275	* Apply a schema get_item_response callback to an array of items and return the result.
276	*
277	* @param AbstractSchema $schema Schema class instance.
278	* @param array $items Array of items.
279	* @return array Array of values from the callback function.
280	*/
281	protected function get_item_responses_from_schema( AbstractSchema $schema, $items ) {
282	$items = array_filter( $items );
283
284	if ( empty( $items ) ) {
285	return [];
286	}
287
288	return array_values( array_map( [ $schema, 'get_item_response' ], $items ) );
289	}
290
291	/**
292	* Retrieves an array of endpoint arguments from the item schema for the controller.
293	*
294	* @uses rest_get_endpoint_args_for_schema()
295	* @param string $method Optional. HTTP method of the request.
296	* @return array Endpoint arguments.
297	*/
298	public function get_endpoint_args_for_item_schema( $method = \WP_REST_Server::CREATABLE ) {
299	$schema = $this->get_item_schema();
300	$endpoint_args = rest_get_endpoint_args_for_schema( $schema, $method );
301	$endpoint_args = $this->remove_arg_options( $endpoint_args );
302	return $endpoint_args;
303	}
304
305
306	/**
307	* Force all schema properties to be readonly.
308	*
309	* @param array $properties Schema.
310	* @return array Updated schema.
311	*/
312	protected function force_schema_readonly( $properties ) {
313	return array_map(
314	function( $property ) {
315	$property['readonly'] = true;
316	if ( isset( $property['items']['properties'] ) ) {
317	$property['items']['properties'] = $this->force_schema_readonly( $property['items']['properties'] );
318	}
319	return $property;
320	},
321	(array) $properties
322	);
323	}
324
325	/**
326	* Returns consistent currency schema used across endpoints for prices.
327	*
328	* @return array
329	*/
330	protected function get_store_currency_properties() {
331	return [
332	'currency_code' => [
333	'description' => __( 'Currency code (in ISO format) for returned prices.', 'woocommerce' ),
334	'type' => 'string',
335	'context' => [ 'view', 'edit', 'embed' ],
336	'readonly' => true,
337	],
338	'currency_symbol' => [
339	'description' => __( 'Currency symbol for the currency which can be used to format returned prices.', 'woocommerce' ),
340	'type' => 'string',
341	'context' => [ 'view', 'edit', 'embed' ],
342	'readonly' => true,
343	],
344	'currency_minor_unit' => [
345	'description' => __( 'Currency minor unit (number of digits after the decimal separator) for returned prices.', 'woocommerce' ),
346	'type' => 'integer',
347	'context' => [ 'view', 'edit', 'embed' ],
348	'readonly' => true,
349	],
350	'currency_decimal_separator' => array(
351	'description' => __( 'Decimal separator for the currency which can be used to format returned prices.', 'woocommerce' ),
352	'type' => 'string',
353	'context' => array( 'view', 'edit', 'embed' ),
354	'readonly' => true,
355	),
356	'currency_thousand_separator' => array(
357	'description' => __( 'Thousand separator for the currency which can be used to format returned prices.', 'woocommerce' ),
358	'type' => 'string',
359	'context' => array( 'view', 'edit', 'embed' ),
360	'readonly' => true,
361	),
362	'currency_prefix' => array(
363	'description' => __( 'Price prefix for the currency which can be used to format returned prices.', 'woocommerce' ),
364	'type' => 'string',
365	'context' => array( 'view', 'edit', 'embed' ),
366	'readonly' => true,
367	),
368	'currency_suffix' => array(
369	'description' => __( 'Price prefix for the currency which can be used to format returned prices.', 'woocommerce' ),
370	'type' => 'string',
371	'context' => array( 'view', 'edit', 'embed' ),
372	'readonly' => true,
373	),
374	];
375	}
376
377	/**
378	* Adds currency data to an array of monetary values.
379	*
380	* @param array $values Monetary amounts.
381	* @return array Monetary amounts with currency data appended.
382	*/
383	protected function prepare_currency_response( $values ) {
384	return $this->extend->get_formatter( 'currency' )->format( $values );
385	}
386
387	/**
388	* Convert monetary values from WooCommerce to string based integers, using
389	* the smallest unit of a currency.
390	*
391	* @param string\|float $amount Monetary amount with decimals.
392	* @param int $decimals Number of decimals the amount is formatted with.
393	* @param int $rounding_mode Defaults to the PHP_ROUND_HALF_UP constant.
394	* @return string The new amount.
395	*/
396	protected function prepare_money_response( $amount, $decimals = 2, $rounding_mode = PHP_ROUND_HALF_UP ) {
397	return $this->extend->get_formatter( 'money' )->format(
398	$amount,
399	[
400	'decimals' => $decimals,
401	'rounding_mode' => $rounding_mode,
402	]
403	);
404	}
405
406	/**
407	* Prepares HTML based content, such as post titles and content, for the API response.
408	*
409	* @param string\|array $response Data to format.
410	* @return string\|array Formatted data.
411	*/
412	protected function prepare_html_response( $response ) {
413	return $this->extend->get_formatter( 'html' )->format( $response );
414	}
415	}
416