class.json-api.php — Jetpack – WP Security, Backup, Speed, & Growth 13.8.1

jetpack / class.json-api.php

jetpack Last commit date

class.json-api.php

1275 lines

1	<?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName
2	/**
3	* Jetpack JSON API.
4	*
5	* @package automattic/jetpack
6	*/
7
8	use Automattic\Jetpack\Status;
9
10	if ( ! defined( 'WPCOM_JSON_API__DEBUG' ) ) {
11	define( 'WPCOM_JSON_API__DEBUG', false );
12	}
13
14	require_once __DIR__ . '/sal/class.json-api-platform.php';
15
16	/**
17	* Jetpack JSON API.
18	*/
19	class WPCOM_JSON_API {
20	/**
21	* Static instance.
22	*
23	* @todo This should be private.
24	* @var self\|null
25	*/
26	public static $self = null;
27
28	/**
29	* Registered endpoints.
30	*
31	* @var WPCOM_JSON_API_Endpoint[]
32	*/
33	public $endpoints = array();
34
35	/**
36	* Endpoint being processed.
37	*
38	* @var WPCOM_JSON_API_Endpoint
39	*/
40	public $endpoint = null;
41
42	/**
43	* Token details.
44	*
45	* @var array
46	*/
47	public $token_details = array();
48
49	/**
50	* Request HTTP method.
51	*
52	* @var string
53	*/
54	public $method = '';
55
56	/**
57	* Request URL.
58	*
59	* @var string
60	*/
61	public $url = '';
62
63	/**
64	* Path part of the request URL.
65	*
66	* @var string
67	*/
68	public $path = '';
69
70	/**
71	* Version extracted from the request URL.
72	*
73	* @var string\|null
74	*/
75	public $version = null;
76
77	/**
78	* Parsed query data.
79	*
80	* @var array
81	*/
82	public $query = array();
83
84	/**
85	* Post body, if the request is a POST.
86	*
87	* @var string\|null
88	*/
89	public $post_body = null;
90
91	/**
92	* Copy of `$_FILES` if the request is a POST.
93	*
94	* @var null\|array
95	*/
96	public $files = null;
97
98	/**
99	* Content type of the request.
100	*
101	* @var string\|null
102	*/
103	public $content_type = null;
104
105	/**
106	* Value of `$_SERVER['HTTP_ACCEPT']`, if any
107	*
108	* @var string
109	*/
110	public $accept = '';
111
112	/**
113	* Value of `$_SERVER['HTTPS']`, or "--UNset--" if unset.
114	*
115	* @var string
116	*/
117	public $_server_https; // phpcs:ignore PSR2.Classes.PropertyDeclaration.Underscore
118
119	/**
120	* Whether to exit after serving a response.
121	*
122	* @var bool
123	*/
124	public $exit = true;
125
126	/**
127	* Public API scheme.
128	*
129	* @var string
130	*/
131	public $public_api_scheme = 'https';
132
133	/**
134	* Output status code.
135	*
136	* @var int
137	*/
138	public $output_status_code = 200;
139
140	/**
141	* Trapped error.
142	*
143	* @var null\|array
144	*/
145	public $trapped_error = null;
146
147	/**
148	* Whether output has been done.
149	*
150	* @var bool
151	*/
152	public $did_output = false;
153
154	/**
155	* Extra HTTP headers.
156	*
157	* @var string
158	*/
159	public $extra_headers = array();
160
161	/**
162	* AMP source origin.
163	*
164	* @var string
165	*/
166	public $amp_source_origin = null;
167
168	/**
169	* Initialize.
170	*
171	* @param string\|null $method As for `$this->setup_inputs()`.
172	* @param string\|null $url As for `$this->setup_inputs()`.
173	* @param string\|null $post_body As for `$this->setup_inputs()`.
174	* @return WPCOM_JSON_API instance
175	*/
176	public static function init( $method = null, $url = null, $post_body = null ) {
177	if ( ! self::$self ) {
178	self::$self = new static( $method, $url, $post_body );
179	}
180	return self::$self;
181	}
182
183	/**
184	* Add an endpoint.
185	*
186	* @param WPCOM_JSON_API_Endpoint $endpoint Endpoint to add.
187	*/
188	public function add( WPCOM_JSON_API_Endpoint $endpoint ) {
189	// @todo Determine if anything depends on this being serialized rather than e.g. JSON.
190	// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.serialize_serialize -- Legacy, possibly depended on elsewhere.
191	$path_versions = serialize(
192	array(
193	$endpoint->path,
194	$endpoint->min_version,
195	$endpoint->max_version,
196	)
197	);
198	if ( ! isset( $this->endpoints[ $path_versions ] ) ) {
199	$this->endpoints[ $path_versions ] = array();
200	}
201	$this->endpoints[ $path_versions ][ $endpoint->method ] = $endpoint;
202	}
203
204	/**
205	* Determine if a string is truthy. If it's not a string, which can happen with
206	* not well-formed data coming from Jetpack sites, we still consider it a truthy value.
207	*
208	* @param mixed $value true, 1, "1", "t", and "true" (case insensitive) are truthy, everything else isn't.
209	* @return bool
210	*/
211	public static function is_truthy( $value ) {
212	if ( true === $value ) {
213	return true;
214	}
215
216	if ( 1 === $value ) {
217	return true;
218	}
219
220	if ( ! is_string( $value ) ) {
221	return false;
222	}
223
224	switch ( strtolower( (string) $value ) ) {
225	case '1':
226	case 't':
227	case 'true':
228	return true;
229	}
230
231	return false;
232	}
233
234	/**
235	* Determine if a string is falsey.
236	*
237	* @param mixed $value false, 0, "0", "f", and "false" (case insensitive) are falsey, everything else isn't.
238	* @return bool
239	*/
240	public static function is_falsy( $value ) {
241	if ( false === $value ) {
242	return true;
243	}
244
245	if ( 0 === $value ) {
246	return true;
247	}
248
249	if ( ! is_string( $value ) ) {
250	return false;
251	}
252
253	switch ( strtolower( (string) $value ) ) {
254	case '0':
255	case 'f':
256	case 'false':
257	return true;
258	}
259
260	return false;
261	}
262
263	/**
264	* Constructor.
265	*
266	* @todo This should be private.
267	* @param string\|null $method As for `$this->setup_inputs()`.
268	* @param string\|null $url As for `$this->setup_inputs()`.
269	* @param string\|null $post_body As for `$this->setup_inputs()`.
270	*/
271	public function __construct( $method = null, $url = null, $post_body = null ) {
272	$this->setup_inputs( $method, $url, $post_body );
273	}
274
275	/**
276	* Setup inputs.
277	*
278	* @param string\|null $method Request HTTP method. Fetched from `$_SERVER` if null.
279	* @param string\|null $url URL requested. Determined from `$_SERVER` if null.
280	* @param string\|null $post_body POST body. Read from `php://input` if null and method is POST.
281	*/
282	public function setup_inputs( $method = null, $url = null, $post_body = null ) {
283	if ( $method === null ) {
284	$this->method = isset( $_SERVER['REQUEST_METHOD'] ) ? strtoupper( filter_var( wp_unslash( $_SERVER['REQUEST_METHOD'] ) ) ) : '';
285	} else {
286	$this->method = strtoupper( $method );
287	}
288	if ( $url === null ) {
289	// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- Sniff misses the esc_url_raw.
290	$this->url = esc_url_raw( set_url_scheme( 'http://' . ( isset( $_SERVER['HTTP_HOST'] ) ? wp_unslash( $_SERVER['HTTP_HOST'] ) : '' ) . ( isset( $_SERVER['REQUEST_URI'] ) ? wp_unslash( $_SERVER['REQUEST_URI'] ) : '' ) ) );
291	} else {
292	$this->url = $url;
293	}
294
295	$parsed = wp_parse_url( $this->url );
296	if ( ! empty( $parsed['path'] ) ) {
297	$this->path = $parsed['path'];
298	}
299
300	if ( ! empty( $parsed['query'] ) ) {
301	wp_parse_str( $parsed['query'], $this->query );
302	}
303
304	if ( ! empty( $_SERVER['HTTP_ACCEPT'] ) ) {
305	$this->accept = filter_var( wp_unslash( $_SERVER['HTTP_ACCEPT'] ) );
306	}
307
308	if ( 'POST' === $this->method ) {
309	if ( $post_body === null ) {
310	$this->post_body = file_get_contents( 'php://input' );
311
312	if ( ! empty( $_SERVER['HTTP_CONTENT_TYPE'] ) ) {
313	$this->content_type = filter_var( wp_unslash( $_SERVER['HTTP_CONTENT_TYPE'] ) );
314	} elseif ( ! empty( $_SERVER['CONTENT_TYPE'] ) ) {
315	$this->content_type = filter_var( wp_unslash( $_SERVER['CONTENT_TYPE'] ) );
316	} elseif ( isset( $this->post_body[0] ) && '{' === $this->post_body[0] ) {
317	$this->content_type = 'application/json';
318	} else {
319	$this->content_type = 'application/x-www-form-urlencoded';
320	}
321
322	if ( str_starts_with( strtolower( $this->content_type ), 'multipart/' ) ) {
323	// phpcs:ignore WordPress.Security.NonceVerification.Missing
324	$this->post_body = http_build_query( stripslashes_deep( $_POST ) );
325	$this->files = $_FILES;
326	$this->content_type = 'multipart/form-data';
327	}
328	} else {
329	$this->post_body = $post_body;
330	$this->content_type = isset( $this->post_body[0] ) && '{' === $this->post_body[0] ? 'application/json' : 'application/x-www-form-urlencoded';
331	}
332	} else {
333	$this->post_body = null;
334	$this->content_type = null;
335	}
336
337	$this->_server_https = array_key_exists( 'HTTPS', $_SERVER ) ? filter_var( wp_unslash( $_SERVER['HTTPS'] ) ) : '--UNset--';
338	}
339
340	/**
341	* Initialize.
342	*
343	* @return null\|WP_Error (although this implementation always returns null)
344	*/
345	public function initialize() {
346	$this->token_details['blog_id'] = Jetpack_Options::get_option( 'id' );
347	return null;
348	}
349
350	/**
351	* Checks if the current request is authorized with a blog token.
352	* This method is overridden by a child class in WPCOM.
353	*
354	* @since 9.1.0
355	*
356	* @param boolean\|int $site_id The site id.
357	* @return boolean
358	*/
359	public function is_jetpack_authorized_for_site( $site_id = false ) {
360	if ( ! $this->token_details ) {
361	return false;
362	}
363
364	$token_details = (object) $this->token_details;
365
366	$site_in_token = (int) $token_details->blog_id;
367
368	if ( $site_in_token < 1 ) {
369	return false;
370	}
371
372	if ( $site_id && $site_in_token !== (int) $site_id ) {
373	return false;
374	}
375
376	if ( (int) get_current_user_id() !== 0 ) {
377	// If Jetpack blog token is used, no logged-in user should exist.
378	return false;
379	}
380
381	return true;
382	}
383
384	/**
385	* Checks if the current request is authorized with an upload token.
386	* This method is overridden by a child class in WPCOM.
387	*
388	* @since 13.5
389	* @return boolean
390	*/
391	public function is_authorized_with_upload_token() {
392	return false;
393	}
394
395	/**
396	* Serve.
397	*
398	* @param bool $exit Whether to exit.
399	* @return string\|null Content type (assuming it didn't exit), or null in certain error cases.
400	*/
401	public function serve( $exit = true ) {
402	ini_set( 'display_errors', false ); // phpcs:ignore WordPress.PHP.IniSet.display_errors_Blacklisted
403
404	$this->exit = (bool) $exit;
405
406	// This was causing problems with Jetpack, but is necessary for wpcom
407	// @see https://github.com/Automattic/jetpack/pull/2603
408	// @see r124548-wpcom .
409	if ( defined( 'IS_WPCOM' ) && IS_WPCOM ) {
410	add_filter( 'home_url', array( $this, 'ensure_http_scheme_of_home_url' ), 10, 3 );
411	}
412
413	add_filter( 'user_can_richedit', '__return_true' );
414
415	add_filter( 'comment_edit_pre', array( $this, 'comment_edit_pre' ) );
416
417	$initialization = $this->initialize();
418	if ( 'OPTIONS' === $this->method ) {
419	/**
420	* Fires before the page output.
421	* Can be used to specify custom header options.
422	*
423	* @module json-api
424	*
425	* @since 3.1.0
426	*/
427	do_action( 'wpcom_json_api_options' );
428	return $this->output( 200, '', 'text/plain' );
429	}
430
431	if ( is_wp_error( $initialization ) ) {
432	$this->output_error( $initialization );
433	return;
434	}
435
436	// Normalize path and extract API version.
437	$this->path = untrailingslashit( $this->path );
438	if ( preg_match( '#^/rest/v(\d+(\.\d+)*)#', $this->path, $matches ) ) {
439	$this->path = substr( $this->path, strlen( $matches[0] ) );
440	$this->version = $matches[1];
441	}
442
443	$allowed_methods = array( 'GET', 'POST' );
444	$four_oh_five = false;
445
446	$is_help = preg_match( '#/help/?$#i', $this->path );
447	$matching_endpoints = array();
448
449	if ( $is_help ) {
450	$origin = get_http_origin();
451
452	if ( ! empty( $origin ) && 'GET' === $this->method ) {
453	header( 'Access-Control-Allow-Origin: ' . esc_url_raw( $origin ) );
454	}
455
456	$this->path = substr( rtrim( $this->path, '/' ), 0, -5 );
457	// Show help for all matching endpoints regardless of method.
458	$methods = $allowed_methods;
459	$find_all_matching_endpoints = true;
460	// How deep to truncate each endpoint's path to see if it matches this help request.
461	$depth = substr_count( $this->path, '/' ) + 1;
462	if ( false !== stripos( $this->accept, 'javascript' ) \|\| false !== stripos( $this->accept, 'json' ) ) {
463	$help_content_type = 'json';
464	} else {
465	$help_content_type = 'html';
466	}
467	} elseif ( in_array( $this->method, $allowed_methods, true ) ) {
468	// Only serve requested method.
469	$methods = array( $this->method );
470	$find_all_matching_endpoints = false;
471	} else {
472	// We don't allow this requested method - find matching endpoints and send 405.
473	$methods = $allowed_methods;
474	$find_all_matching_endpoints = true;
475	$four_oh_five = true;
476	}
477
478	// Find which endpoint to serve.
479	$found = false;
480	foreach ( $this->endpoints as $endpoint_path_versions => $endpoints_by_method ) {
481	// @todo Determine if anything depends on this being serialized rather than e.g. JSON.
482	// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.serialize_unserialize -- Legacy, possibly depended on elsewhere.
483	$endpoint_path_versions = unserialize( $endpoint_path_versions );
484	$endpoint_path = $endpoint_path_versions[0];
485	$endpoint_min_version = $endpoint_path_versions[1];
486	$endpoint_max_version = $endpoint_path_versions[2];
487
488	// Make sure max_version is not less than min_version.
489	if ( version_compare( $endpoint_max_version, $endpoint_min_version, '<' ) ) {
490	$endpoint_max_version = $endpoint_min_version;
491	}
492
493	foreach ( $methods as $method ) {
494	if ( ! isset( $endpoints_by_method[ $method ] ) ) {
495	continue;
496	}
497
498	// Normalize.
499	$endpoint_path = untrailingslashit( $endpoint_path );
500	if ( $is_help ) {
501	// Truncate path at help depth.
502	$endpoint_path = implode( '/', array_slice( explode( '/', $endpoint_path ), 0, $depth ) );
503	}
504
505	// Generate regular expression from sprintf().
506	$endpoint_path_regex = str_replace( array( '%s', '%d' ), array( '([^/?&]+)', '(\d+)' ), $endpoint_path );
507
508	if ( ! preg_match( "#^$endpoint_path_regex\$#", $this->path, $path_pieces ) ) {
509	// This endpoint does not match the requested path.
510	continue;
511	}
512
513	if ( version_compare( $this->version, $endpoint_min_version, '<' ) \|\| version_compare( $this->version, $endpoint_max_version, '>' ) ) {
514	// This endpoint does not match the requested version.
515	continue;
516	}
517
518	$found = true;
519
520	if ( $find_all_matching_endpoints ) {
521	$matching_endpoints[] = array( $endpoints_by_method[ $method ], $path_pieces );
522	} else {
523	// The method parameters are now in $path_pieces.
524	$endpoint = $endpoints_by_method[ $method ];
525	break 2;
526	}
527	}
528	}
529
530	if ( ! $found ) {
531	return $this->output( 404, '', 'text/plain' );
532	}
533
534	if ( $four_oh_five ) {
535	$allowed_methods = array();
536	foreach ( $matching_endpoints as $matching_endpoint ) {
537	$allowed_methods[] = $matching_endpoint[0]->method;
538	}
539
540	header( 'Allow: ' . strtoupper( implode( ',', array_unique( $allowed_methods ) ) ) );
541	return $this->output(
542	405,
543	array(
544	'error' => 'not_allowed',
545	'error_message' => 'Method not allowed',
546	)
547	);
548	}
549
550	if ( $is_help ) {
551	/**
552	* Fires before the API output.
553	*
554	* @since 1.9.0
555	*
556	* @param string help.
557	*/
558	do_action( 'wpcom_json_api_output', 'help' );
559	$proxied = function_exists( 'wpcom_is_proxied_request' ) ? wpcom_is_proxied_request() : false;
560	if ( 'json' === $help_content_type ) {
561	$docs = array();
562	foreach ( $matching_endpoints as $matching_endpoint ) {
563	if ( $matching_endpoint[0]->is_publicly_documentable() \|\| $proxied \|\| WPCOM_JSON_API__DEBUG ) {
564	$docs[] = call_user_func( array( $matching_endpoint[0], 'generate_documentation' ) );
565	}
566	}
567	return $this->output( 200, $docs );
568	} else {
569	status_header( 200 );
570	foreach ( $matching_endpoints as $matching_endpoint ) {
571	if ( $matching_endpoint[0]->is_publicly_documentable() \|\| $proxied \|\| WPCOM_JSON_API__DEBUG ) {
572	call_user_func( array( $matching_endpoint[0], 'document' ) );
573	}
574	}
575	}
576	exit;
577	}
578
579	if ( $endpoint->in_testing && ! WPCOM_JSON_API__DEBUG ) {
580	return $this->output( 404, '', 'text/plain' );
581	}
582
583	/** This action is documented in class.json-api.php */
584	do_action( 'wpcom_json_api_output', $endpoint->stat );
585
586	$response = $this->process_request( $endpoint, $path_pieces );
587
588	if ( ! $response && ! is_array( $response ) ) {
589	return $this->output( 500, '', 'text/plain' );
590	} elseif ( is_wp_error( $response ) ) {
591	return $this->output_error( $response );
592	}
593
594	$output_status_code = $this->output_status_code;
595	$this->set_output_status_code();
596
597	return $this->output( $output_status_code, $response, 'application/json', $this->extra_headers );
598	}
599
600	/**
601	* Process a request.
602	*
603	* @param WPCOM_JSON_API_Endpoint $endpoint Endpoint.
604	* @param array $path_pieces Path pieces.
605	* @return array\|WP_Error Return value from the endpoint's callback.
606	*/
607	public function process_request( WPCOM_JSON_API_Endpoint $endpoint, $path_pieces ) {
608	$this->endpoint = $endpoint;
609	return call_user_func_array( array( $endpoint, 'callback' ), $path_pieces );
610	}
611
612	/**
613	* Output a response or error without exiting.
614	*
615	* @param int $status_code HTTP status code.
616	* @param mixed $response Response data.
617	* @param string $content_type Content type of the response.
618	*/
619	public function output_early( $status_code, $response = null, $content_type = 'application/json' ) {
620	$exit = $this->exit;
621	$this->exit = false;
622	if ( is_wp_error( $response ) ) {
623	$this->output_error( $response );
624	} else {
625	$this->output( $status_code, $response, $content_type );
626	}
627	$this->exit = $exit;
628	if ( ! defined( 'XMLRPC_REQUEST' ) \|\| ! XMLRPC_REQUEST ) {
629	$this->finish_request();
630	}
631	}
632
633	/**
634	* Set output status code.
635	*
636	* @param int $code HTTP status code.
637	*/
638	public function set_output_status_code( $code = 200 ) {
639	$this->output_status_code = $code;
640	}
641
642	/**
643	* Output a response.
644	*
645	* @param int $status_code HTTP status code.
646	* @param mixed $response Response data.
647	* @param string $content_type Content type of the response.
648	* @param array $extra Additional HTTP headers.
649	* @return string Content type (assuming it didn't exit).
650	*/
651	public function output( $status_code, $response = null, $content_type = 'application/json', $extra = array() ) {
652	$status_code = (int) $status_code;
653
654	// In case output() was called before the callback returned.
655	if ( $this->did_output ) {
656	if ( $this->exit ) {
657	exit;
658	}
659	return $content_type;
660	}
661	$this->did_output = true;
662
663	// 400s and 404s are allowed for all origins
664	if ( 404 === $status_code \|\| 400 === $status_code ) {
665	header( 'Access-Control-Allow-Origin: *' );
666	}
667
668	/* Add headers for form submission from <amp-form/> */
669	if ( $this->amp_source_origin ) {
670	header( 'Access-Control-Allow-Origin: ' . wp_unslash( $this->amp_source_origin ) );
671	header( 'Access-Control-Allow-Credentials: true' );
672	}
673
674	if ( $response === null ) {
675	$response = new stdClass();
676	}
677
678	if ( 'text/plain' === $content_type \|\|
679	'text/html' === $content_type ) {
680	status_header( (int) $status_code );
681	header( 'Content-Type: ' . $content_type );
682	foreach ( $extra as $key => $value ) {
683	header( "$key: $value" );
684	}
685	echo $response; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
686	if ( $this->exit ) {
687	exit;
688	}
689
690	return $content_type;
691	}
692
693	$response = $this->filter_fields( $response );
694
695	if ( isset( $this->query['http_envelope'] ) && self::is_truthy( $this->query['http_envelope'] ) ) {
696	$headers = array(
697	array(
698	'name' => 'Content-Type',
699	'value' => $content_type,
700	),
701	);
702
703	foreach ( $extra as $key => $value ) {
704	$headers[] = array(
705	'name' => $key,
706	'value' => $value,
707	);
708	}
709
710	$response = array(
711	'code' => (int) $status_code,
712	'headers' => $headers,
713	'body' => $response,
714	);
715	$status_code = 200;
716	$content_type = 'application/json';
717	}
718
719	status_header( (int) $status_code );
720	header( "Content-Type: $content_type" );
721	if ( isset( $this->query['callback'] ) && is_string( $this->query['callback'] ) ) {
722	$callback = preg_replace( '/[^a-z0-9_.]/i', '', $this->query['callback'] );
723	} else {
724	$callback = false;
725	}
726
727	if ( $callback ) {
728	// Mitigate Rosetta Flash [1] by setting the Content-Type-Options: nosniff header
729	// and by prepending the JSONP response with a JS comment.
730	// [1] <https://blog.miki.it/2014/7/8/abusing-jsonp-with-rosetta-flash/index.html>.
731	echo "/**/$callback("; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- This is JSONP output, not HTML.
732
733	}
734	echo $this->json_encode( $response ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- This is JSON or JSONP output, not HTML.
735	if ( $callback ) {
736	echo ');';
737	}
738
739	if ( $this->exit ) {
740	exit;
741	}
742
743	return $content_type;
744	}
745
746	/**
747	* Serialize an error.
748	*
749	* @param WP_Error $error Error.
750	* @return array with 'status_code' and 'errors' data.
751	*/
752	public static function serializable_error( $error ) {
753
754	$status_code = $error->get_error_data();
755
756	if ( is_array( $status_code ) && isset( $status_code['status_code'] ) ) {
757	$status_code = $status_code['status_code'];
758	}
759
760	if ( ! $status_code ) {
761	$status_code = 400;
762	}
763	$response = array(
764	'error' => $error->get_error_code(),
765	'message' => $error->get_error_message(),
766	);
767
768	$additional_data = $error->get_error_data( 'additional_data' );
769	if ( $additional_data ) {
770	$response['data'] = $additional_data;
771	}
772
773	return array(
774	'status_code' => $status_code,
775	'errors' => $response,
776	);
777	}
778
779	/**
780	* Output an error.
781	*
782	* @param WP_Error $error Error.
783	* @return string Content type (assuming it didn't exit).
784	*/
785	public function output_error( $error ) {
786	$error_response = static::serializable_error( $error );
787
788	return $this->output( $error_response['status_code'], $error_response['errors'] );
789	}
790
791	/**
792	* Filter fields in a response.
793	*
794	* @param array\|object $response Response.
795	* @return array\|object Filtered response.
796	*/
797	public function filter_fields( $response ) {
798	if ( empty( $this->query['fields'] ) \|\| ( is_array( $response ) && ! empty( $response['error'] ) ) \|\| ! empty( $this->endpoint->custom_fields_filtering ) ) {
799	return $response;
800	}
801
802	$fields = array_map( 'trim', explode( ',', $this->query['fields'] ) );
803
804	if ( is_object( $response ) ) {
805	$response = (array) $response;
806	}
807
808	$has_filtered = false;
809	if ( is_array( $response ) && empty( $response['ID'] ) ) {
810	$keys_to_filter = array(
811	'categories',
812	'comments',
813	'connections',
814	'domains',
815	'groups',
816	'likes',
817	'media',
818	'notes',
819	'posts',
820	'services',
821	'sites',
822	'suggestions',
823	'tags',
824	'themes',
825	'topics',
826	'users',
827	);
828
829	foreach ( $keys_to_filter as $key_to_filter ) {
830	if ( ! isset( $response[ $key_to_filter ] ) \|\| $has_filtered ) {
831	continue;
832	}
833
834	foreach ( $response[ $key_to_filter ] as $key => $values ) {
835	if ( is_object( $values ) ) {
836	if ( is_object( $response[ $key_to_filter ] ) ) {
837	// phpcs:ignore Squiz.PHP.DisallowMultipleAssignments.Found -- False positive.
838	$response[ $key_to_filter ]->$key = (object) array_intersect_key( ( (array) $values ), array_flip( $fields ) );
839	} elseif ( is_array( $response[ $key_to_filter ] ) ) {
840	$response[ $key_to_filter ][ $key ] = (object) array_intersect_key( ( (array) $values ), array_flip( $fields ) );
841	}
842	} elseif ( is_array( $values ) ) {
843	$response[ $key_to_filter ][ $key ] = array_intersect_key( $values, array_flip( $fields ) );
844	}
845	}
846
847	$has_filtered = true;
848	}
849	}
850
851	if ( ! $has_filtered ) {
852	if ( is_object( $response ) ) {
853	$response = (object) array_intersect_key( (array) $response, array_flip( $fields ) );
854	} elseif ( is_array( $response ) ) {
855	$response = array_intersect_key( $response, array_flip( $fields ) );
856	}
857	}
858
859	return $response;
860	}
861
862	/**
863	* Filter for `home_url`.
864	*
865	* If `$original_scheme` is null, turns an https URL to http.
866	*
867	* @param string $url The complete home URL including scheme and path.
868	* @param string $path Path relative to the home URL. Blank string if no path is specified.
869	* @param string\|null $original_scheme Scheme to give the home URL context. Accepts 'http', 'https', 'relative', 'rest', or null.
870	* @return string URL.
871	*/
872	public function ensure_http_scheme_of_home_url( $url, $path, $original_scheme ) {
873	if ( $original_scheme ) {
874	return $url;
875	}
876
877	return preg_replace( '#^https:#', 'http:', $url );
878	}
879
880	/**
881	* Decode HTML special characters in comment content.
882	*
883	* @param string $comment_content Comment content.
884	* @return string
885	*/
886	public function comment_edit_pre( $comment_content ) {
887	return htmlspecialchars_decode( $comment_content, ENT_QUOTES );
888	}
889
890	/**
891	* JSON encode.
892	*
893	* @param mixed $data Data.
894	* @return string\|false
895	*/
896	public function json_encode( $data ) {
897	return wp_json_encode( $data );
898	}
899
900	/**
901	* Test if a string ends with a string.
902	*
903	* @param string $haystack String to check.
904	* @param string $needle Suffix to check.
905	* @return bool
906	*/
907	public function ends_with( $haystack, $needle ) {
908	return substr( $haystack, -strlen( $needle ) ) === $needle;
909	}
910
911	/**
912	* Returns the site's blog_id in the WP.com ecosystem
913	*
914	* @return int
915	*/
916	public function get_blog_id_for_output() {
917	return $this->token_details['blog_id'];
918	}
919
920	/**
921	* Returns the site's local blog_id.
922	*
923	* @param int $blog_id Blog ID.
924	* @return int
925	*/
926	public function get_blog_id( $blog_id ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
927	return $GLOBALS['blog_id'];
928	}
929
930	/**
931	* Switch to blog and validate user.
932	*
933	* @param int $blog_id Blog ID.
934	* @param bool $verify_token_for_blog Whether to verify the token.
935	* @return int Blog ID.
936	*/
937	public function switch_to_blog_and_validate_user( $blog_id = 0, $verify_token_for_blog = true ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
938	if ( $this->is_restricted_blog( $blog_id ) ) {
939	return new WP_Error( 'unauthorized', 'User cannot access this restricted blog', 403 );
940	}
941	/**
942	* If this is a private site we check for 2 things:
943	* 1. In case of user based authentication, we need to check if the logged-in user has the 'read' capability.
944	* 2. In case of site based authentication, make sure the endpoint accepts it.
945	*/
946	if ( ( new Status() )->is_private_site() &&
947	! current_user_can( 'read' ) &&
948	! $this->endpoint->accepts_site_based_authentication()
949	) {
950	return new WP_Error( 'unauthorized', 'User cannot access this private blog.', 403 );
951	}
952
953	return $blog_id;
954	}
955
956	/**
957	* Returns true if the specified blog ID is a restricted blog
958	*
959	* @param int $blog_id Blog ID.
960	* @return bool
961	*/
962	public function is_restricted_blog( $blog_id ) {
963	/**
964	* Filters all REST API access and return a 403 unauthorized response for all Restricted blog IDs.
965	*
966	* @module json-api
967	*
968	* @since 3.4.0
969	*
970	* @param array $array Array of Blog IDs.
971	*/
972	$restricted_blog_ids = apply_filters( 'wpcom_json_api_restricted_blog_ids', array() );
973	return true === in_array( $blog_id, $restricted_blog_ids ); // phpcs:ignore WordPress.PHP.StrictInArray.MissingTrueStrict -- I don't trust filters to return the right types.
974	}
975
976	/**
977	* Post like count.
978	*
979	* @param int $blog_id Blog ID.
980	* @param int $post_id Post ID.
981	* @return int
982	*/
983	public function post_like_count( $blog_id, $post_id ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
984	return 0;
985	}
986
987	/**
988	* Is liked?
989	*
990	* @param int $blog_id Blog ID.
991	* @param int $post_id Post ID.
992	* @return bool
993	*/
994	public function is_liked( $blog_id, $post_id ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
995	return false;
996	}
997
998	/**
999	* Is reblogged?
1000	*
1001	* @param int $blog_id Blog ID.
1002	* @param int $post_id Post ID.
1003	* @return bool
1004	*/
1005	public function is_reblogged( $blog_id, $post_id ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
1006	return false;
1007	}
1008
1009	/**
1010	* Is following?
1011	*
1012	* @param int $blog_id Blog ID.
1013	* @return bool
1014	*/
1015	public function is_following( $blog_id ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
1016	return false;
1017	}
1018
1019	/**
1020	* Add global ID.
1021	*
1022	* @param int $blog_id Blog ID.
1023	* @param int $post_id Post ID.
1024	* @return string
1025	*/
1026	public function add_global_ID( $blog_id, $post_id ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable, WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid
1027	return '';
1028	}
1029
1030	/**
1031	* Return a count of comment likes.
1032	* This method is overridden by a child class in WPCOM.
1033	*
1034	* @since 13.5
1035	* @return int
1036	*/
1037	public function comment_like_count() {
1038	func_get_args(); // @phan-suppress-current-line PhanPluginUseReturnValueInternalKnown -- This is just here so Phan realizes the wpcom version does this.
1039	return 0;
1040	}
1041
1042	/**
1043	* Get avatar URL.
1044	*
1045	* @param string $email Email.
1046	* @param array $args Args for `get_avatar_url()`.
1047	* @return string\|false
1048	*/
1049	public function get_avatar_url( $email, $args = null ) {
1050	if ( function_exists( 'wpcom_get_avatar_url' ) ) {
1051	$ret = wpcom_get_avatar_url( $email, $args['size'] ?? 96, $args['default'] ?? '', false, $args['force_default'] ?? false );
1052	return $ret ? $ret[0] : false;
1053	} else {
1054	return null === $args
1055	? get_avatar_url( $email )
1056	: get_avatar_url( $email, $args );
1057	}
1058	}
1059
1060	/**
1061	* Counts the number of comments on a site, including certain comment types.
1062	*
1063	* @param int $post_id Post ID.
1064	* @return array Array of counts, matching the output of https://developer.wordpress.org/reference/functions/get_comment_count/.
1065	*/
1066	public function wp_count_comments( $post_id ) {
1067	global $wpdb;
1068	if ( 0 !== $post_id ) {
1069	return wp_count_comments( $post_id );
1070	}
1071
1072	$counts = array(
1073	'total_comments' => 0,
1074	'all' => 0,
1075	);
1076
1077	/**
1078	* Exclude certain comment types from comment counts in the REST API.
1079	*
1080	* @since 6.9.0
1081	* @deprecated 11.1
1082	* @module json-api
1083	*
1084	* @param array Array of comment types to exclude (default: 'order_note', 'webhook_delivery', 'review', 'action_log')
1085	*/
1086	$exclude = apply_filters_deprecated( 'jetpack_api_exclude_comment_types_count', array( 'order_note', 'webhook_delivery', 'review', 'action_log' ), 'jetpack-11.1', 'jetpack_api_include_comment_types_count' ); // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
1087
1088	/**
1089	* Include certain comment types in comment counts in the REST API.
1090	* Note: the default array of comment types includes an empty string,
1091	* to support comments posted before WP 5.5, that used an empty string as comment type.
1092	*
1093	* @since 11.1
1094	* @module json-api
1095	*
1096	* @param array Array of comment types to include (default: 'comment', 'pingback', 'trackback')
1097	*/
1098	$include = apply_filters(
1099	'jetpack_api_include_comment_types_count',
1100	array( 'comment', 'pingback', 'trackback', '' )
1101	);
1102
1103	if ( empty( $include ) ) {
1104	return wp_count_comments( $post_id );
1105	}
1106
1107	array_walk( $include, 'esc_sql' );
1108	$where = sprintf(
1109	"WHERE comment_type IN ( '%s' )",
1110	implode( "','", $include )
1111	);
1112
1113	// phpcs:disable WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- `$where` is built with escaping just above.
1114	$count = $wpdb->get_results(
1115	"SELECT comment_approved, COUNT(*) AS num_comments
1116	FROM $wpdb->comments
1117	{$where}
1118	GROUP BY comment_approved
1119	"
1120	);
1121	// phpcs:enable WordPress.DB.PreparedSQL.InterpolatedNotPrepared
1122
1123	$approved = array(
1124	'0' => 'moderated',
1125	'1' => 'approved',
1126	'spam' => 'spam',
1127	'trash' => 'trash',
1128	'post-trashed' => 'post-trashed',
1129	);
1130
1131	// <https://developer.wordpress.org/reference/functions/get_comment_count/#source>
1132	foreach ( $count as $row ) {
1133	if ( ! in_array( $row->comment_approved, array( 'post-trashed', 'trash', 'spam' ), true ) ) {
1134	$counts['all'] += $row->num_comments;
1135	$counts['total_comments'] += $row->num_comments;
1136	} elseif ( ! in_array( $row->comment_approved, array( 'post-trashed', 'trash' ), true ) ) {
1137	$counts['total_comments'] += $row->num_comments;
1138	}
1139	if ( isset( $approved[ $row->comment_approved ] ) ) {
1140	$counts[ $approved[ $row->comment_approved ] ] = $row->num_comments;
1141	}
1142	}
1143
1144	foreach ( $approved as $key ) {
1145	if ( empty( $counts[ $key ] ) ) {
1146	$counts[ $key ] = 0;
1147	}
1148	}
1149
1150	$counts = (object) $counts;
1151
1152	return $counts;
1153	}
1154
1155	/**
1156	* Traps `wp_die()` calls and outputs a JSON response instead.
1157	* The result is always output, never returned.
1158	*
1159	* @param string\|null $error_code Call with string to start the trapping. Call with null to stop.
1160	* @param int $http_status HTTP status code, 400 by default.
1161	*/
1162	public function trap_wp_die( $error_code = null, $http_status = 400 ) {
1163	// Determine the filter name; based on the conditionals inside the wp_die function.
1164	if ( wp_is_json_request() ) {
1165	$die_handler = 'wp_die_json_handler';
1166	} elseif ( wp_is_jsonp_request() ) {
1167	$die_handler = 'wp_die_jsonp_handler';
1168	} elseif ( wp_is_xml_request() ) {
1169	$die_handler = 'wp_die_xml_handler';
1170	} else {
1171	$die_handler = 'wp_die_handler';
1172	}
1173
1174	if ( $error_code === null ) {
1175	$this->trapped_error = null;
1176	// Stop trapping.
1177	remove_filter( $die_handler, array( $this, 'wp_die_handler_callback' ) );
1178	return;
1179	}
1180
1181	// If API called via PHP, bail: don't do our custom wp_die(). Do the normal wp_die().
1182	if ( defined( 'IS_WPCOM' ) && IS_WPCOM ) {
1183	if ( ! defined( 'REST_API_REQUEST' ) \|\| ! REST_API_REQUEST ) {
1184	return;
1185	}
1186	} elseif ( ! defined( 'XMLRPC_REQUEST' ) \|\| ! XMLRPC_REQUEST ) {
1187	return;
1188	}
1189
1190	$this->trapped_error = array(
1191	'status' => $http_status,
1192	'code' => $error_code,
1193	'message' => '',
1194	);
1195	// Start trapping.
1196	add_filter( $die_handler, array( $this, 'wp_die_handler_callback' ) );
1197	}
1198
1199	/**
1200	* Filter function for `wp_die_handler` and similar filters.
1201	*
1202	* @return callable
1203	*/
1204	public function wp_die_handler_callback() {
1205	return array( $this, 'wp_die_handler' );
1206	}
1207
1208	/**
1209	* Handler for `wp_die` calls.
1210	*
1211	* @param string\|WP_Error $message As for `wp_die()`.
1212	* @param string\|int $title As for `wp_die()`.
1213	* @param string\|array\|int $args As for `wp_die()`.
1214	* @return never
1215	*/
1216	public function wp_die_handler( $message, $title = '', $args = array() ) {
1217	// Allow wp_die calls to override HTTP status code...
1218	$args = wp_parse_args(
1219	$args,
1220	array(
1221	'response' => $this->trapped_error['status'],
1222	)
1223	);
1224
1225	// ... unless it's 500
1226	if ( 500 !== (int) $args['response'] ) {
1227	$this->trapped_error['status'] = $args['response'];
1228	}
1229
1230	if ( $title ) {
1231	$message = "$title: $message";
1232	}
1233
1234	$this->trapped_error['message'] = wp_kses( $message, array() );
1235
1236	switch ( $this->trapped_error['code'] ) {
1237	case 'comment_failure':
1238	if ( did_action( 'comment_duplicate_trigger' ) ) {
1239	$this->trapped_error['code'] = 'comment_duplicate';
1240	} elseif ( did_action( 'comment_flood_trigger' ) ) {
1241	$this->trapped_error['code'] = 'comment_flood';
1242	}
1243	break;
1244	}
1245
1246	// We still want to exit so that code execution stops where it should.
1247	// Attach the JSON output to the WordPress shutdown handler.
1248	add_action( 'shutdown', array( $this, 'output_trapped_error' ), 0 );
1249	exit;
1250	}
1251
1252	/**
1253	* Output the trapped error.
1254	*/
1255	public function output_trapped_error() {
1256	$this->exit = false; // We're already exiting once. Don't do it twice.
1257	$this->output(
1258	$this->trapped_error['status'],
1259	(object) array(
1260	'error' => $this->trapped_error['code'],
1261	'message' => $this->trapped_error['message'],
1262	)
1263	);
1264	}
1265
1266	/**
1267	* Finish the request.
1268	*/
1269	public function finish_request() {
1270	if ( function_exists( 'fastcgi_finish_request' ) ) {
1271	return fastcgi_finish_request();
1272	}
1273	}
1274	}
1275