jetpack / class.json-api-endpoints.php

class.json-api-endpoints.php in Jetpack – WP Security, Backup, Speed, & Growth 16.0, at class.json-api-endpoints.php

2,918 lines 91.6 KB

Raw Download Zip

1	<?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName
2	/**
3	* Jetpack API endpoint base class.
4	*
5	* @package automattic/jetpack
6	*/
7
8	use Automattic\Jetpack\Connection\Client;
9	use Automattic\Jetpack\Connection\Manager;
10	use Automattic\Jetpack\Connection\Rest_Authentication;
11	use Automattic\Jetpack\Connection\Tokens;
12	use Automattic\Jetpack\Status;
13	use Automattic\Jetpack\Status\Host;
14
15	require_once __DIR__ . '/json-api-config.php';
16	require_once __DIR__ . '/sal/class.json-api-links.php';
17	require_once __DIR__ . '/sal/class.json-api-metadata.php';
18	require_once __DIR__ . '/sal/class.json-api-date.php';
19
20	/**
21	* Endpoint.
22	*/
23	abstract class WPCOM_JSON_API_Endpoint {
24	/**
25	* The API Object
26	*
27	* @var WPCOM_JSON_API
28	*/
29	public $api;
30
31	/**
32	* The link-generating utility class
33	*
34	* @var WPCOM_JSON_API_Links
35	*/
36	public $links;
37
38	/**
39	* Whether to pass wpcom user details.
40	*
41	* @var bool
42	*/
43	public $pass_wpcom_user_details = false;
44
45	/**
46	* One liner.
47	*
48	* @var string
49	*/
50	public $description;
51
52	/**
53	* Object Grouping For Documentation (Users, Posts, Comments)
54	*
55	* @var string
56	*/
57	public $group;
58
59	/**
60	* Stats extra value to bump
61	*
62	* @var mixed
63	*/
64	public $stat;
65
66	/**
67	* HTTP Method
68	*
69	* @var string
70	*/
71	public $method = 'GET';
72
73	/**
74	* Minimum version of the api for which to serve this endpoint
75	*
76	* @var string
77	*/
78	public $min_version = '0';
79
80	/**
81	* Maximum version of the api for which to serve this endpoint
82	*
83	* @var string
84	*/
85	public $max_version = WPCOM_JSON_API__CURRENT_VERSION;
86
87	/**
88	* Forced endpoint environment when running on WPCOM
89	*
90	* @var string '', 'wpcom', 'secure', or 'jetpack'
91	*/
92	public $force = '';
93
94	/**
95	* Whether the endpoint is deprecated
96	*
97	* @var bool
98	*/
99	public $deprecated = false;
100
101	/**
102	* Version of the endpoint this endpoint is deprecated in favor of.
103	*
104	* @var string
105	*/
106	protected $new_version = WPCOM_JSON_API__CURRENT_VERSION;
107
108	/**
109	* Whether the endpoint is only available on WordPress.com hosted blogs
110	*
111	* @var bool
112	*/
113	public $jp_disabled = false;
114
115	/**
116	* Path at which to serve this endpoint: sprintf() format.
117	*
118	* @var string
119	*/
120	public $path = '';
121
122	/**
123	* Identifiers to fill sprintf() formatted $path
124	*
125	* @var array
126	*/
127	public $path_labels = array();
128
129	/**
130	* The REST endpoint if available.
131	*
132	* @var string
133	*/
134	public $rest_route;
135
136	/**
137	* Jetpack Version in which REST support was introduced.
138	*
139	* @var string
140	*/
141	public $rest_min_jp_version;
142
143	/**
144	* Accepted query parameters
145	*
146	* @var array
147	*/
148	public $query = array(
149	// Parameter name.
150	'context' => array(
151	// Default value => description.
152	'display' => 'Formats the output as HTML for display. Shortcodes are parsed, paragraph tags are added, etc..',
153	// Other possible values => description.
154	'edit' => 'Formats the output for editing. Shortcodes are left unparsed, significant whitespace is kept, etc..',
155	),
156	'http_envelope' => array(
157	'false' => '',
158	'true' => 'Some environments (like in-browser JavaScript or Flash) block or divert responses with a non-200 HTTP status code. Setting this parameter will force the HTTP status code to always be 200. The JSON response is wrapped in an "envelope" containing the "real" HTTP status code and headers.',
159	),
160	'pretty' => array(
161	'false' => '',
162	'true' => 'Output pretty JSON',
163	),
164	'meta' => "(string) Optional. Loads data from the endpoints found in the 'meta' part of the response. Comma-separated list. Example: meta=site,likes",
165	'fields' => '(string) Optional. Returns specified fields only. Comma-separated list. Example: fields=ID,title',
166	// Parameter name => description (default value is empty).
167	'callback' => '(string) An optional JSONP callback function.',
168	);
169
170	/**
171	* Response format
172	*
173	* @var array
174	*/
175	public $response_format = array();
176
177	/**
178	* Request format
179	*
180	* @var array
181	*/
182	public $request_format = array();
183
184	/**
185	* Is this endpoint still in testing phase? If so, not available to the public.
186	*
187	* @var bool
188	*/
189	public $in_testing = false;
190
191	/**
192	* Is this endpoint still allowed if the site in question is flagged?
193	*
194	* @var bool
195	*/
196	public $allowed_if_flagged = false;
197
198	/**
199	* Is this endpoint allowed if the site is red flagged?
200	*
201	* @var bool
202	*/
203	public $allowed_if_red_flagged = false;
204
205	/**
206	* Is this endpoint allowed if the site is deleted?
207	*
208	* @var bool
209	*/
210	public $allowed_if_deleted = false;
211
212	/**
213	* Version of the API
214	*
215	* @var string
216	*/
217	public $version = '';
218
219	/**
220	* Example request to make
221	*
222	* @var string
223	*/
224	public $example_request = '';
225
226	/**
227	* Example request data (for POST methods)
228	*
229	* @var string
230	*/
231	public $example_request_data = '';
232
233	/**
234	* Example response from $example_request
235	*
236	* @var string
237	*/
238	public $example_response = '';
239
240	/**
241	* OAuth2 scope required when running on WPCOM
242	*
243	* @var string
244	*/
245	public $required_scope = '';
246
247	/**
248	* Set to true if the endpoint implements its own filtering instead of the standard `fields` query method
249	*
250	* @var bool
251	*/
252	public $custom_fields_filtering = false;
253
254	/**
255	* Set to true if the endpoint accepts all cross origin requests. You probably should not set this flag.
256	*
257	* @var bool
258	*/
259	public $allow_cross_origin_request = false;
260
261	/**
262	* Set to true if the endpoint can recieve unauthorized POST requests.
263	*
264	* @var bool
265	*/
266	public $allow_unauthorized_request = false;
267
268	/**
269	* Set to true if the endpoint should accept site based (not user based) authentication.
270	*
271	* @var bool
272	*/
273	public $allow_jetpack_site_auth = false;
274
275	/**
276	* Set to true if the endpoint should accept user based authentication.
277	*
278	* @var bool
279	*/
280	public $allow_jetpack_token_auth = false;
281
282	/**
283	* Set to true if the endpoint should accept auth from an upload token.
284	*
285	* @var bool
286	*/
287	public $allow_upload_token_auth = false;
288
289	/**
290	* Set to true if the endpoint should require auth from a Rewind auth token.
291	*
292	* @var bool
293	*/
294	public $require_rewind_auth = false;
295
296	/**
297	* Whether this endpoint allows falling back to a blog token for making requests to remote Jetpack sites.
298	*
299	* @var bool
300	*/
301	public $allow_fallback_to_jetpack_blog_token = false;
302
303	/**
304	* REST namespace.
305	*/
306	const REST_NAMESPACE = 'jetpack/rest';
307
308	/**
309	* Post object format.
310	*
311	* @var array
312	*/
313	public $post_object_format;
314
315	/**
316	* Comment object format.
317	*
318	* @var array
319	*/
320	public $comment_object_format;
321
322	/**
323	* Dropdown page object format.
324	*
325	* @var array
326	*/
327	public $dropdown_page_object_format;
328
329	/**
330	* Constructor.
331	*
332	* @param string\|array\|object $args Args.
333	*/
334	public function __construct( $args ) {
335	$defaults = array(
336	'in_testing' => false,
337	'allowed_if_flagged' => false,
338	'allowed_if_red_flagged' => false,
339	'allowed_if_deleted' => false,
340	'description' => '',
341	'group' => '',
342	'stat' => '',
343	'method' => 'GET',
344	'path' => '/',
345	'min_version' => '0',
346	'max_version' => WPCOM_JSON_API__CURRENT_VERSION,
347	'force' => '',
348	'deprecated' => false,
349	'new_version' => WPCOM_JSON_API__CURRENT_VERSION,
350	'jp_disabled' => false,
351	'path_labels' => array(),
352	'rest_route' => null,
353	'rest_min_jp_version' => null,
354	'request_format' => array(),
355	'response_format' => array(),
356	'query_parameters' => array(),
357	'version' => 'v1',
358	'example_request' => '',
359	'example_request_data' => '',
360	'example_response' => '',
361	'required_scope' => '',
362	'pass_wpcom_user_details' => false,
363	'custom_fields_filtering' => false,
364	'allow_cross_origin_request' => false,
365	'allow_unauthorized_request' => false,
366	'allow_jetpack_site_auth' => false,
367	'allow_jetpack_token_auth' => false,
368	'allow_upload_token_auth' => false,
369	'allow_fallback_to_jetpack_blog_token' => false,
370	);
371
372	$args = wp_parse_args( $args, $defaults );
373
374	$this->in_testing = $args['in_testing'];
375
376	$this->allowed_if_flagged = $args['allowed_if_flagged'];
377	$this->allowed_if_red_flagged = $args['allowed_if_red_flagged'];
378	$this->allowed_if_deleted = $args['allowed_if_deleted'];
379
380	$this->description = $args['description'];
381	$this->group = $args['group'];
382	$this->stat = $args['stat'];
383	$this->force = $args['force'];
384	$this->jp_disabled = $args['jp_disabled'];
385
386	$this->method = $args['method'];
387	$this->path = $args['path'];
388	$this->path_labels = $args['path_labels'];
389	$this->min_version = $args['min_version'];
390	$this->max_version = $args['max_version'];
391	$this->deprecated = $args['deprecated'];
392	$this->new_version = $args['new_version'];
393
394	$this->rest_route = $args['rest_route'];
395	$this->rest_min_jp_version = $args['rest_min_jp_version'];
396
397	// Ensure max version is not less than min version.
398	if ( version_compare( $this->min_version, $this->max_version, '>' ) ) {
399	$this->max_version = $this->min_version;
400	}
401
402	$this->pass_wpcom_user_details = $args['pass_wpcom_user_details'];
403	$this->custom_fields_filtering = (bool) $args['custom_fields_filtering'];
404
405	$this->allow_cross_origin_request = (bool) $args['allow_cross_origin_request'];
406	$this->allow_unauthorized_request = (bool) $args['allow_unauthorized_request'];
407	$this->allow_jetpack_site_auth = (bool) $args['allow_jetpack_site_auth'];
408	$this->allow_jetpack_token_auth = (bool) $args['allow_jetpack_token_auth'];
409	$this->allow_upload_token_auth = (bool) $args['allow_upload_token_auth'];
410	$this->allow_fallback_to_jetpack_blog_token = (bool) $args['allow_fallback_to_jetpack_blog_token'];
411	$this->require_rewind_auth = isset( $args['require_rewind_auth'] ) ? (bool) $args['require_rewind_auth'] : false;
412
413	$this->version = $args['version'];
414
415	$this->required_scope = $args['required_scope'];
416
417	if ( $this->request_format ) {
418	$this->request_format = array_filter( array_merge( $this->request_format, $args['request_format'] ) );
419	} else {
420	$this->request_format = $args['request_format'];
421	}
422
423	if ( $this->response_format ) {
424	$this->response_format = array_filter( array_merge( $this->response_format, $args['response_format'] ) );
425	} else {
426	$this->response_format = $args['response_format'];
427	}
428
429	if ( false === $args['query_parameters'] ) {
430	$this->query = array();
431	} elseif ( is_array( $args['query_parameters'] ) ) {
432	$this->query = array_filter( array_merge( $this->query, $args['query_parameters'] ) );
433	}
434
435	$this->api = WPCOM_JSON_API::init(); // Auto-add to WPCOM_JSON_API.
436	$this->links = WPCOM_JSON_API_Links::getInstance();
437
438	/** Example Request/Response */
439
440	// Examples for endpoint documentation request.
441	$this->example_request = $args['example_request'];
442	$this->example_request_data = $args['example_request_data'];
443	$this->example_response = $args['example_response'];
444
445	$this->api->add( $this );
446
447	if ( ( ! defined( 'IS_WPCOM' ) \|\| ! IS_WPCOM ) && $this->rest_route && ( ! defined( 'XMLRPC_REQUEST' ) \|\| ! XMLRPC_REQUEST ) ) {
448	$this->create_rest_route_for_endpoint();
449	}
450	}
451
452	/**
453	* Get all query args. Prefill with defaults.
454	*
455	* @param bool $return_default_values Whether to include default values in the response.
456	* @param bool $cast_and_filter Whether to cast and filter input according to the documentation.
457	* @return array
458	*/
459	public function query_args( $return_default_values = true, $cast_and_filter = true ) {
460	$args = array_intersect_key( $this->api->query, $this->query );
461
462	if ( ! $cast_and_filter ) {
463	return $args;
464	}
465
466	return $this->cast_and_filter( $args, $this->query, $return_default_values );
467	}
468
469	/**
470	* Get POST body data.
471	*
472	* @param bool $return_default_values Whether to include default values in the response.
473	* @param bool $cast_and_filter Whether to cast and filter input according to the documentation.
474	* @return mixed
475	*/
476	public function input( $return_default_values = true, $cast_and_filter = true ) {
477	$return = null;
478	$input = trim( (string) $this->api->post_body );
479	$content_type = (string) $this->api->content_type;
480	if ( $content_type ) {
481	list ( $content_type ) = explode( ';', $content_type );
482	}
483	$content_type = trim( $content_type );
484	switch ( $content_type ) {
485	case 'application/json':
486	case 'application/x-javascript':
487	case 'text/javascript':
488	case 'text/x-javascript':
489	case 'text/x-json':
490	case 'text/json':
491	$return = json_decode( $input, true );
492
493	if ( JSON_ERROR_NONE !== json_last_error() ) {
494	return null;
495	}
496
497	break;
498	case 'multipart/form-data':
499	// phpcs:ignore WordPress.Security.NonceVerification.Missing
500	$return = array_merge( stripslashes_deep( $_POST ), $_FILES );
501	break;
502	case 'application/x-www-form-urlencoded':
503	// attempt JSON first, since probably a curl command.
504	$return = json_decode( $input, true );
505
506	if ( $return === null ) {
507	wp_parse_str( $input, $return );
508	}
509
510	break;
511	default:
512	wp_parse_str( $input, $return );
513	break;
514	}
515
516	if ( isset( $this->api->query['force'] )
517	&& 'secure' === $this->api->query['force']
518	&& isset( $return['secure_key'] ) ) {
519	$this->api->post_body = $this->get_secure_body( $return['secure_key'] );
520	$this->api->query['force'] = false;
521	return $this->input( $return_default_values, $cast_and_filter );
522	}
523
524	if ( $cast_and_filter ) {
525	$return = $this->cast_and_filter( $return, $this->request_format, $return_default_values );
526	}
527	return $return;
528	}
529
530	/**
531	* Fetch a body via secure request.
532	*
533	* @param string $secure_key Key for the request.
534	* @return mixed\|null API response, or null if the request failed.
535	*/
536	protected function get_secure_body( $secure_key ) {
537	$response = Client::wpcom_json_api_request_as_blog(
538	sprintf( '/sites/%d/secure-request', Jetpack_Options::get_option( 'id' ) ),
539	'1.1',
540	array( 'method' => 'POST' ),
541	array( 'secure_key' => $secure_key )
542	);
543	if ( 200 !== $response['response']['code'] ) {
544	return null;
545	}
546	return json_decode( $response['body'], true );
547	}
548
549	/**
550	* Cast and filter data.
551	*
552	* @param mixed $data Data to cast and filter.
553	* @param array $documentation Documentation for keys in `$data` to keep and cast.
554	* @param bool $return_default_values Set default values from `$documentation` to process.
555	* @param bool $for_output See `$this->cast_and_filter_item()`.
556	* @return mixed Filtered data.
557	*/
558	public function cast_and_filter( $data, $documentation, $return_default_values = false, $for_output = false ) {
559	$return_as_object = false;
560	if ( is_object( $data ) ) {
561	// @todo this should probably be a deep copy if $data can ever have nested objects
562	$data = (array) $data;
563	$return_as_object = true;
564	} elseif ( ! is_array( $data ) ) {
565	return $data;
566	}
567
568	$boolean_arg = array( 'false', 'true' );
569	$naeloob_arg = array( 'true', 'false' );
570
571	$return = array();
572
573	foreach ( $documentation as $key => $description ) {
574	if ( is_array( $description ) ) {
575	// String or boolean array keys only.
576	$whitelist = array_keys( $description );
577
578	if ( $whitelist === $boolean_arg \|\| $whitelist === $naeloob_arg ) {
579	// Truthiness.
580	if ( isset( $data[ $key ] ) ) {
581	$return[ $key ] = (bool) WPCOM_JSON_API::is_truthy( $data[ $key ] );
582	} elseif ( $return_default_values ) {
583	$return[ $key ] = $whitelist === $naeloob_arg; // Default to true for naeloob_arg and false for boolean_arg.
584	}
585	} elseif ( isset( $data[ $key ] ) && isset( $description[ $data[ $key ] ] ) ) {
586	// String Key.
587	$return[ $key ] = (string) $data[ $key ];
588	} elseif ( $return_default_values ) {
589	// Default value.
590	$return[ $key ] = (string) current( $whitelist );
591	}
592
593	continue;
594	}
595
596	$types = $this->parse_types( $description );
597	$type = array_shift( $types );
598
599	// Explicit default - string and int only for now. Always set these reguardless of $return_default_values.
600	if ( isset( $type['default'] ) ) {
601	if ( ! isset( $data[ $key ] ) ) {
602	$data[ $key ] = $type['default'];
603	}
604	}
605
606	if ( ! isset( $data[ $key ] ) ) {
607	continue;
608	}
609
610	$this->cast_and_filter_item( $return, $type, $key, $data[ $key ], $types, $for_output );
611	}
612
613	if ( $return_as_object ) {
614	return (object) $return;
615	}
616
617	return $return;
618	}
619
620	/**
621	* Casts $value according to $type.
622	* Handles fallbacks for certain values of $type when $value is not that $type
623	* Currently, only handles fallback between string <-> array (two way), from string -> false (one way), and from object -> false (one way),
624	* and string -> object (one way)
625	*
626	* Handles "child types" - array:URL, object:category
627	* array:URL means an array of URLs
628	* object:category means a hash of categories
629	*
630	* Handles object typing - object>post means an object of type post
631	*
632	* @param array $return Array to assign the value into.
633	* @param string\|array $type Type to cast.
634	* @param string\|int $key Key in `$return` to assign the value to.
635	* @param mixed $value Value to cast.
636	* @param array $types Fallback types.
637	* @param bool $for_output Appears to affect formatting of 'date' types.
638	*/
639	public function cast_and_filter_item( &$return, $type, $key, $value, $types = array(), $for_output = false ) {
640	if ( is_string( $type ) ) {
641	$type = compact( 'type' );
642	}
643
644	switch ( $type['type'] ) {
645	case 'false':
646	$return[ $key ] = false;
647	break;
648	case 'url':
649	if ( is_object( $value ) && isset( $value->url ) && str_contains( $value->url, 'https://videos.files.wordpress.com/' ) ) {
650	$value = $value->url;
651	}
652	// Check for string since esc_url_raw() expects one.
653	if ( ! is_string( $value ) ) {
654	break;
655	}
656	$return[ $key ] = (string) esc_url_raw( $value );
657	break;
658	case 'string':
659	// Fallback string -> array, or for string -> object.
660	if ( is_array( $value ) \|\| is_object( $value ) ) {
661	if ( ! empty( $types[0] ) ) {
662	$next_type = array_shift( $types );
663	return $this->cast_and_filter_item( $return, $next_type, $key, $value, $types, $for_output );
664	}
665	}
666
667	// Fallback string -> false.
668	if ( ! is_string( $value ) ) {
669	if ( ! empty( $types[0] ) && 'false' === $types[0]['type'] ) {
670	$next_type = array_shift( $types );
671	return $this->cast_and_filter_item( $return, $next_type, $key, $value, $types, $for_output );
672	}
673	if ( is_array( $value ) ) {
674	// Give up rather than setting the value to the string 'Array'.
675	break;
676	}
677	}
678	$return[ $key ] = (string) $value;
679	break;
680	case 'html':
681	$return[ $key ] = (string) $value;
682	break;
683	case 'safehtml':
684	$return[ $key ] = wp_kses( (string) $value, wp_kses_allowed_html() );
685	break;
686	case 'zip':
687	case 'media':
688	if ( is_array( $value ) ) {
689	if ( isset( $value['name'] ) && is_array( $value['name'] ) ) {
690	// It's a $_FILES array
691	// Reformat into array of $_FILES items.
692	$files = array();
693
694	foreach ( $value['name'] as $k => $v ) {
695	$files[ $k ] = array();
696	foreach ( array_keys( $value ) as $file_key ) {
697	$files[ $k ][ $file_key ] = $value[ $file_key ][ $k ];
698	}
699	}
700
701	foreach ( $files as $k => $file ) {
702	if ( ! isset( $file['tmp_name'] ) \|\| ! is_string( $file['tmp_name'] ) \|\| ! is_uploaded_file( $file['tmp_name'] ) ) {
703	unset( $files[ $k ] );
704	}
705	}
706	if ( $files ) {
707	$return[ $key ] = $files;
708	}
709	} elseif ( isset( $value['tmp_name'] ) && is_string( $value['tmp_name'] ) && is_uploaded_file( $value['tmp_name'] ) ) {
710	$return[ $key ] = $value;
711	}
712	}
713	break;
714	case 'array':
715	// Fallback array -> string.
716	if ( is_string( $value ) ) {
717	if ( ! empty( $types[0] ) ) {
718	$next_type = array_shift( $types );
719	return $this->cast_and_filter_item( $return, $next_type, $key, $value, $types, $for_output );
720	}
721	}
722
723	if ( isset( $type['children'] ) ) {
724	$children = array();
725	foreach ( (array) $value as $k => $child ) {
726	$this->cast_and_filter_item( $children, $type['children'], $k, $child, array(), $for_output );
727	}
728	$return[ $key ] = (array) $children;
729	break;
730	}
731
732	$return[ $key ] = (array) $value;
733	break;
734	case 'iso 8601 datetime':
735	case 'datetime':
736	// (string)s
737	$dates = $this->parse_date( (string) $value );
738	if ( $for_output ) {
739	$return[ $key ] = $this->format_date( $dates[1], $dates[0] );
740	} else {
741	list( $return[ $key ], $return[ "{$key}_gmt" ] ) = $dates;
742	}
743	break;
744	case 'float':
745	$return[ $key ] = (float) $value;
746	break;
747	case 'int':
748	case 'integer':
749	$return[ $key ] = (int) $value;
750	break;
751	case 'bool':
752	case 'boolean':
753	$return[ $key ] = (bool) WPCOM_JSON_API::is_truthy( $value );
754	break;
755	case 'object':
756	// Fallback object -> false.
757	if ( is_scalar( $value ) \|\| $value === null ) {
758	if ( ! empty( $types[0] ) && 'false' === $types[0]['type'] ) {
759	return $this->cast_and_filter_item( $return, 'false', $key, $value, $types, $for_output );
760	}
761	}
762
763	if ( isset( $type['children'] ) ) {
764	$children = array();
765	foreach ( (array) $value as $k => $child ) {
766	$this->cast_and_filter_item( $children, $type['children'], $k, $child, array(), $for_output );
767	}
768	$return[ $key ] = (object) $children;
769	break;
770	}
771
772	if ( isset( $type['subtype'] ) ) {
773	return $this->cast_and_filter_item( $return, $type['subtype'], $key, $value, $types, $for_output );
774	}
775
776	$return[ $key ] = (object) $value;
777	break;
778	case 'post':
779	$return[ $key ] = (object) $this->cast_and_filter( $value, $this->post_object_format, false, $for_output );
780	break;
781	case 'comment':
782	$return[ $key ] = (object) $this->cast_and_filter( $value, $this->comment_object_format, false, $for_output );
783	break;
784	case 'tag':
785	case 'category':
786	$docs = array(
787	'ID' => '(int)',
788	'name' => '(string)',
789	'slug' => '(string)',
790	'description' => '(HTML)',
791	'post_count' => '(int)',
792	'feed_url' => '(string)',
793	'meta' => '(object)',
794	);
795	if ( 'category' === $type['type'] ) {
796	$docs['parent'] = '(int)';
797	}
798	$return[ $key ] = (object) $this->cast_and_filter( $value, $docs, false, $for_output );
799	break;
800	case 'post_reference':
801	case 'comment_reference':
802	$docs = array(
803	'ID' => '(int)',
804	'type' => '(string)',
805	'title' => '(string)',
806	'link' => '(URL)',
807	);
808	$return[ $key ] = (object) $this->cast_and_filter( $value, $docs, false, $for_output );
809	break;
810	case 'geo':
811	$docs = array(
812	'latitude' => '(float)',
813	'longitude' => '(float)',
814	'address' => '(string)',
815	);
816	$return[ $key ] = (object) $this->cast_and_filter( $value, $docs, false, $for_output );
817	break;
818	case 'author':
819	$docs = array(
820	'ID' => '(int)',
821	'user_login' => '(string)',
822	'login' => '(string)',
823	'email' => '(string\|false)',
824	'name' => '(string)',
825	'first_name' => '(string)',
826	'last_name' => '(string)',
827	'nice_name' => '(string)',
828	'URL' => '(URL)',
829	'avatar_URL' => '(URL)',
830	'profile_URL' => '(URL)',
831	'is_super_admin' => '(bool)',
832	'roles' => '(array:string)',
833	'ip_address' => '(string\|false)',
834	'wpcom_id' => '(int\|null)',
835	'wpcom_login' => '(string\|null)',
836	);
837	$return[ $key ] = (object) $this->cast_and_filter( $value, $docs, false, $for_output );
838	break;
839	case 'role':
840	$docs = array(
841	'name' => '(string)',
842	'display_name' => '(string)',
843	'capabilities' => '(object:boolean)',
844	);
845	$return[ $key ] = (object) $this->cast_and_filter( $value, $docs, false, $for_output );
846	break;
847	case 'attachment':
848	$docs = array(
849	'ID' => '(int)',
850	'URL' => '(URL)',
851	'guid' => '(string)',
852	'mime_type' => '(string)',
853	'width' => '(int)',
854	'height' => '(int)',
855	'duration' => '(int)',
856	);
857	$return[ $key ] = (object) $this->cast_and_filter(
858	$value,
859	/**
860	* Filter the documentation returned for a post attachment.
861	*
862	* @module json-api
863	*
864	* @since 1.9.0
865	*
866	* @param array $docs Array of documentation about a post attachment.
867	*/
868	apply_filters( 'wpcom_json_api_attachment_cast_and_filter', $docs ),
869	false,
870	$for_output
871	);
872	break;
873	case 'metadata':
874	$docs = array(
875	'id' => '(int)',
876	'key' => '(string)',
877	'value' => '(string\|false\|float\|int\|array\|object)',
878	'previous_value' => '(string)',
879	'operation' => '(string)',
880	);
881	$return[ $key ] = (object) $this->cast_and_filter(
882	$value,
883	/** This filter is documented in class.json-api-endpoints.php */
884	apply_filters( 'wpcom_json_api_attachment_cast_and_filter', $docs ),
885	false,
886	$for_output
887	);
888	break;
889	case 'plugin':
890	$docs = array(
891	'id' => '(safehtml) The plugin\'s ID',
892	'slug' => '(safehtml) The plugin\'s Slug',
893	'active' => '(boolean) The plugin status.',
894	'update' => '(object) The plugin update info.',
895	'name' => '(safehtml) The name of the plugin.',
896	'plugin_url' => '(url) Link to the plugin\'s web site.',
897	'version' => '(safehtml) The plugin version number.',
898	'description' => '(safehtml) Description of what the plugin does and/or notes from the author',
899	'author' => '(safehtml) The plugin author\'s name',
900	'author_url' => '(url) The plugin author web site address',
901	'network' => '(boolean) Whether the plugin can only be activated network wide.',
902	'autoupdate' => '(boolean) Whether the plugin is auto updated',
903	'log' => '(array:safehtml) An array of update log strings.',
904	'action_links' => '(array) An array of action links that the plugin uses.',
905	);
906	$return[ $key ] = (object) $this->cast_and_filter(
907	$value,
908	/**
909	* Filter the documentation returned for a plugin.
910	*
911	* @module json-api
912	*
913	* @since 3.1.0
914	*
915	* @param array $docs Array of documentation about a plugin.
916	*/
917	apply_filters( 'wpcom_json_api_plugin_cast_and_filter', $docs ),
918	false,
919	$for_output
920	);
921	break;
922	case 'plugin_v1_2':
923	$docs = class_exists( 'Jetpack_JSON_API_Get_Plugins_v1_2_Endpoint' )
924	? Jetpack_JSON_API_Get_Plugins_v1_2_Endpoint::$_response_format
925	: Jetpack_JSON_API_Plugins_Endpoint::$_response_format_v1_2;
926	$return[ $key ] = (object) $this->cast_and_filter(
927	$value,
928	/**
929	* Filter the documentation returned for a plugin.
930	*
931	* @module json-api
932	*
933	* @since 3.1.0
934	*
935	* @param array $docs Array of documentation about a plugin.
936	*/
937	apply_filters( 'wpcom_json_api_plugin_cast_and_filter', $docs ),
938	false,
939	$for_output
940	);
941	break;
942	case 'file_mod_capabilities':
943	$docs = array(
944	'reasons_modify_files_unavailable' => '(array) The reasons why files can\'t be modified',
945	'reasons_autoupdate_unavailable' => '(array) The reasons why autoupdates aren\'t allowed',
946	'modify_files' => '(boolean) true if files can be modified',
947	'autoupdate_files' => '(boolean) true if autoupdates are allowed',
948	);
949	$return[ $key ] = (array) $this->cast_and_filter( $value, $docs, false, $for_output );
950	break;
951	case 'jetpackmodule':
952	$docs = array(
953	'id' => '(string) The module\'s ID',
954	'active' => '(boolean) The module\'s status.',
955	'name' => '(string) The module\'s name.',
956	'description' => '(safehtml) The module\'s description.',
957	'sort' => '(int) The module\'s display order.',
958	'introduced' => '(string) The Jetpack version when the module was introduced.',
959	'changed' => '(string) The Jetpack version when the module was changed.',
960	'free' => '(boolean) The module\'s Free or Paid status.',
961	'module_tags' => '(array) The module\'s tags.',
962	'override' => '(string) The module\'s override. Empty if no override, otherwise \'active\' or \'inactive\'',
963	);
964	$return[ $key ] = (object) $this->cast_and_filter(
965	$value,
966	/** This filter is documented in class.json-api-endpoints.php */
967	apply_filters( 'wpcom_json_api_plugin_cast_and_filter', $docs ),
968	false,
969	$for_output
970	);
971	break;
972	case 'sharing_button':
973	$docs = array(
974	'ID' => '(string)',
975	'name' => '(string)',
976	'URL' => '(string)',
977	'icon' => '(string)',
978	'enabled' => '(bool)',
979	'visibility' => '(string)',
980	);
981	$return[ $key ] = (array) $this->cast_and_filter( $value, $docs, false, $for_output );
982	break;
983	case 'sharing_button_service':
984	$docs = array(
985	'ID' => '(string) The service identifier',
986	'name' => '(string) The service name',
987	'class_name' => '(string) Class name for custom style sharing button elements',
988	'genericon' => '(string) The Genericon unicode character for the custom style sharing button icon',
989	'preview_smart' => '(string) An HTML snippet of a rendered sharing button smart preview',
990	'preview_smart_js' => '(string) An HTML snippet of the page-wide initialization scripts used for rendering the sharing button smart preview',
991	);
992	$return[ $key ] = (array) $this->cast_and_filter( $value, $docs, false, $for_output );
993	break;
994	case 'site_keyring':
995	$docs = array(
996	'keyring_id' => '(int) Keyring ID',
997	'service' => '(string) The service name',
998	'external_user_id' => '(string) External user id for the service',
999	);
1000	$return[ $key ] = (array) $this->cast_and_filter( $value, $docs, false, $for_output );
1001	break;
1002	case 'taxonomy':
1003	$docs = array(
1004	'name' => '(string) The taxonomy slug',
1005	'label' => '(string) The taxonomy human-readable name',
1006	'labels' => '(object) Mapping of labels for the taxonomy',
1007	'description' => '(string) The taxonomy description',
1008	'hierarchical' => '(bool) Whether the taxonomy is hierarchical',
1009	'public' => '(bool) Whether the taxonomy is public',
1010	'capabilities' => '(object) Mapping of current user capabilities for the taxonomy',
1011	);
1012	$return[ $key ] = (array) $this->cast_and_filter( $value, $docs, false, $for_output );
1013	break;
1014	case 'visibility':
1015	// This is needed to fix a bug in WPAndroid where `public: "PUBLIC"` is sent in place of `public: 1`.
1016	if ( 'public' === strtolower( $value ) ) {
1017	$return[ $key ] = 1;
1018	} elseif ( 'private' === strtolower( $value ) ) {
1019	$return[ $key ] = -1;
1020	} else {
1021	$return[ $key ] = (int) $value;
1022	}
1023	break;
1024	case 'dropdown_page':
1025	$return[ $key ] = (array) $this->cast_and_filter( $value, $this->dropdown_page_object_format, false, $for_output );
1026	break;
1027	default:
1028	$method_name = $type['type'] . '_docs';
1029	if ( method_exists( 'WPCOM_JSON_API_Jetpack_Overrides', $method_name ) ) {
1030	$docs = WPCOM_JSON_API_Jetpack_Overrides::$method_name();
1031	}
1032
1033	if ( ! empty( $docs ) ) {
1034	$return[ $key ] = (object) $this->cast_and_filter(
1035	$value,
1036	/** This filter is documented in class.json-api-endpoints.php */
1037	apply_filters( 'wpcom_json_api_plugin_cast_and_filter', $docs ),
1038	false,
1039	$for_output
1040	);
1041	} else {
1042	// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_trigger_error, WordPress.Security.EscapeOutput.OutputNotEscaped
1043	trigger_error( "Unknown API casting type {$type['type']}", E_USER_WARNING );
1044	}
1045	}
1046	}
1047
1048	/**
1049	* Parse types from text.
1050	*
1051	* @param string $text Text.
1052	* @return array Types.
1053	*/
1054	public function parse_types( $text ) {
1055	if ( ! preg_match( '#^$([^)]+)$#', ltrim( $text ), $matches ) ) {
1056	return 'none';
1057	}
1058
1059	$types = explode( '\|', strtolower( $matches[1] ) );
1060	$return = array();
1061	foreach ( $types as $type ) {
1062	foreach ( array(
1063	':' => 'children',
1064	'>' => 'subtype',
1065	'=' => 'default',
1066	) as $operator => $meaning ) {
1067	if ( str_contains( $type, $operator ) ) {
1068	$item = explode( $operator, $type, 2 );
1069	$return[] = array(
1070	'type' => $item[0],
1071	$meaning => $item[1],
1072	);
1073	continue 2;
1074	}
1075	}
1076	$return[] = compact( 'type' );
1077	}
1078
1079	return $return;
1080	}
1081
1082	/**
1083	* Checks if the endpoint is publicly displayable
1084	*
1085	* @return bool
1086	*/
1087	public function is_publicly_documentable() {
1088	return '__do_not_document' !== $this->group && true !== $this->in_testing;
1089	}
1090
1091	/**
1092	* Auto generates documentation based on description, method, path, path_labels, and query parameters.
1093	* Echoes HTML.
1094	*
1095	* @param bool $show_description Whether to show the description.
1096	*/
1097	public function document( $show_description = true ) {
1098	global $wpdb;
1099	$original_post = $GLOBALS['post'] ?? 'unset';
1100	unset( $GLOBALS['post'] );
1101
1102	$doc = $this->generate_documentation();
1103
1104	if ( $show_description ) :
1105	?>
1106	<caption>
1107	<h1><?php echo wp_kses_post( $doc['method'] ); ?> <?php echo wp_kses_post( $doc['path_labeled'] ); ?></h1>
1108	<p><?php echo wp_kses_post( $doc['description'] ); ?></p>
1109	</caption>
1110
1111	<?php endif; ?>
1112
1113	<?php if ( true === $this->deprecated ) { ?>
1114	<p><strong>This endpoint is deprecated in favor of version <?php echo (float) $this->new_version; ?></strong></p>
1115	<?php } ?>
1116
1117	<section class="resource-info">
1118	<h2 id="apidoc-resource-info">Resource Information</h2>
1119
1120	<table class="api-doc api-doc-resource-parameters api-doc-resource">
1121
1122	<thead>
1123	<tr>
1124	<th class="api-index-title" scope="column"> </th>
1125	<th class="api-index-title" scope="column"> </th>
1126	</tr>
1127	</thead>
1128	<tbody>
1129
1130	<tr class="api-index-item">
1131	<th scope="row" class="parameter api-index-item-title">Method</th>
1132	<td class="type api-index-item-title"><?php echo wp_kses_post( $doc['method'] ); ?></td>
1133	</tr>
1134
1135	<tr class="api-index-item">
1136	<th scope="row" class="parameter api-index-item-title">URL</th>
1137	<?php
1138	$version = WPCOM_JSON_API__CURRENT_VERSION;
1139	if ( ! empty( $this->max_version ) ) {
1140	$version = $this->max_version;
1141	}
1142	?>
1143	<td class="type api-index-item-title">https://public-api.wordpress.com/rest/v<?php echo (float) $version; ?><?php echo wp_kses_post( $doc['path_labeled'] ); ?></td>
1144	</tr>
1145
1146	<tr class="api-index-item">
1147	<th scope="row" class="parameter api-index-item-title">Requires authentication?</th>
1148	<?php
1149	$requires_auth = $wpdb->get_row( $wpdb->prepare( 'SELECT requires_authentication FROM rest_api_documentation WHERE `version` = %s AND `path` = %s AND `method` = %s LIMIT 1', $version, untrailingslashit( $doc['path_labeled'] ), $doc['method'] ) );
1150	?>
1151	<td class="type api-index-item-title"><?php echo ( ! empty( $requires_auth->requires_authentication ) ? 'Yes' : 'No' ); ?></td>
1152	</tr>
1153
1154	</tbody>
1155	</table>
1156
1157	</section>
1158
1159	<?php
1160
1161	foreach ( array(
1162	'path' => 'Method Parameters',
1163	'query' => 'Query Parameters',
1164	'body' => 'Request Parameters',
1165	'response' => 'Response Parameters',
1166	) as $doc_section_key => $label ) :
1167	$doc_section = 'response' === $doc_section_key ? $doc['response']['body'] : $doc['request'][ $doc_section_key ];
1168	if ( ! $doc_section ) {
1169	continue;
1170	}
1171
1172	$param_label = strtolower( str_replace( ' ', '-', $label ) );
1173	?>
1174
1175	<section class="<?php echo esc_attr( $param_label ); ?>">
1176
1177	<h2 id="apidoc-<?php echo esc_attr( $doc_section_key ); ?>"><?php echo wp_kses_post( $label ); ?></h2>
1178
1179	<table class="api-doc api-doc-<?php echo esc_attr( $param_label ); ?>-parameters api-doc-<?php echo esc_attr( strtolower( str_replace( ' ', '-', $doc['group'] ) ) ); ?>">
1180
1181	<thead>
1182	<tr>
1183	<th class="api-index-title" scope="column">Parameter</th>
1184	<th class="api-index-title" scope="column">Type</th>
1185	<th class="api-index-title" scope="column">Description</th>
1186	</tr>
1187	</thead>
1188	<tbody>
1189
1190	<?php foreach ( $doc_section as $key => $item ) : ?>
1191
1192	<tr class="api-index-item">
1193	<th scope="row" class="parameter api-index-item-title"><?php echo wp_kses_post( $key ); ?></th>
1194	<td class="type api-index-item-title"><?php echo wp_kses_post( $item['type'] ); // @todo auto-link? ?></td>
1195	<td class="description api-index-item-body">
1196	<?php
1197
1198	$this->generate_doc_description( $item['description'] );
1199
1200	?>
1201	</td>
1202	</tr>
1203
1204	<?php endforeach; ?>
1205	</tbody>
1206	</table>
1207	</section>
1208	<?php endforeach; ?>
1209
1210	<?php
1211	if ( 'unset' !== $original_post ) {
1212	$GLOBALS['post'] = $original_post; // phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited
1213	}
1214	}
1215
1216	/**
1217	* `preg_replace_callback` callback to add http_build_query to php content example.
1218	*
1219	* @todo Is this used anywhere?
1220	*
1221	* @param array $matches Matches.
1222	* @return string
1223	*/
1224	public function add_http_build_query_to_php_content_example( $matches ) {
1225	$trimmed_match = ltrim( $matches[0] );
1226	$pad = substr( $matches[0], 0, -1 * strlen( $trimmed_match ) );
1227	$pad = ltrim( $pad, ' ' );
1228	$return = ' ' . str_replace( "\n", "\n ", $matches[0] );
1229	return " http_build_query({$return}{$pad})";
1230	}
1231
1232	/**
1233	* Recursively generates the <dl>'s to document item descriptions.
1234	* Echoes HTML.
1235	*
1236	* @param string\|array $item Post data to output, or an array of key => data mappings.
1237	*/
1238	public function generate_doc_description( $item ) {
1239	if ( is_array( $item ) ) :
1240	?>
1241
1242	<dl>
1243	<?php foreach ( $item as $description_key => $description_value ) : ?>
1244
1245	<dt><?php echo wp_kses_post( $description_key . ':' ); ?></dt>
1246	<dd><?php $this->generate_doc_description( $description_value ); ?></dd>
1247
1248	<?php endforeach; ?>
1249
1250	</dl>
1251
1252	<?php
1253	else :
1254	echo wp_kses_post( $item );
1255	endif;
1256	}
1257
1258	/**
1259	* Auto generates documentation based on description, method, path, path_labels, and query parameters.
1260	* Echoes HTML.
1261	*/
1262	public function generate_documentation() {
1263	$format = str_replace( '%d', '%s', $this->path );
1264	$path_labeled = $format;
1265	if ( ! empty( $this->path_labels ) ) {
1266	$path_labeled = vsprintf( $format, array_keys( $this->path_labels ) );
1267	}
1268	$boolean_arg = array( 'false', 'true' );
1269	$naeloob_arg = array( 'true', 'false' );
1270
1271	$doc = array(
1272	'description' => $this->description,
1273	'method' => $this->method,
1274	'path_format' => $this->path,
1275	'path_labeled' => $path_labeled,
1276	'group' => $this->group,
1277	'request' => array(
1278	'path' => array(),
1279	'query' => array(),
1280	'body' => array(),
1281	),
1282	'response' => array(
1283	'body' => array(),
1284	),
1285	);
1286
1287	foreach ( array(
1288	'path_labels' => 'path',
1289	'query' => 'query',
1290	'request_format' => 'body',
1291	'response_format' => 'body',
1292	) as $_property => $doc_item ) {
1293	foreach ( (array) $this->$_property as $key => $description ) {
1294	if ( is_array( $description ) ) {
1295	$description_keys = array_keys( $description );
1296	if ( $boolean_arg === $description_keys \|\| $naeloob_arg === $description_keys ) {
1297	$type = '(bool)';
1298	} else {
1299	$type = '(string)';
1300	}
1301
1302	if ( 'response_format' !== $_property ) {
1303	// hack - don't show "(default)" in response format.
1304	reset( $description );
1305	$description_key = key( $description );
1306	$description[ $description_key ] = "(default) {$description[$description_key]}";
1307	}
1308	} else {
1309	$types = $this->parse_types( $description );
1310	$type = array();
1311	$default = '';
1312
1313	if ( 'none' === $types ) {
1314	$types = array();
1315	$types[]['type'] = 'none';
1316	}
1317
1318	foreach ( $types as $type_array ) {
1319	$type[] = $type_array['type'];
1320	if ( isset( $type_array['default'] ) ) {
1321	$default = $type_array['default'];
1322	if ( 'string' === $type_array['type'] ) {
1323	$default = "'$default'";
1324	}
1325	}
1326	}
1327	$type = '(' . implode( '\|', $type ) . ')';
1328	if ( str_contains( $description, ')' ) ) {
1329	list( , $description ) = explode( ')', $description, 2 );
1330	}
1331	$description = trim( $description );
1332	if ( $default ) {
1333	$description .= " Default: $default.";
1334	}
1335	}
1336
1337	$item = compact( 'type', 'description' );
1338
1339	if ( 'response_format' === $_property ) {
1340	$doc['response'][ $doc_item ][ $key ] = $item;
1341	} else {
1342	$doc['request'][ $doc_item ][ $key ] = $item;
1343	}
1344	}
1345	}
1346
1347	return $doc;
1348	}
1349
1350	/**
1351	* Can the user view the post?
1352	*
1353	* @param int $post_id Post ID.
1354	* @return bool\|WP_Error
1355	*/
1356	public function user_can_view_post( $post_id ) {
1357	$post = get_post( $post_id );
1358	if ( ! $post \|\| is_wp_error( $post ) ) {
1359	return false;
1360	}
1361
1362	if ( 'inherit' === $post->post_status ) {
1363	$parent_post = get_post( $post->post_parent );
1364	$post_status_obj = get_post_status_object( $parent_post->post_status ?? $post->post_status );
1365	} else {
1366	$post_status_obj = get_post_status_object( $post->post_status );
1367	}
1368
1369	if ( empty( $post_status_obj->public ) ) {
1370	if ( is_user_logged_in() ) {
1371	if ( ! empty( $post_status_obj->protected ) ) {
1372	if ( ! current_user_can( 'edit_post', $post->ID ) ) {
1373	return new WP_Error( 'unauthorized', 'User cannot view post', 403 );
1374	}
1375	} elseif ( ! empty( $post_status_obj->private ) ) {
1376	if ( ! current_user_can( 'read_post', $post->ID ) ) {
1377	return new WP_Error( 'unauthorized', 'User cannot view post', 403 );
1378	}
1379	} elseif ( in_array( $post->post_status, array( 'inherit', 'trash' ), true ) ) {
1380	if ( ! current_user_can( 'edit_post', $post->ID ) ) {
1381	return new WP_Error( 'unauthorized', 'User cannot view post', 403 );
1382	}
1383	} elseif ( 'auto-draft' === $post->post_status ) { // phpcs:ignore Generic.CodeAnalysis.EmptyStatement.DetectedElseif
1384	// allow auto-drafts.
1385	} else {
1386	return new WP_Error( 'unauthorized', 'User cannot view post', 403 );
1387	}
1388	} else {
1389	return new WP_Error( 'unauthorized', 'User cannot view post', 403 );
1390	}
1391	}
1392
1393	if (
1394	( new Status() )->is_private_site() &&
1395	/**
1396	* Filter access to a specific post.
1397	*
1398	* @module json-api
1399	*
1400	* @since 3.4.0
1401	*
1402	* @param bool current_user_can( 'read_post', $post->ID ) Can the current user access the post.
1403	* @param WP_Post $post Post data.
1404	*/
1405	! apply_filters(
1406	'wpcom_json_api_user_can_view_post',
1407	current_user_can( 'read_post', $post->ID ),
1408	$post
1409	)
1410	) {
1411	return new WP_Error(
1412	'unauthorized',
1413	'User cannot view post',
1414	array(
1415	'status_code' => 403,
1416	'error' => 'private_blog',
1417	)
1418	);
1419	}
1420
1421	if ( strlen( $post->post_password ) && ! current_user_can( 'edit_post', $post->ID ) ) {
1422	return new WP_Error(
1423	'unauthorized',
1424	'User cannot view password protected post',
1425	array(
1426	'status_code' => 403,
1427	'error' => 'password_protected',
1428	)
1429	);
1430	}
1431
1432	return true;
1433	}
1434
1435	/**
1436	* Returns author object.
1437	*
1438	* @param object $author user ID, user row, WP_User object, comment row, post row.
1439	* @param bool $show_email_and_ip output the author's email address and IP address?.
1440	*
1441	* @return object
1442	*/
1443	public function get_author( $author, $show_email_and_ip = false ) {
1444	$is_jetpack = null;
1445	$login = null;
1446	$email = null;
1447	$name = null;
1448	$first_name = null;
1449	$last_name = null;
1450	$nice = null;
1451	$url = null;
1452	$ip_address = $author->comment_author_IP ?? '';
1453	$site_id = -1;
1454
1455	if ( isset( $author->comment_author_email ) ) {
1456	$id = empty( $author->user_id ) ? 0 : (int) $author->user_id;
1457	$login = '';
1458	$email = $author->comment_author_email;
1459	$name = $author->comment_author;
1460	$first_name = '';
1461	$last_name = '';
1462	$avatar_url = $this->api->get_avatar_url( $author );
1463	$nice = '';
1464	$url = $author->comment_author_url;
1465	// Convert Gravatar URLs containing an email address to the hashed version.
1466	if ( preg_match( '#^https?://(?:www\.)?gravatar\.com/([^/?]+)#i', $url, $matches ) && is_email( $matches[1] ) ) {
1467	$url = 'https://gravatar.com/' . md5( strtolower( trim( $matches[1] ) ) );
1468	}
1469
1470	// Add additional user data to the response if a valid user ID is available.
1471	if ( 0 < $id ) {
1472	$user = get_user_by( 'id', $id );
1473	if ( $user instanceof WP_User ) {
1474	$login = $user->user_login ?? '';
1475	$first_name = $user->first_name ?? '';
1476	$last_name = $user->last_name ?? '';
1477	$nice = $user->user_nicename ?? '';
1478	}
1479	}
1480
1481	// Comment author URLs and Emails are sent through wp_kses() on save, which replaces "&" with "&"
1482	// "&" is the only email/URL character altered by wp_kses().
1483	foreach ( array( 'email', 'url' ) as $field ) {
1484	$$field = str_replace( '&', '&', $$field );
1485	}
1486	} elseif ( $author instanceof WP_User \|\| isset( $author->user_email ) ) {
1487	$author = $author->ID;
1488	} elseif ( isset( $author->user_id ) && $author->user_id ) {
1489	$author = $author->user_id;
1490	} elseif ( isset( $author->post_author ) ) {
1491	// then $author is a Post Object.
1492	if ( ! $author->post_author ) {
1493	return null;
1494	}
1495	/**
1496	* Filter whether the current site is a Jetpack site.
1497	*
1498	* @module json-api
1499	*
1500	* @since 3.3.0
1501	*
1502	* @param bool false Is the current site a Jetpack site. Default to false.
1503	* @param int get_current_blog_id() Blog ID.
1504	*/
1505	$is_jetpack = true === apply_filters( 'is_jetpack_site', false, get_current_blog_id() );
1506	$post_id = $author->ID;
1507	if ( $is_jetpack && ( defined( 'IS_WPCOM' ) && IS_WPCOM ) ) {
1508	$id = get_post_meta( $post_id, '_jetpack_post_author_external_id', true );
1509	$email = get_post_meta( $post_id, '_jetpack_author_email', true );
1510	$login = '';
1511	$name = get_post_meta( $post_id, '_jetpack_author', true );
1512	$first_name = '';
1513	$last_name = '';
1514	$url = '';
1515	$nice = '';
1516	} else {
1517	$author = $author->post_author;
1518	}
1519	}
1520
1521	if ( ! isset( $id ) ) {
1522	$user = get_user_by( 'id', $author );
1523	if ( ! $user \|\| is_wp_error( $user ) ) {
1524	return null;
1525	}
1526	$id = $user->ID;
1527	$email = $user->user_email;
1528	$login = $user->user_login;
1529	$name = $user->display_name;
1530	$first_name = $user->first_name;
1531	$last_name = $user->last_name;
1532	$url = $user->user_url;
1533	$nice = $user->user_nicename;
1534	}
1535	if ( defined( 'IS_WPCOM' ) && IS_WPCOM && ! $is_jetpack && $id > 0 ) {
1536	/**
1537	* Allow customizing the blog ID returned with the author in WordPress.com REST API queries.
1538	*
1539	* @since 12.9
1540	*
1541	* @module json-api
1542	*
1543	* @param bool\|int $active_blog Blog ID, or false by default.
1544	* @param int $id User ID.
1545	*/
1546	$active_blog = apply_filters( 'wpcom_api_pre_get_active_blog_author', false, $id );
1547	if ( false === $active_blog ) {
1548	$active_blog = get_active_blog_for_user( $id );
1549	}
1550	if ( ! empty( $active_blog ) ) {
1551	$site_id = $active_blog->blog_id;
1552	}
1553	if ( $site_id > - 1 ) {
1554	$site_visible = (
1555	- 1 !== (int) $active_blog->public \|\|
1556	is_private_blog_user( $site_id, get_current_user_id() )
1557	);
1558	}
1559	$profile_url = "https://gravatar.com/{$login}";
1560	} else {
1561	$profile_url = 'https://gravatar.com/' . md5( strtolower( trim( $email ) ) );
1562	}
1563
1564	if ( ! isset( $avatar_url ) ) {
1565	$avatar_url = $this->api->get_avatar_url( $email );
1566	}
1567
1568	if ( $show_email_and_ip ) {
1569	$email = (string) $email;
1570	$ip_address = (string) $ip_address;
1571	} else {
1572	$email = false;
1573	$ip_address = false;
1574	}
1575
1576	$author = array(
1577	'ID' => (int) $id,
1578	'login' => (string) $login,
1579	'email' => $email, // string\|bool.
1580	'name' => (string) $name,
1581	'first_name' => (string) $first_name,
1582	'last_name' => (string) $last_name,
1583	'nice_name' => (string) $nice,
1584	'URL' => (string) esc_url_raw( $url ),
1585	'avatar_URL' => (string) esc_url_raw( $avatar_url ),
1586	'profile_URL' => (string) esc_url_raw( $profile_url ),
1587	'ip_address' => $ip_address, // string\|bool.
1588	);
1589
1590	if ( $site_id > -1 ) {
1591	$author['site_ID'] = (int) $site_id;
1592	$author['site_visible'] = $site_visible ?? null;
1593	}
1594
1595	// Only include WordPress.com user data when author_wpcom_data is enabled.
1596	$args = $this->query_args();
1597
1598	if ( ! empty( $id ) && ! empty( $args['author_wpcom_data'] ) ) {
1599	if ( ( new Host() )->is_wpcom_simple() ) {
1600	$user = get_user_by( 'id', $id );
1601	$author['wpcom_id'] = isset( $user->ID ) ? (int) $user->ID : null;
1602	$author['wpcom_login'] = $user->user_login ?? '';
1603	} else {
1604	// If this is a Jetpack site, use the connection manager to get the user data.
1605	$wpcom_user_data = ( new Manager() )->get_connected_user_data( $id );
1606	if ( $wpcom_user_data && isset( $wpcom_user_data['ID'] ) ) {
1607	$author['wpcom_id'] = (int) $wpcom_user_data['ID'];
1608	$author['wpcom_login'] = $wpcom_user_data['login'] ?? '';
1609	}
1610	}
1611	}
1612
1613	return (object) $author;
1614	}
1615
1616	/**
1617	* Get a media item.
1618	*
1619	* @param int $media_id Media post ID.
1620	* @return object\|WP_Error Media item data, or WP_Error.
1621	*/
1622	public function get_media_item( $media_id ) {
1623	$media_item = get_post( $media_id );
1624
1625	if ( ! $media_item \|\| is_wp_error( $media_item ) ) {
1626	return new WP_Error( 'unknown_media', 'Unknown Media', 404 );
1627	}
1628
1629	$response = array(
1630	'id' => (string) $media_item->ID,
1631	'date' => (string) $this->format_date( $media_item->post_date_gmt, $media_item->post_date ),
1632	'parent' => $media_item->post_parent,
1633	'link' => wp_get_attachment_url( $media_item->ID ),
1634	'title' => $media_item->post_title,
1635	'caption' => $media_item->post_excerpt,
1636	'description' => $media_item->post_content,
1637	'metadata' => wp_get_attachment_metadata( $media_item->ID ),
1638	);
1639
1640	if ( defined( 'IS_WPCOM' ) && IS_WPCOM && is_array( $response['metadata'] ) && ! empty( $response['metadata']['file'] ) ) {
1641	remove_filter( '_wp_relative_upload_path', 'wpcom_wp_relative_upload_path', 10 );
1642	$response['metadata']['file'] = _wp_relative_upload_path( $response['metadata']['file'] );
1643	add_filter( '_wp_relative_upload_path', 'wpcom_wp_relative_upload_path', 10, 2 );
1644	}
1645
1646	$response['meta'] = (object) array(
1647	'links' => (object) array(
1648	'self' => (string) $this->links->get_media_link( $this->api->get_blog_id_for_output(), $media_id ),
1649	'help' => (string) $this->links->get_media_link( $this->api->get_blog_id_for_output(), $media_id, 'help' ),
1650	'site' => (string) $this->links->get_site_link( $this->api->get_blog_id_for_output() ),
1651	),
1652	);
1653
1654	return (object) $response;
1655	}
1656
1657	/**
1658	* Get a v1.1 media item.
1659	*
1660	* @param int $media_id Media post ID.
1661	* @param WP_Post\|null $media_item Media item.
1662	* @param string\|null $file File path.
1663	* @return object\|WP_Error Media item data, or WP_Error.
1664	*/
1665	public function get_media_item_v1_1( $media_id, $media_item = null, $file = null ) {
1666	if ( ! $media_item ) {
1667	$media_item = get_post( $media_id );
1668	}
1669
1670	if ( ! $media_item \|\| is_wp_error( $media_item ) ) {
1671	return new WP_Error( 'unknown_media', 'Unknown Media', 404 );
1672	}
1673
1674	$attachment_file = isset( $media_item->ID ) ? get_attached_file( $media_item->ID ) : null;
1675
1676	$file = basename( $attachment_file ? $attachment_file : $file );
1677	$file_info = pathinfo( $file );
1678	$ext = $file_info['extension'] ?? null;
1679
1680	// File operations are handled differently on WordPress.com.
1681	if ( defined( 'IS_WPCOM' ) && IS_WPCOM ) {
1682	$attachment_metadata = isset( $media_item->ID ) ? wp_get_attachment_metadata( $media_item->ID ) : array();
1683	$filesize = ! empty( $attachment_metadata['filesize'] ) ? $attachment_metadata['filesize'] : 0;
1684	} else {
1685	// For VideoPress videos, $attachment_file is the video URL.
1686	$filesize = ( $attachment_file && file_exists( $attachment_file ) )
1687	? filesize( $attachment_file )
1688	: 0;
1689	}
1690
1691	$response = array(
1692	'ID' => $media_item->ID ?? null,
1693	'URL' => isset( $media_item->ID ) ? wp_get_attachment_url( $media_item->ID ) : null,
1694	'guid' => $media_item->guid ?? null,
1695	'date' => ( isset( $media_item->post_date_gmt ) && isset( $media_item->post_date ) ) ?
1696	(string) $this->format_date( $media_item->post_date_gmt, $media_item->post_date ) : null,
1697	'post_ID' => $media_item->post_parent ?? null,
1698	'author_ID' => isset( $media_item->post_author ) ? (int) $media_item->post_author : null,
1699	'file' => $file,
1700	'mime_type' => $media_item->post_mime_type ?? null,
1701	'extension' => $ext,
1702	'title' => $media_item->post_title ?? '',
1703	'caption' => $media_item->post_excerpt ?? '',
1704	'description' => $media_item->post_content ?? '',
1705	'alt' => isset( $media_item->ID ) ? get_post_meta( $media_item->ID, '_wp_attachment_image_alt', true ) : '',
1706	'icon' => isset( $media_item->ID ) ? wp_mime_type_icon( $media_item->ID ) : null,
1707	'size' => size_format( (int) $filesize, 2 ),
1708	'thumbnails' => array(),
1709	);
1710
1711	if ( in_array( $ext, array( 'jpg', 'jpeg', 'png', 'gif', 'webp' ), true ) && isset( $media_item->ID ) ) {
1712	$metadata = wp_get_attachment_metadata( $media_item->ID );
1713	if ( isset( $metadata['height'] ) ) {
1714	$response['height'] = $metadata['height'];
1715	}
1716	if ( isset( $metadata['width'] ) ) {
1717	$response['width'] = $metadata['width'];
1718	}
1719
1720	if ( isset( $metadata['sizes'] ) ) {
1721	/**
1722	* Filter the thumbnail sizes available for each attachment ID.
1723	*
1724	* @module json-api
1725	*
1726	* @since 3.9.0
1727	*
1728	* @param array $metadata['sizes'] Array of thumbnail sizes available for a given attachment ID.
1729	* @param string $media_id Attachment ID.
1730	*/
1731	$sizes = apply_filters( 'rest_api_thumbnail_sizes', $metadata['sizes'], $media_item->ID );
1732	if ( is_array( $sizes ) ) {
1733	foreach ( $sizes as $size => $size_details ) {
1734	if ( isset( $size_details['file'] ) ) {
1735	$response['thumbnails'][ $size ] = dirname( $response['URL'] ) . '/' . $size_details['file'];
1736	}
1737	}
1738	/**
1739	* Filter the thumbnail URLs for attachment files.
1740	*
1741	* @module json-api
1742	*
1743	* @since 7.1.0
1744	*
1745	* @param array $metadata['sizes'] Array with thumbnail sizes as keys and URLs as values.
1746	*/
1747	$response['thumbnails'] = apply_filters( 'rest_api_thumbnail_size_urls', $response['thumbnails'] );
1748	}
1749	}
1750
1751	if ( isset( $metadata['image_meta'] ) ) {
1752	$response['exif'] = $metadata['image_meta'];
1753	}
1754	}
1755
1756	if ( in_array( $ext, array( 'mp3', 'm4a', 'wav', 'ogg' ), true ) && isset( $media_item->ID ) ) {
1757	$metadata = wp_get_attachment_metadata( $media_item->ID );
1758
1759	if ( isset( $metadata['length'] ) ) {
1760	$response['length'] = $metadata['length'];
1761	}
1762	$response['exif'] = is_array( $metadata ) ? $metadata : false;
1763	}
1764
1765	$is_video = false;
1766
1767	if (
1768	in_array( $ext, array( 'ogv', 'mp4', 'mov', 'wmv', 'avi', 'mpg', '3gp', '3g2', 'm4v' ), true )
1769	\|\| 'video/videopress' === $response['mime_type']
1770	) {
1771	$is_video = true;
1772	}
1773
1774	if ( $is_video && isset( $media_item->ID ) ) {
1775	$metadata = wp_get_attachment_metadata( $media_item->ID );
1776
1777	if ( isset( $metadata['height'] ) ) {
1778	$response['height'] = $metadata['height'];
1779	}
1780	if ( isset( $metadata['width'] ) ) {
1781	$response['width'] = $metadata['width'];
1782	}
1783
1784	if ( isset( $metadata['length'] ) ) {
1785	$response['length'] = $metadata['length'];
1786	}
1787
1788	if ( empty( $response['length'] ) && isset( $metadata['duration'] ) ) {
1789	$response['length'] = (int) $metadata['duration'];
1790	}
1791
1792	if ( empty( $response['length'] ) && isset( $metadata['videopress']['duration'] ) ) {
1793	$response['length'] = ceil( $metadata['videopress']['duration'] / 1000 );
1794	}
1795
1796	// add VideoPress info.
1797	if ( function_exists( 'video_get_info_by_blogpostid' ) ) {
1798	$info = video_get_info_by_blogpostid( $this->api->get_blog_id_for_output(), $media_item->ID );
1799
1800	// If we failed to get VideoPress info, but it exists in the meta data (for some reason)
1801	// then let's use that.
1802	if ( false === $info && isset( $metadata['videopress'] ) ) {
1803	$info = (object) $metadata['videopress'];
1804	}
1805
1806	if ( isset( $info->rating ) ) {
1807	$response['rating'] = $info->rating;
1808	}
1809
1810	if ( isset( $info->display_embed ) ) {
1811	$response['display_embed'] = (string) (int) $info->display_embed;
1812	// If not, default to metadata (for WPCOM).
1813	} elseif ( isset( $metadata['videopress']['display_embed'] ) ) {
1814	// We convert it to int then to string so that (bool) false to become "0".
1815	$response['display_embed'] = (string) (int) $metadata['videopress']['display_embed'];
1816	}
1817
1818	if ( isset( $info->allow_download ) ) {
1819	$response['allow_download'] = (string) (int) $info->allow_download;
1820	} elseif ( isset( $metadata['videopress']['allow_download'] ) ) {
1821	// We convert it to int then to string so that (bool) false to become "0".
1822	$response['allow_download'] = (string) (int) $metadata['videopress']['allow_download'];
1823	}
1824
1825	if ( isset( $info->thumbnail_generating ) ) {
1826	$response['thumbnail_generating'] = (bool) intval( $info->thumbnail_generating );
1827	} elseif ( isset( $metadata['videopress']['thumbnail_generating'] ) ) {
1828	$response['thumbnail_generating'] = (bool) intval( $metadata['videopress']['thumbnail_generating'] );
1829	}
1830
1831	if ( isset( $info->privacy_setting ) ) {
1832	$response['privacy_setting'] = (int) $info->privacy_setting;
1833	} elseif ( isset( $metadata['videopress']['privacy_setting'] ) ) {
1834	$response['privacy_setting'] = (int) $metadata['videopress']['privacy_setting'];
1835	}
1836
1837	$thumbnail_query_data = array();
1838	if ( ! empty( $info ) && function_exists( 'video_is_private' ) && video_is_private( $info ) ) {
1839	$thumbnail_query_data['metadata_token'] = video_generate_auth_token( $info );
1840	}
1841
1842	// Thumbnails.
1843	if ( function_exists( 'video_format_done' ) && function_exists( 'video_image_url_by_guid' ) ) {
1844	$response['thumbnails'] = array(
1845	'fmt_hd' => '',
1846	'fmt_dvd' => '',
1847	'fmt_std' => '',
1848	);
1849	foreach ( $response['thumbnails'] as $size => $thumbnail_url ) {
1850	if ( video_format_done( $info, $size ) ) {
1851	$response['thumbnails'][ $size ] = \add_query_arg( $thumbnail_query_data, \video_image_url_by_guid( $info->guid, $size ) );
1852	} else {
1853	unset( $response['thumbnails'][ $size ] );
1854	}
1855	}
1856	}
1857
1858	if ( isset( $info->title ) ) {
1859	$response['title'] = $info->title;
1860	}
1861
1862	// If we didn't get VideoPress information (for some reason) then let's
1863	// not try and include it in the response.
1864	if ( isset( $info->guid ) ) {
1865	$response['videopress_guid'] = $info->guid;
1866	$response['videopress_processing_done'] = isset( $info->finish_date_gmt ) && '0000-00-00 00:00:00' !== $info->finish_date_gmt;
1867	}
1868	}
1869	}
1870
1871	$response['thumbnails'] = (object) $response['thumbnails'];
1872
1873	$response['meta'] = (object) array(
1874	'links' => (object) array(
1875	'self' => isset( $media_item->ID ) ? (string) $this->links->get_media_link( $this->api->get_blog_id_for_output(), $media_item->ID ) : null,
1876	'help' => isset( $media_item->ID ) ? (string) $this->links->get_media_link( $this->api->get_blog_id_for_output(), $media_item->ID, 'help' ) : null,
1877	'site' => (string) $this->links->get_site_link( $this->api->get_blog_id_for_output() ),
1878	),
1879	);
1880
1881	// add VideoPress link to the meta.
1882	if ( isset( $response['videopress_guid'] ) ) {
1883	if ( function_exists( 'video_get_info_by_blogpostid' ) ) {
1884	$response['meta']->links->videopress = (string) $this->links->get_link( '/videos/%s', $response['videopress_guid'], '' );
1885	}
1886	}
1887
1888	if ( isset( $media_item->post_parent ) && $media_item->post_parent > 0 ) {
1889	$response['meta']->links->parent = (string) $this->links->get_post_link( $this->api->get_blog_id_for_output(), $media_item->post_parent );
1890	}
1891
1892	return (object) $response;
1893	}
1894
1895	/**
1896	* Get a formatted taxonomy.
1897	*
1898	* @param int $taxonomy_id Taxonomy ID.
1899	* @param string $taxonomy_type Name of taxonomy.
1900	* @param string $context Context, 'edit' or 'display'.
1901	* @return object\|WP_Error
1902	*/
1903	public function get_taxonomy( $taxonomy_id, $taxonomy_type, $context ) {
1904
1905	$taxonomy = get_term_by( 'slug', $taxonomy_id, $taxonomy_type );
1906	// keep updating this function.
1907	if ( ! $taxonomy \|\| is_wp_error( $taxonomy ) ) {
1908	return new WP_Error( 'unknown_taxonomy', 'Unknown taxonomy', 404 );
1909	}
1910
1911	return $this->format_taxonomy( $taxonomy, $taxonomy_type, $context );
1912	}
1913
1914	/**
1915	* Format a taxonomy.
1916	*
1917	* @param WP_Term $taxonomy Taxonomy.
1918	* @param string $taxonomy_type Name of taxonomy.
1919	* @param string $context Context, 'edit' or 'display'.
1920	* @return object\|WP_Error
1921	*/
1922	public function format_taxonomy( $taxonomy, $taxonomy_type, $context ) {
1923	// Permissions.
1924	switch ( $context ) {
1925	case 'edit':
1926	$tax = get_taxonomy( $taxonomy_type );
1927	if ( ! current_user_can( $tax->cap->edit_terms ) ) {
1928	return new WP_Error( 'unauthorized', 'User cannot edit taxonomy', 403 );
1929	}
1930	break;
1931	case 'display':
1932	if ( ( new Status() )->is_private_site() && ! current_user_can( 'read' ) ) {
1933	return new WP_Error( 'unauthorized', 'User cannot view taxonomy', 403 );
1934	}
1935	break;
1936	default:
1937	return new WP_Error( 'invalid_context', 'Invalid API CONTEXT', 400 );
1938	}
1939
1940	$response = array();
1941	$response['ID'] = (int) $taxonomy->term_id;
1942	$response['name'] = (string) $taxonomy->name;
1943	$response['slug'] = (string) $taxonomy->slug;
1944	$response['description'] = (string) $taxonomy->description;
1945	$response['post_count'] = (int) $taxonomy->count;
1946	$response['feed_url'] = get_term_feed_link( $taxonomy->term_id, $taxonomy_type );
1947
1948	if ( is_taxonomy_hierarchical( $taxonomy_type ) ) {
1949	$response['parent'] = (int) $taxonomy->parent;
1950	}
1951
1952	$response['meta'] = (object) array(
1953	'links' => (object) array(
1954	'self' => (string) $this->links->get_taxonomy_link( $this->api->get_blog_id_for_output(), $taxonomy->slug, $taxonomy_type ),
1955	'help' => (string) $this->links->get_taxonomy_link( $this->api->get_blog_id_for_output(), $taxonomy->slug, $taxonomy_type, 'help' ),
1956	'site' => (string) $this->links->get_site_link( $this->api->get_blog_id_for_output() ),
1957	),
1958	);
1959
1960	return (object) $response;
1961	}
1962
1963	/**
1964	* Returns ISO 8601 formatted datetime: 2011-12-08T01:15:36-08:00
1965	*
1966	* @param string $date_gmt GMT datetime string.
1967	* @param string $date Optional. Used to calculate the offset from GMT.
1968	* @return string
1969	*/
1970	public function format_date( $date_gmt, $date = null ) {
1971	return WPCOM_JSON_API_Date::format_date( $date_gmt, $date );
1972	}
1973
1974	/**
1975	* Parses a date string and returns the local and GMT representations
1976	* of that date & time in 'YYYY-MM-DD HH:MM:SS' format without
1977	* timezones or offsets. If the parsed datetime was not localized to a
1978	* particular timezone or offset we will assume it was given in GMT
1979	* relative to now and will convert it to local time using either the
1980	* timezone set in the options table for the blog or the GMT offset.
1981	*
1982	* @param string $date_string Date to parse.
1983	*
1984	* @return array{string,string} ( $local_time_string, $gmt_time_string )
1985	*/
1986	public function parse_date( $date_string ) {
1987	$date_string_info = date_parse( $date_string );
1988	if ( 0 === $date_string_info['error_count'] ) {
1989	// Check if it's already localized. Can't just check is_localtime because date_parse('oppossum') returns true; WTF, PHP.
1990	if ( isset( $date_string_info['zone'] ) && true === $date_string_info['is_localtime'] ) {
1991	$dt_utc = new DateTime( $date_string );
1992	$dt_local = clone $dt_utc;
1993	$dt_utc->setTimezone( new DateTimeZone( 'UTC' ) );
1994	return array(
1995	$dt_local->format( 'Y-m-d H:i:s' ),
1996	$dt_utc->format( 'Y-m-d H:i:s' ),
1997	);
1998	}
1999
2000	// It's parseable but no TZ info so assume UTC.
2001	$dt_utc = new DateTime( $date_string, new DateTimeZone( 'UTC' ) );
2002	$dt_local = clone $dt_utc;
2003	} else {
2004	// Could not parse time, use now in UTC.
2005	$dt_utc = new DateTime( 'now', new DateTimeZone( 'UTC' ) );
2006	$dt_local = clone $dt_utc;
2007	}
2008
2009	$dt_local->setTimezone( wp_timezone() );
2010
2011	return array(
2012	$dt_local->format( 'Y-m-d H:i:s' ),
2013	$dt_utc->format( 'Y-m-d H:i:s' ),
2014	);
2015	}
2016
2017	/**
2018	* Load the functions.php file for the current theme to get its post formats, CPTs, etc.
2019	*/
2020	public function load_theme_functions() {
2021	if ( ! defined( 'STYLESHEETPATH' ) ) {
2022	wp_templating_constants();
2023	}
2024
2025	// bail if we've done this already (can happen when calling /batch endpoint).
2026	if ( defined( 'REST_API_THEME_FUNCTIONS_LOADED' ) ) {
2027	return;
2028	}
2029
2030	// VIP context loading is handled elsewhere, so bail to prevent
2031	// duplicate loading. See `switch_to_blog_and_validate_user()`.
2032	if ( defined( 'WPCOM_IS_VIP_ENV' ) && WPCOM_IS_VIP_ENV ) {
2033	return;
2034	}
2035
2036	$do_check_theme =
2037	defined( 'REST_API_TEST_REQUEST' ) && REST_API_TEST_REQUEST \|\|
2038	defined( 'IS_WPCOM' ) && IS_WPCOM;
2039
2040	if ( $do_check_theme && ! wpcom_should_load_theme_files_on_rest_api() ) {
2041	return;
2042	}
2043
2044	define( 'REST_API_THEME_FUNCTIONS_LOADED', true );
2045
2046	// the theme info we care about is found either within functions.php or one of the jetpack files.
2047	$function_files = array( '/functions.php', '/inc/jetpack.compat.php', '/inc/jetpack.php', '/includes/jetpack.compat.php' );
2048
2049	$copy_dirs = array( get_template_directory() );
2050
2051	// Is this a child theme? Load the child theme's functions file.
2052	if ( get_stylesheet_directory() !== get_template_directory() && wpcom_is_child_theme() ) {
2053	foreach ( $function_files as $function_file ) {
2054	if ( file_exists( get_stylesheet_directory() . $function_file ) ) {
2055	require_once get_stylesheet_directory() . $function_file;
2056	}
2057	}
2058	$copy_dirs[] = get_stylesheet_directory();
2059	}
2060
2061	foreach ( $function_files as $function_file ) {
2062	if ( file_exists( get_template_directory() . $function_file ) ) {
2063	require_once get_template_directory() . $function_file;
2064	}
2065	}
2066
2067	// add inc/wpcom.php and/or includes/wpcom.php.
2068	wpcom_load_theme_compat_file();
2069
2070	// Enable including additional directories or files in actions to be copied.
2071	$copy_dirs = apply_filters( 'restapi_theme_action_copy_dirs', $copy_dirs );
2072
2073	// since the stuff we care about (CPTS, post formats, are usually on setup or init hooks, we want to load those).
2074	$this->copy_hooks( 'after_setup_theme', 'restapi_theme_after_setup_theme', $copy_dirs );
2075
2076	/**
2077	* Fires functions hooked onto `after_setup_theme` by the theme for the purpose of the REST API.
2078	*
2079	* The REST API does not load the theme when processing requests.
2080	* To enable theme-based functionality, the API will load the '/functions.php',
2081	* '/inc/jetpack.compat.php', '/inc/jetpack.php', '/includes/jetpack.compat.php files
2082	* of the theme (parent and child) and copy functions hooked onto 'after_setup_theme' within those files.
2083	*
2084	* @module json-api
2085	*
2086	* @since 3.2.0
2087	*/
2088	do_action( 'restapi_theme_after_setup_theme' );
2089	$this->copy_hooks( 'init', 'restapi_theme_init', $copy_dirs );
2090
2091	/**
2092	* Fires functions hooked onto `init` by the theme for the purpose of the REST API.
2093	*
2094	* The REST API does not load the theme when processing requests.
2095	* To enable theme-based functionality, the API will load the '/functions.php',
2096	* '/inc/jetpack.compat.php', '/inc/jetpack.php', '/includes/jetpack.compat.php files
2097	* of the theme (parent and child) and copy functions hooked onto 'init' within those files.
2098	*
2099	* @module json-api
2100	*
2101	* @since 3.2.0
2102	*/
2103	do_action( 'restapi_theme_init' );
2104	}
2105
2106	/**
2107	* Copy hook functions.
2108	*
2109	* @param string $from_hook Hook to copy from.
2110	* @param string $to_hook Hook to copy to.
2111	* @param array $base_paths Only copy hooks defined in the specified paths.
2112	*/
2113	public function copy_hooks( $from_hook, $to_hook, $base_paths ) {
2114	global $wp_filter;
2115	foreach ( $wp_filter as $hook => $actions ) {
2116
2117	if ( $from_hook !== $hook ) {
2118	continue;
2119	}
2120	if ( ! has_action( $hook ) ) {
2121	continue;
2122	}
2123
2124	foreach ( $actions as $priority => $callbacks ) {
2125	foreach ( $callbacks as $callback_data ) {
2126	$callback = $callback_data['function'];
2127
2128	// use reflection api to determine filename where function is defined.
2129	$reflection = $this->get_reflection( $callback );
2130
2131	if ( false !== $reflection ) {
2132	$file_name = $reflection->getFileName();
2133	foreach ( $base_paths as $base_path ) {
2134
2135	// only copy hooks with functions which are part of the specified files.
2136	if ( str_starts_with( $file_name, $base_path ) ) {
2137	add_action(
2138	$to_hook,
2139	$callback_data['function'],
2140	$priority,
2141	$callback_data['accepted_args']
2142	);
2143	}
2144	}
2145	}
2146	}
2147	}
2148	}
2149	}
2150
2151	/**
2152	* Get a ReflectionMethod or ReflectionFunction for the callback.
2153	*
2154	* @param callable $callback Callback.
2155	* @return ReflectionMethod\|ReflectionFunction\|false
2156	*/
2157	public function get_reflection( $callback ) {
2158	if ( is_array( $callback ) ) {
2159	list( $class, $method ) = $callback;
2160	return new ReflectionMethod( $class, $method );
2161	}
2162
2163	if ( is_string( $callback ) && strpos( $callback, '::' ) !== false ) {
2164	list( $class, $method ) = explode( '::', $callback );
2165	return new ReflectionMethod( $class, $method );
2166	}
2167
2168	if ( method_exists( $callback, '__invoke' ) ) {
2169	return new ReflectionMethod( $callback, '__invoke' );
2170	}
2171
2172	if ( is_string( $callback ) && strpos( $callback, '::' ) === false && function_exists( $callback ) ) {
2173	return new ReflectionFunction( $callback );
2174	}
2175
2176	return false;
2177	}
2178
2179	/**
2180	* Check whether a user can view or edit a post type.
2181	*
2182	* @param string $post_type post type to check.
2183	* @param string $context 'display' or 'edit'.
2184	* @return bool
2185	*/
2186	public function current_user_can_access_post_type( $post_type, $context = 'display' ) {
2187	$post_type_object = get_post_type_object( $post_type );
2188	if ( ! $post_type_object ) {
2189	return false;
2190	}
2191
2192	switch ( $context ) {
2193	case 'edit':
2194	return current_user_can( $post_type_object->cap->edit_posts );
2195	case 'display':
2196	return $post_type_object->public \|\| current_user_can( $post_type_object->cap->read_private_posts );
2197	default:
2198	return false;
2199	}
2200	}
2201
2202	/**
2203	* Is the post type allowed?
2204	*
2205	* @param string $post_type Post type.
2206	* @return bool
2207	*/
2208	public function is_post_type_allowed( $post_type ) {
2209	// if the post type is empty, that's fine, WordPress will default to post.
2210	if ( empty( $post_type ) ) {
2211	return true;
2212	}
2213
2214	// allow special 'any' type.
2215	if ( 'any' === $post_type ) {
2216	return true;
2217	}
2218
2219	// check for allowed types.
2220	if ( in_array( $post_type, $this->_get_whitelisted_post_types(), true ) ) {
2221	return true;
2222	}
2223
2224	$post_type_object = get_post_type_object( $post_type );
2225	if ( $post_type_object ) {
2226	if ( ! empty( $post_type_object->show_in_rest ) ) {
2227	return $post_type_object->show_in_rest;
2228	}
2229	if ( ! empty( $post_type_object->publicly_queryable ) ) {
2230	return $post_type_object->publicly_queryable;
2231	}
2232	}
2233
2234	return ! empty( $post_type_object->public );
2235	}
2236
2237	/**
2238	* Gets the whitelisted post types that JP should allow access to.
2239	*
2240	* @return array Whitelisted post types.
2241	*/
2242	protected function _get_whitelisted_post_types() { // phpcs:ignore PSR2.Methods.MethodDeclaration.Underscore -- Legacy.
2243	$allowed_types = array( 'post', 'page', 'revision' );
2244
2245	/**
2246	* Filter the post types Jetpack has access to, and can synchronize with WordPress.com.
2247	*
2248	* @module json-api
2249	*
2250	* @since 2.2.3
2251	*
2252	* @param array $allowed_types Array of whitelisted post types. Default to `array( 'post', 'page', 'revision' )`.
2253	*/
2254	$allowed_types = apply_filters( 'rest_api_allowed_post_types', $allowed_types );
2255
2256	return array_unique( $allowed_types );
2257	}
2258
2259	/**
2260	* Mobile apps are allowed free video uploads, but limited to 5 minutes in length.
2261	*
2262	* @param array $media_item the media item to evaluate.
2263	*
2264	* @return bool true if the media item is a video that was uploaded via the mobile
2265	* app that is longer than 5 minutes.
2266	*/
2267	public function media_item_is_free_video_mobile_upload_and_too_long( $media_item ) {
2268	if ( ! $media_item ) {
2269	return false;
2270	}
2271
2272	// Verify file is a video.
2273	$is_video = preg_match( '@^video/@', $media_item['type'] );
2274	if ( ! $is_video ) {
2275	return false;
2276	}
2277
2278	// Check if the request is from a mobile app, where we allow free video uploads at limited length.
2279	if ( ! in_array( $this->api->token_details['client_id'], VIDEOPRESS_ALLOWED_REST_API_CLIENT_IDS, true ) ) {
2280	return false;
2281	}
2282
2283	// We're only worried about free sites.
2284	require_once WP_CONTENT_DIR . '/admin-plugins/wpcom-billing.php';
2285	$current_plan = WPCOM_Store_API::get_current_plan( get_current_blog_id() );
2286	if ( ! $current_plan['is_free'] ) {
2287	return false;
2288	}
2289
2290	// We don't know if this is an upload or a sideload, but in either case the tmp_name should be a path, not a URL.
2291	if ( wp_parse_url( $media_item['tmp_name'], PHP_URL_SCHEME ) !== null ) {
2292	return false;
2293	}
2294
2295	// Check if video is longer than 5 minutes.
2296	$video_meta = wp_read_video_metadata( $media_item['tmp_name'] );
2297	if (
2298	false !== $video_meta &&
2299	isset( $video_meta['length'] ) &&
2300	5 * MINUTE_IN_SECONDS < $video_meta['length']
2301	) {
2302	videopress_log(
2303	'videopress_app_upload_length_block',
2304	'Mobile app upload on free site blocked because length was longer than 5 minutes.',
2305	null,
2306	null,
2307	null,
2308	null,
2309	array(
2310	'blog_id' => get_current_blog_id(),
2311	'user_id' => get_current_user_id(),
2312	)
2313	);
2314	return true;
2315	}
2316
2317	return false;
2318	}
2319
2320	/**
2321	* Handle a v1.1 media creation.
2322	*
2323	* Only one of $media_files and $media_urls should be non-empty.
2324	*
2325	* @param array $media_files File upload data.
2326	* @param array $media_urls URLs to fetch.
2327	* @param array $media_attrs Attributes corresponding to each entry in `$media_files`/`$media_urls`.
2328	* @param int\|false $force_parent_id Force the parent ID, overriding `$media_attrs[]['parent_id']`.
2329	* @return array Two items:
2330	* - media_ids: IDs created, by index in `$media_files`/`$media_urls`.
2331	* - errors: Errors encountered, by index in `$media_files`/`$media_urls`.
2332	*/
2333	public function handle_media_creation_v1_1( $media_files, $media_urls, $media_attrs = array(), $force_parent_id = false ) {
2334
2335	add_filter( 'upload_mimes', array( $this, 'allow_video_uploads' ) );
2336
2337	$media_ids = array();
2338	$errors = array();
2339	$user_can_upload_files = current_user_can( 'upload_files' ) \|\| $this->api->is_authorized_with_upload_token();
2340	$media_attrs = array_values( $media_attrs ); // reset the keys.
2341	$i = 0;
2342
2343	if ( ! empty( $media_files ) ) {
2344	$this->api->trap_wp_die( 'upload_error' );
2345	foreach ( $media_files as $media_item ) {
2346	$_FILES['.api.media.item.'] = $media_item;
2347
2348	if ( ! $user_can_upload_files ) {
2349	$media_id = new WP_Error( 'unauthorized', 'User cannot upload media.', 403 );
2350	} elseif ( ! is_array( $media_item ) ) {
2351	$media_id = new WP_Error( 'invalid_input', 'Unable to process request.', 400 );
2352	$media_item = array(
2353	'name' => 'invalid_file',
2354	);
2355	} elseif ( $this->media_item_is_free_video_mobile_upload_and_too_long( $media_item ) ) {
2356	$media_id = new WP_Error( 'upload_video_length', 'Video uploads longer than 5 minutes require a paid plan.', 400 );
2357	} else {
2358	if ( $force_parent_id ) {
2359	$parent_id = absint( $force_parent_id );
2360	} elseif ( ! empty( $media_attrs[ $i ] ) && ! empty( $media_attrs[ $i ]['parent_id'] ) ) {
2361	$parent_id = absint( $media_attrs[ $i ]['parent_id'] );
2362	} else {
2363	$parent_id = 0;
2364	}
2365	$media_id = media_handle_upload( '.api.media.item.', $parent_id );
2366	}
2367	if ( is_wp_error( $media_id ) ) {
2368	$errors[ $i ]['file'] = $media_item['name'];
2369	$errors[ $i ]['error'] = $media_id->get_error_code();
2370	$errors[ $i ]['message'] = $media_id->get_error_message();
2371	} else {
2372	$media_ids[ $i ] = $media_id;
2373	}
2374
2375	++$i;
2376	}
2377	$this->api->trap_wp_die( null );
2378	unset( $_FILES['.api.media.item.'] );
2379	}
2380
2381	if ( ! empty( $media_urls ) ) {
2382	foreach ( $media_urls as $url ) {
2383	if ( ! $user_can_upload_files ) {
2384	$media_id = new WP_Error( 'unauthorized', 'User cannot upload media.', 403 );
2385	} else {
2386	if ( $force_parent_id ) {
2387	$parent_id = absint( $force_parent_id );
2388	} elseif ( ! empty( $media_attrs[ $i ] ) && ! empty( $media_attrs[ $i ]['parent_id'] ) ) {
2389	$parent_id = absint( $media_attrs[ $i ]['parent_id'] );
2390	} else {
2391	$parent_id = 0;
2392	}
2393	$media_id = $this->handle_media_sideload( $url, $parent_id );
2394	}
2395	if ( is_wp_error( $media_id ) ) {
2396	$errors[ $i ] = array(
2397	'file' => $url,
2398	'error' => $media_id->get_error_code(),
2399	'message' => $media_id->get_error_message(),
2400	);
2401	} elseif ( ! empty( $media_id ) ) {
2402	$media_ids[ $i ] = $media_id;
2403	}
2404
2405	++$i;
2406	}
2407	}
2408
2409	if ( ! empty( $media_attrs ) ) {
2410	foreach ( $media_ids as $index => $media_id ) {
2411	if ( empty( $media_attrs[ $index ] ) ) {
2412	continue;
2413	}
2414
2415	$attrs = $media_attrs[ $index ];
2416	$insert = array();
2417
2418	// Attributes: Title, Caption, Description.
2419
2420	if ( isset( $attrs['title'] ) ) {
2421	$insert['post_title'] = $attrs['title'];
2422	}
2423
2424	if ( isset( $attrs['caption'] ) ) {
2425	$insert['post_excerpt'] = $attrs['caption'];
2426	}
2427
2428	if ( isset( $attrs['description'] ) ) {
2429	$insert['post_content'] = $attrs['description'];
2430	}
2431
2432	if ( ! empty( $insert ) ) {
2433	$insert['ID'] = $media_id;
2434	wp_update_post( (object) $insert );
2435	}
2436
2437	// Attributes: Alt.
2438
2439	if ( isset( $attrs['alt'] ) ) {
2440	$alt = wp_strip_all_tags( $attrs['alt'], true );
2441	update_post_meta( $media_id, '_wp_attachment_image_alt', $alt );
2442	}
2443
2444	// Attributes: Artist, Album.
2445
2446	$id3_meta = array();
2447
2448	foreach ( array( 'artist', 'album' ) as $key ) {
2449	if ( isset( $attrs[ $key ] ) ) {
2450	$id3_meta[ $key ] = wp_strip_all_tags( $attrs[ $key ], true );
2451	}
2452	}
2453
2454	if ( ! empty( $id3_meta ) ) {
2455	// Before updating metadata, ensure that the item is audio.
2456	$item = $this->get_media_item_v1_1( $media_id );
2457	if ( str_starts_with( $item->mime_type, 'audio/' ) ) {
2458	wp_update_attachment_metadata( $media_id, $id3_meta );
2459	}
2460	}
2461
2462	// Attributes: Meta
2463	if ( isset( $attrs['meta'] ) && isset( $attrs['meta']['vertical_id'] ) ) {
2464	update_post_meta( $media_id, 'vertical_id', $attrs['meta']['vertical_id'] );
2465	}
2466	}
2467	}
2468
2469	return array(
2470	'media_ids' => $media_ids,
2471	'errors' => $errors,
2472	);
2473	}
2474
2475	/**
2476	* Handle a media sideload.
2477	*
2478	* @param string $url URL.
2479	* @param int $parent_post_id Parent post ID.
2480	* @param string $type Type.
2481	* @return int\|WP_Error\|false Media post ID, or error, or false if nothing was sideloaded.
2482	*/
2483	public function handle_media_sideload( $url, $parent_post_id = 0, $type = 'any' ) {
2484	if ( ! function_exists( 'download_url' ) \|\| ! function_exists( 'media_handle_sideload' ) ) {
2485	return false;
2486	}
2487
2488	// if we didn't get a URL, let's bail.
2489	$parsed = wp_parse_url( $url );
2490	if ( empty( $parsed ) ) {
2491	return false;
2492	}
2493
2494	$tmp = download_url( $url );
2495	if ( is_wp_error( $tmp ) ) {
2496	return $tmp;
2497	}
2498
2499	// First check to see if we get a mime-type match by file, otherwise, check to
2500	// see if WordPress supports this file as an image. If neither, then it is not supported.
2501	if ( ! $this->is_file_supported_for_sideloading( $tmp ) \|\| 'image' === $type && ! file_is_displayable_image( $tmp ) ) {
2502	@unlink( $tmp ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
2503	return new WP_Error( 'invalid_input', 'Invalid file type.', 403 );
2504	}
2505
2506	// emulate a $_FILES entry.
2507	$file_array = array(
2508	'name' => basename( wp_parse_url( $url, PHP_URL_PATH ) ),
2509	'tmp_name' => $tmp,
2510	);
2511
2512	$id = media_handle_sideload( $file_array, $parent_post_id );
2513	if ( file_exists( $tmp ) ) {
2514	@unlink( $tmp ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
2515	}
2516
2517	if ( is_wp_error( $id ) ) {
2518	return $id;
2519	}
2520
2521	if ( ! $id \|\| ! is_int( $id ) ) {
2522	return false;
2523	}
2524
2525	return $id;
2526	}
2527
2528	/**
2529	* Checks that the mime type of the specified file is among those in a filterable list of mime types.
2530	*
2531	* @param string $file Path to file to get its mime type.
2532	*
2533	* @return bool
2534	*/
2535	protected function is_file_supported_for_sideloading( $file ) {
2536	return jetpack_is_file_supported_for_sideloading( $file );
2537	}
2538
2539	/**
2540	* Filter for `upload_mimes`.
2541	*
2542	* @param array $mimes Allowed mime types.
2543	* @return array Allowed mime types.
2544	*/
2545	public function allow_video_uploads( $mimes ) {
2546	// if we are on Jetpack, bail - Videos are already allowed.
2547	if ( ! defined( 'IS_WPCOM' ) \|\| ! IS_WPCOM ) {
2548	return $mimes;
2549	}
2550
2551	// extra check that this filter is only ever applied during REST API requests.
2552	if ( ! defined( 'REST_API_REQUEST' ) \|\| ! REST_API_REQUEST ) {
2553	return $mimes;
2554	}
2555
2556	// bail early if they already have video upload capability.
2557	if ( wpcom_site_can_upload_videos() ) {
2558	return $mimes;
2559	}
2560
2561	// lets whitelist to only specific clients right now.
2562	$clients_allowed_video_uploads = array();
2563	/**
2564	* Filter the list of whitelisted video clients.
2565	*
2566	* @module json-api
2567	*
2568	* @since 3.2.0
2569	*
2570	* @param array $clients_allowed_video_uploads Array of whitelisted Video clients.
2571	*/
2572	$clients_allowed_video_uploads = apply_filters( 'rest_api_clients_allowed_video_uploads', $clients_allowed_video_uploads );
2573	if ( ! isset( $this->api->token_details['client_id'] ) \|\| ! in_array( $this->api->token_details['client_id'], $clients_allowed_video_uploads, true ) ) {
2574	return $mimes;
2575	}
2576
2577	$mime_list = wp_get_mime_types();
2578
2579	$video_exts = explode( ' ', get_site_option( 'video_upload_filetypes', false, false ) );
2580	/**
2581	* Filter the video filetypes allowed on the site.
2582	*
2583	* @module json-api
2584	*
2585	* @since 3.2.0
2586	*
2587	* @param array $video_exts Array of video filetypes allowed on the site.
2588	*/
2589	$video_exts = apply_filters( 'video_upload_filetypes', $video_exts );
2590	$video_mimes = array();
2591
2592	if ( ! empty( $video_exts ) ) {
2593	foreach ( $video_exts as $ext ) {
2594	foreach ( $mime_list as $ext_pattern => $mime ) {
2595	if ( '' !== $ext && str_contains( $ext_pattern, $ext ) ) {
2596	$video_mimes[ $ext_pattern ] = $mime;
2597	}
2598	}
2599	}
2600
2601	$mimes = array_merge( $mimes, $video_mimes );
2602	}
2603
2604	return $mimes;
2605	}
2606
2607	/**
2608	* Is the current site multi-user?
2609	*
2610	* @return bool
2611	*/
2612	public function is_current_site_multi_user() {
2613	$users = wp_cache_get( 'site_user_count', 'WPCOM_JSON_API_Endpoint' );
2614	if ( false === $users ) {
2615	$user_query = new WP_User_Query(
2616	array(
2617	'blog_id' => get_current_blog_id(),
2618	'fields' => 'ID',
2619	)
2620	);
2621	$users = (int) $user_query->get_total();
2622	wp_cache_set( 'site_user_count', $users, 'WPCOM_JSON_API_Endpoint', DAY_IN_SECONDS );
2623	}
2624	return $users > 1;
2625	}
2626
2627	/**
2628	* Whether cross-origin requests are allowed.
2629	*
2630	* @return bool
2631	*/
2632	public function allows_cross_origin_requests() {
2633	return 'GET' === $this->method \|\| $this->allow_cross_origin_request;
2634	}
2635
2636	/**
2637	* Whether unauthorized requests are allowed.
2638	*
2639	* @param string $origin Origin.
2640	* @param string[] $complete_access_origins Access origins.
2641	* @return bool
2642	*/
2643	public function allows_unauthorized_requests( $origin, $complete_access_origins ) {
2644	return 'GET' === $this->method \|\| ( $this->allow_unauthorized_request && in_array( $origin, $complete_access_origins, true ) );
2645	}
2646
2647	/**
2648	* Whether this endpoint accepts site based authentication for the current request.
2649	*
2650	* @since 9.1.0
2651	*
2652	* @return bool true, if Jetpack blog token is used and `allow_jetpack_site_auth` is true,
2653	* false otherwise.
2654	*/
2655	public function accepts_site_based_authentication() {
2656	return $this->allow_jetpack_site_auth &&
2657	$this->api->is_jetpack_authorized_for_site();
2658	}
2659
2660	/**
2661	* Get platform.
2662	*
2663	* @return WPORG_Platform
2664	*/
2665	public function get_platform() {
2666	return wpcom_get_sal_platform( $this->api->token_details );
2667	}
2668
2669	/**
2670	* Allows the endpoint to perform logic to allow it to decide whether-or-not it should force a
2671	* response from the WPCOM API, or potentially go to the Jetpack blog.
2672	*
2673	* Override this method if you want to do something different.
2674	*
2675	* @param int $blog_id Blog ID.
2676	* @return bool
2677	*/
2678	public function force_wpcom_request( $blog_id ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
2679	return false;
2680	}
2681
2682	/**
2683	* Get an array of all valid AMP origins for a blog's siteurl.
2684	*
2685	* @param string $siteurl Origin url of the API request.
2686	* @return array
2687	*/
2688	public function get_amp_cache_origins( $siteurl ) {
2689	$host = wp_parse_url( $siteurl, PHP_URL_HOST );
2690
2691	/*
2692	* From AMP docs:
2693	* "When possible, the Google AMP Cache will create a subdomain for each AMP document's domain by first converting it
2694	* from IDN (punycode) to UTF-8. The caches replaces every - (dash) with -- (2 dashes) and replace every . (dot) with
2695	* - (dash). For example, pub.com will map to pub-com.cdn.ampproject.org."
2696	*/
2697	if ( function_exists( 'idn_to_utf8' ) ) {
2698	// The third parameter is set explicitly to prevent issues with newer PHP versions compiled with an old ICU version.
2699	$variant = defined( 'INTL_IDNA_VARIANT_UTS46' )
2700	? INTL_IDNA_VARIANT_UTS46
2701	// phpcs:ignore PHPCompatibility.Constants.RemovedConstants.intl_idna_variant_2003Deprecated, PHPCompatibility.Constants.RemovedConstants.intl_idna_variant_2003DeprecatedRemoved
2702	: INTL_IDNA_VARIANT_2003; // @phan-suppress-current-line PhanUndeclaredConstant
2703	$host = idn_to_utf8( $host, IDNA_DEFAULT, $variant );
2704	}
2705	$subdomain = str_replace( array( '-', '.' ), array( '--', '-' ), $host );
2706	return array(
2707	$siteurl,
2708	// Google AMP Cache (legacy).
2709	'https://cdn.ampproject.org',
2710	// Google AMP Cache subdomain.
2711	sprintf( 'https://%s.cdn.ampproject.org', $subdomain ),
2712	// Cloudflare AMP Cache.
2713	sprintf( 'https://%s.amp.cloudflare.com', $subdomain ),
2714	// Bing AMP Cache.
2715	sprintf( 'https://%s.bing-amp.com', $subdomain ),
2716	);
2717	}
2718
2719	/**
2720	* Register a REST route for this jsonAPI endpoint.
2721	*
2722	* @return void
2723	* @throws Exception The exception if something goes wrong.
2724	*/
2725	public function create_rest_route_for_endpoint() {
2726	register_rest_route(
2727	static::REST_NAMESPACE,
2728	$this->build_rest_route(),
2729	array(
2730	'methods' => $this->method,
2731	'callback' => array( $this, 'rest_callback' ),
2732	'permission_callback' => array( $this, 'rest_permission_callback' ),
2733	)
2734	);
2735	}
2736
2737	/**
2738	* Handle the rest call.
2739	*
2740	* @param WP_REST_Request $request The request object.
2741	*
2742	* @return mixed\|WP_Error
2743	*/
2744	public function rest_callback( WP_REST_Request $request ) {
2745	// phpcs:ignore WordPress.PHP.IniSet.display_errors_Disallowed -- Making sure random warnings don't break JSON.
2746	ini_set( 'display_errors', false );
2747
2748	$blog_id = Jetpack_Options::get_option( 'id' );
2749
2750	add_filter( 'user_can_richedit', '__return_true' );
2751	add_filter( 'comment_edit_pre', array( $this->api, 'comment_edit_pre' ) );
2752
2753	$this->api->initialize();
2754	$this->api->endpoint = $this;
2755
2756	$this->api->path = $this->path;
2757	$this->api->version = $this->max_version;
2758
2759	$locale = $request->get_param( 'language' );
2760	if ( $locale ) {
2761	$this->api->init_locale( $locale );
2762	}
2763
2764	if ( $this->in_testing && ! WPCOM_JSON_API__DEBUG ) {
2765	return new WP_Error( 'endpoint_not_available' );
2766	}
2767
2768	$token_data = ( new Manager() )->verify_xml_rpc_signature();
2769	if ( ! $token_data \|\| empty( $token_data['token_key'] ) \|\| ! array_key_exists( 'user_id', $token_data ) ) {
2770	return new WP_Error( 'response_signature_error' );
2771	}
2772
2773	$token = ( new Tokens() )->get_access_token( $token_data['user_id'], $token_data['token_key'] );
2774	if ( is_wp_error( $token ) ) {
2775	return $token;
2776	}
2777	if ( ! $token ) {
2778	return new WP_Error( 'response_signature_error' );
2779	}
2780
2781	/** This action is documented in class.json-api.php */
2782	do_action( 'wpcom_json_api_output', $this->stat );
2783
2784	$response = call_user_func_array(
2785	array( $this, 'callback' ),
2786	array_values( array( $this->path, $blog_id ) + $request->get_url_params() )
2787	);
2788
2789	if ( ! $response && ! is_array( $response ) ) {
2790	// Dealing with empty non-array response.
2791	$response = new WP_Error( 'empty_response', 'Endpoint response is empty', 500 );
2792	}
2793
2794	// Mirror the XML-RPC path, which runs filter_fields() in WPCOM_JSON_API::output() before
2795	// returning, so a `fields` request yields the same keys on both transports. Endpoints may
2796	// force-add keys past `fields` for internal processors (e.g. the post type/status/password);
2797	// without this they would leak on the REST transport only.
2798	if ( ! is_wp_error( $response ) ) {
2799	$response = $this->api->filter_fields( $response );
2800	}
2801
2802	$status_code = 200;
2803
2804	if ( is_wp_error( $response ) ) {
2805	$status_code = 500;
2806
2807	if ( $response->get_error_data() && is_scalar( $response->get_error_data() )
2808	&& (string) (int) $response->get_error_data() === (string) $response->get_error_data()
2809	) {
2810	$status_code = (int) $response->get_error_data();
2811	}
2812
2813	$response = WPCOM_JSON_API::serializable_error( $response );
2814	}
2815
2816	if ( $request->get_param( 'http_envelope' ) ) {
2817	$response = WPCOM_JSON_API::wrap_http_envelope( $status_code, $response, 'application/json' );
2818	}
2819
2820	$response = wp_json_encode( $response, JSON_UNESCAPED_SLASHES );
2821
2822	$nonce = wp_generate_password( 10, false );
2823	$hmac = hash_hmac( 'sha1', $nonce . $response, $token->secret );
2824
2825	return array(
2826	$response,
2827	(string) $nonce,
2828	$hmac,
2829	);
2830	}
2831
2832	/**
2833	* The REST endpoint should only be available for requests signed with a valid blog or user token.
2834	* Declaring it "final" so individual endpoints couldn't remove this requirement.
2835	*
2836	* If you need to add custom permissions to individual endpoints, you can override method `rest_permission_callback_custom()`.
2837	*
2838	* @see self::rest_permission_callback_custom()
2839	*
2840	* @return true\|WP_Error
2841	*/
2842	final public function rest_permission_callback() {
2843	$manager = new Manager( 'jetpack' );
2844	if ( ! $manager->is_connected() ) {
2845	return new WP_Error( 'site_not_connected' );
2846	}
2847
2848	if ( ( ( $this->allow_jetpack_site_auth \|\| $this->allow_fallback_to_jetpack_blog_token ) && Rest_Authentication::is_signed_with_blog_token() )
2849	\|\| ( get_current_user_id() && Rest_Authentication::is_signed_with_user_token() )
2850	) {
2851	$custom_permission_result = $this->rest_permission_callback_custom();
2852
2853	// Successful custom permission check.
2854	if ( $custom_permission_result === true ) {
2855	return true;
2856	}
2857
2858	// Custom permission check errored, returning the error.
2859	if ( is_wp_error( $custom_permission_result ) ) {
2860	return $custom_permission_result;
2861	}
2862
2863	// Custom permission check failed, but didn't return a specific error. Proceed to returning the generic error.
2864	}
2865
2866	$message = esc_html__(
2867	'You do not have the correct user permissions to perform this action. Please contact your site admin if you think this is a mistake.',
2868	'jetpack'
2869	);
2870	return new WP_Error( 'rest_api_invalid_permission', $message, array( 'status' => rest_authorization_required_code() ) );
2871	}
2872
2873	/**
2874	* You can override this method in individual endpoints to add custom permission checks.
2875	* This will run on top of `rest_permission_callback()`.
2876	*
2877	* @see self::rest_permission_callback()
2878	*
2879	* @return true\|WP_Error
2880	*/
2881	public function rest_permission_callback_custom() {
2882	return true;
2883	}
2884
2885	/**
2886	* Build the REST endpoint URL.
2887	*
2888	* @return string
2889	*/
2890	public function build_rest_route() {
2891	$version_prefix = $this->max_version ? 'v' . $this->max_version : '';
2892	return $version_prefix . $this->rest_route;
2893	}
2894
2895	/**
2896	* Get Jetpack Version where support for the endpoint was introduced.
2897	*
2898	* @return string
2899	*/
2900	public function get_rest_min_jp_version() {
2901	return $this->rest_min_jp_version;
2902	}
2903
2904	/**
2905	* Return endpoint response
2906	*
2907	* @param string $path ... determined by ->$path.
2908	*
2909	* @return array\|WP_Error
2910	* falsy: HTTP 500, no response body
2911	* WP_Error( $error_code, $error_message, $http_status_code ): HTTP $status_code, json_encode( array( 'error' => $error_code, 'message' => $error_message ) ) response body
2912	* $data: HTTP 200, json_encode( $data ) response body
2913	*/
2914	abstract public function callback( $path = '' );
2915	}
2916
2917	require_once __DIR__ . '/json-endpoints.php';
2918