jetpack / sal / class.json-api-links.php

class.json-api-links.php in Jetpack – WP Security, Backup, Speed, & Growth 13.6, at sal/class.json-api-links.php

447 lines 15.5 KB

Raw Download Zip

1	<?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName
2	/**
3	* WPCOM_JSON_API_Links class.
4	*
5	* @package automattic/jetpack
6	*/
7
8	require_once __DIR__ . '/../class.json-api.php';
9
10	/**
11	* Base class for WPCOM_JSON_API_Links.
12	*/
13	class WPCOM_JSON_API_Links {
14
15	/**
16	* An instance of the WPCOM_JSON_API.
17	*
18	* @var WPCOM_JSON_API
19	*/
20	private $api;
21
22	/**
23	* A WPCOM_JSON_API_Links instance.
24	*
25	* @var WPCOM_JSON_API_Links
26	*/
27	private static $instance;
28
29	/**
30	* An array of the closest supported version of an endpoint to the current endpoint.
31	*
32	* @var array
33	*/
34	private $closest_endpoint_cache_by_version = array();
35
36	/**
37	* An array including the current api endpoint as well as the max versions found if that endpoint doesn't exist.
38	*
39	* @var array
40	*/
41	private $matches_by_version = array();
42
43	/**
44	* An array including the cached endpoint path versions.
45	*
46	* @var array
47	*/
48	private $cache_result = null;
49
50	/**
51	* Creates a new instance of the WPCOM_JSON_API_Links class.
52	*
53	* @return WPCOM_JSON_API_Links
54	*/
55	public static function getInstance() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid
56	if ( null === self::$instance ) {
57	self::$instance = new self();
58	}
59
60	return self::$instance;
61	}
62
63	/**
64	* WPCOM_JSON_API_Links constructor.
65	*
66	* Method protected for singleton.
67	*/
68	protected function __construct() {
69	$this->api = WPCOM_JSON_API::init();
70	}
71
72	/**
73	* An empty, private __clone method to prohibit cloning of this instance.
74	*/
75	private function __clone() { }
76
77	/**
78	* Overriding PHP's default __wakeup method to prvent unserializing of the instance, and return an error message.
79	*
80	* @return never
81	*/
82	public function __wakeup() {
83	die( "Please don't __wakeup WPCOM_JSON_API_Links" );
84	}
85
86	/**
87	* Generate a URL to an endpoint
88	*
89	* Used to construct meta links in API responses
90	*
91	* @param mixed ...$args Optional arguments to be appended to URL.
92	* @return string Endpoint URL
93	**/
94	public function get_link( ...$args ) {
95	$format = array_shift( $args );
96	$base = WPCOM_JSON_API__BASE;
97
98	$path = array_pop( $args );
99
100	if ( $path ) {
101	$path = '/' . ltrim( $path, '/' );
102	// tack the path onto the end of the format string.
103	// have to escape %'s in the path as %% because
104	// we're about to pass it through sprintf and we don't
105	// want it to see the % as a placeholder.
106	$format .= str_replace( '%', '%%', $path );
107	}
108
109	// Escape any % in args before using sprintf.
110	$escaped_args = array();
111	foreach ( $args as $arg_key => $arg_value ) {
112	$escaped_args[ $arg_key ] = str_replace( '%', '%%', $arg_value );
113	}
114
115	$relative_path = vsprintf( $format, $escaped_args );
116
117	if ( ! wp_startswith( $relative_path, '.' ) ) {
118	// Generic version. Match the requested version as best we can.
119	$api_version = $this->get_closest_version_of_endpoint( $format, $relative_path );
120	$base = substr( $base, 0, - 1 ) . $api_version;
121	}
122
123	// escape any % in the relative path before running it through sprintf again.
124	$relative_path = str_replace( '%', '%%', $relative_path );
125	// http, WPCOM_JSON_API__BASE, ... , path.
126	// %s , %s , $format, %s.
127	return esc_url_raw( sprintf( "https://%s$relative_path", $base ) );
128	}
129
130	/**
131	* Generate the /me prefixed endpoint URL
132	*
133	* Used to construct meta links in API responses, specific to WordPress.com user account pages.
134	*
135	* @param string $path Optional path to be appended to the URL.
136	* @return string /me endpoint URL
137	**/
138	public function get_me_link( $path = '' ) {
139	return $this->get_link( '/me', $path );
140	}
141
142	/**
143	* Generate the endpoint URL for taxonomies
144	*
145	* Used to construct meta links in API responses, specific to taxonomies.
146	*
147	* @param int $blog_id The site's Jetpack blog ID.
148	* @param int $taxonomy_id The taxonomy ID (for example of the category, tag).
149	* @param string $taxonomy_type The taxonomy type (for example category, tag).
150	* @param string $path Optional path to be appended to the URL.
151	* @return string Endpoint URL including taxonomy information.
152	**/
153	public function get_taxonomy_link( $blog_id, $taxonomy_id, $taxonomy_type, $path = '' ) {
154	switch ( $taxonomy_type ) {
155	case 'category':
156	return $this->get_link( '/sites/%d/categories/slug:%s', $blog_id, $taxonomy_id, $path );
157
158	case 'post_tag':
159	return $this->get_link( '/sites/%d/tags/slug:%s', $blog_id, $taxonomy_id, $path );
160
161	default:
162	return $this->get_link( '/sites/%d/taxonomies/%s/terms/slug:%s', $blog_id, $taxonomy_type, $taxonomy_id, $path );
163	}
164	}
165
166	/**
167	* Generate the endpoint URL for media links
168	*
169	* Used to construct meta links in API responses, specific to media links.
170	*
171	* @param int $blog_id The site's Jetpack blog ID.
172	* @param int $media_id The media item ID.
173	* @param string $path Optional path to be appended to the URL.
174	* @return string Endpoint URL including media information.
175	**/
176	public function get_media_link( $blog_id, $media_id, $path = '' ) {
177	return $this->get_link( '/sites/%d/media/%d', $blog_id, $media_id, $path );
178	}
179
180	/**
181	* Generate the site link endpoint URL
182	*
183	* Used to construct meta links in API responses, specific to /site links.
184	*
185	* @param int $blog_id The site's Jetpack blog ID.
186	* @param string $path Optional path to be appended to the URL.
187	* @return string Endpoint URL including site information.
188	**/
189	public function get_site_link( $blog_id, $path = '' ) {
190	return $this->get_link( '/sites/%d', $blog_id, $path );
191	}
192
193	/**
194	* Generate the posts endpoint URL
195	*
196	* Used to construct meta links in API responses, specific to posts links.
197	*
198	* @param int $blog_id The site's Jetpack blog ID.
199	* @param int $post_id The post ID.
200	* @param string $path Optional path to be appended to the URL.
201	* @return string Endpoint URL including post information.
202	**/
203	public function get_post_link( $blog_id, $post_id, $path = '' ) {
204	return $this->get_link( '/sites/%d/posts/%d', $blog_id, $post_id, $path );
205	}
206
207	/**
208	* Generate the comments endpoint URL
209	*
210	* Used to construct meta links in API responses, specific to comments links.
211	*
212	* @param int $blog_id The site's Jetpack blog ID.
213	* @param int $comment_id The comment ID.
214	* @param string $path Optional path to be appended to the URL.
215	* @return string Endpoint URL including comment information.
216	**/
217	public function get_comment_link( $blog_id, $comment_id, $path = '' ) {
218	return $this->get_link( '/sites/%d/comments/%d', $blog_id, $comment_id, $path );
219	}
220
221	/**
222	* Generate the endpoint URL for Publicize connections
223	*
224	* Used to construct meta links in API responses, specific to Publicize connections.
225	*
226	* @param int $blog_id The site's Jetpack blog ID.
227	* @param int $publicize_connection_id The ID of the Publicize connection.
228	* @param string $path Optional path to be appended to the URL.
229	* @return string Endpoint URL including Publicize connection information.
230	**/
231	public function get_publicize_connection_link( $blog_id, $publicize_connection_id, $path = '' ) {
232	return $this->get_link( '.1/sites/%d/publicize-connections/%d', $blog_id, $publicize_connection_id, $path );
233	}
234
235	/**
236	* Generate the endpoint URL for a single Publicize connection including a Keyring connection
237	*
238	* Used to construct meta links in API responses, specific to a single Publicize and Keyring connection.
239	*
240	* @param int $keyring_token_id The ID of the Keyring connection.
241	* @param string $path Optional path to be appended to the URL.
242	* @return string Endpoint URL including specific Keyring connection information for a specific Publicize connection.
243	**/
244	public function get_publicize_connections_link( $keyring_token_id, $path = '' ) {
245	return $this->get_link( '.1/me/publicize-connections/?keyring_connection_ID=%d', $keyring_token_id, $path );
246	}
247
248	/**
249	* Generate the endpoint URL for a single Keyring connection
250	*
251	* Used to construct meta links in API responses, specific to a Keyring connections.
252	*
253	* @param int $keyring_token_id The ID of the Keyring connection.
254	* @param string $path Optional path to be appended to the URL.
255	* @return string Endpoint URL including specific Keyring connection.
256	**/
257	public function get_keyring_connection_link( $keyring_token_id, $path = '' ) {
258	return $this->get_link( '.1/me/keyring-connections/%d', $keyring_token_id, $path );
259	}
260
261	/**
262	* Generate the endpoint URL for an external service that can be integrated with via Keyring
263	*
264	* Used to construct meta links in API responses, specific to an external service.
265	*
266	* @param int $external_service The ID of the external service.
267	* @param string $path Optional path to be appended to the URL.
268	* @return string Endpoint URL including information about an external service that WordPress.com or Jetpack sites can integrate with via keyring.
269	**/
270	public function get_external_service_link( $external_service, $path = '' ) {
271	return $this->get_link( '.1/meta/external-services/%s', $external_service, $path );
272	}
273
274	/**
275	* Try to find the closest supported version of an endpoint to the current endpoint
276	*
277	* For example, if we were looking at the path /animals/panda:
278	* - if the current endpoint is v1.3 and there is a v1.3 of /animals/%s available, we return 1.3
279	* - if the current endpoint is v1.3 and there is no v1.3 of /animals/%s known, we fall back to the
280	* maximum available version of /animals/%s, e.g. 1.1
281	*
282	* This method is used in get_link() to construct meta links for API responses.
283	*
284	* @param string $template_path The generic endpoint path, e.g. /sites/%s .
285	* @param string $path The current endpoint path, relative to the version, e.g. /sites/12345 .
286	* @param string $request_method Request method used to access the endpoint path .
287	* @return string The current version, or otherwise the maximum version available
288	*/
289	public function get_closest_version_of_endpoint( $template_path, $path, $request_method = 'GET' ) {
290	$closest_endpoint_cache_by_version = & $this->closest_endpoint_cache_by_version;
291
292	$closest_endpoint_cache = & $closest_endpoint_cache_by_version[ $this->api->version ];
293	if ( ! $closest_endpoint_cache ) {
294	$closest_endpoint_cache_by_version[ $this->api->version ] = array();
295	$closest_endpoint_cache = & $closest_endpoint_cache_by_version[ $this->api->version ];
296	}
297
298	if ( ! isset( $closest_endpoint_cache[ $template_path ] ) ) {
299	$closest_endpoint_cache[ $template_path ] = array();
300	} elseif ( isset( $closest_endpoint_cache[ $template_path ][ $request_method ] ) ) {
301	return $closest_endpoint_cache[ $template_path ][ $request_method ];
302	}
303
304	$path = untrailingslashit( $path );
305
306	// /help is a special case - always use the current request version
307	if ( wp_endswith( $path, '/help' ) ) {
308	$closest_endpoint_cache[ $template_path ][ $request_method ] = $this->api->version;
309	return $this->api->version;
310	}
311
312	$matches_by_version = & $this->matches_by_version;
313
314	// try to match out of saved matches.
315	if ( ! isset( $matches_by_version[ $this->api->version ] ) ) {
316	$matches_by_version[ $this->api->version ] = array();
317	}
318	foreach ( $matches_by_version[ $this->api->version ] as $match ) {
319	$regex = $match->regex;
320	if ( preg_match( "#^$regex\$#", $path ) ) {
321	$closest_endpoint_cache[ $template_path ][ $request_method ] = $match->version;
322	return $match->version;
323	}
324	}
325
326	$endpoint_path_versions = $this->get_endpoint_path_versions();
327	$last_path_segment = $this->get_last_segment_of_relative_path( $path );
328	$max_version_found = null;
329
330	foreach ( $endpoint_path_versions as $endpoint_last_path_segment => $endpoints ) {
331
332	// Does the last part of the path match the path key? (e.g. 'posts')
333	// If the last part contains a placeholder (e.g. %s), we want to carry on.
334	// phpcs:ignore Universal.Operators.StrictComparisons.LooseNotEqual
335	if ( $last_path_segment != $endpoint_last_path_segment && ! strstr( $endpoint_last_path_segment, '%' ) ) {
336	continue;
337	}
338
339	foreach ( $endpoints as $endpoint ) {
340	// Does the request method match?
341	if ( ! in_array( $request_method, $endpoint['request_methods'], true ) ) {
342	continue;
343	}
344
345	$endpoint_path = untrailingslashit( $endpoint['path'] );
346	$endpoint_path_regex = str_replace( array( '%s', '%d' ), array( '([^/?&]+)', '(\d+)' ), $endpoint_path );
347
348	if ( ! preg_match( "#^$endpoint_path_regex\$#", $path ) ) {
349	continue;
350	}
351
352	// Make sure the endpoint exists at the same version.
353	if ( null !== $this->api->version &&
354	version_compare( $this->api->version, $endpoint['min_version'], '>=' ) &&
355	version_compare( $this->api->version, $endpoint['max_version'], '<=' )
356	) {
357	array_push(
358	$matches_by_version[ $this->api->version ],
359	(object) array(
360	'version' => $this->api->version,
361	'regex' => $endpoint_path_regex,
362	)
363	);
364	$closest_endpoint_cache[ $template_path ][ $request_method ] = $this->api->version;
365	return $this->api->version;
366	}
367
368	// If the endpoint doesn't exist at the same version, record the max version we found.
369	if ( empty( $max_version_found ) \|\| version_compare( $max_version_found['version'], $endpoint['max_version'], '<' ) ) {
370	$max_version_found = array(
371	'version' => $endpoint['max_version'],
372	'regex' => $endpoint_path_regex,
373	);
374	}
375	}
376	}
377
378	// If the endpoint version is less than the requested endpoint version, return the max version found.
379	if ( ! empty( $max_version_found ) ) {
380	array_push(
381	$matches_by_version[ $this->api->version ],
382	(object) $max_version_found
383	);
384	$closest_endpoint_cache[ $template_path ][ $request_method ] = $max_version_found['version'];
385	return $max_version_found['version'];
386	}
387
388	// Otherwise, use the API version of the current request.
389	return $this->api->version;
390	}
391
392	/**
393	* Get an array of endpoint paths with their associated versions
394	*
395	* @return array Array of endpoint paths, min_versions and max_versions, keyed by last segment of path
396	**/
397	protected function get_endpoint_path_versions() {
398
399	if ( ! empty( $this->cache_result ) ) {
400	return $this->cache_result;
401	}
402
403	/*
404	* Create a map of endpoints and their min/max versions keyed by the last segment of the path (e.g. 'posts')
405	* This reduces the search space when finding endpoint matches in get_closest_version_of_endpoint()
406	*/
407	$endpoint_path_versions = array();
408
409	foreach ( $this->api->endpoints as $key => $endpoint_objects ) {
410
411	// @todo As with the todo in class.json-api.php, we need to determine if anything depends on this being serialized and hence unserialized, rather than e.g. JSON.
412	// The key contains a serialized path, min_version and max_version.
413	list( $path, $min_version, $max_version ) = unserialize( $key ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.serialize_unserialize -- Legacy, see serialization at class.json-api.php.
414
415	// Grab the last component of the relative path to use as the top-level key.
416	$last_path_segment = $this->get_last_segment_of_relative_path( $path );
417
418	$endpoint_path_versions[ $last_path_segment ][] = array(
419	'path' => $path,
420	'min_version' => $min_version,
421	'max_version' => $max_version,
422	'request_methods' => array_keys( $endpoint_objects ),
423	);
424	}
425
426	$this->cache_result = $endpoint_path_versions;
427
428	return $endpoint_path_versions;
429	}
430
431	/**
432	* Grab the last segment of a relative path
433	*
434	* @param string $path Path.
435	* @return string Last path segment
436	*/
437	protected function get_last_segment_of_relative_path( $path ) {
438	$path_parts = array_filter( explode( '/', $path ) );
439
440	if ( empty( $path_parts ) ) {
441	return null;
442	}
443
444	return end( $path_parts );
445	}
446	}
447