wp-parsely / src / Endpoints / class-base-endpoint.php

class-base-endpoint.php in Parse.ly 3.14.1, at src/Endpoints/class-base-endpoint.php

160 lines 4.1 KB

Raw Download Zip

1	<?php
2	/**
3	* Endpoints: Base endpoint class
4	*
5	* @package Parsely
6	* @since 3.11.0
7	*/
8
9	declare(strict_types=1);
10
11	namespace Parsely\Endpoints;
12
13	use Parsely\Parsely;
14
15	use function Parsely\Utils\convert_endpoint_to_filter_key;
16
17	/**
18	* Base class for API endpoints.
19	*
20	* Most endpoint classes should derive from this class. Child classes must add a
21	* protected `ENDPOINT` constant.
22	*
23	* @since 3.2.0
24	* @since 3.11.0 Moved from Base_Endpoint_Remote into Base_Endpoint.
25	*
26	* @phpstan-import-type WP_HTTP_Request_Args from Parsely
27	*
28	* @phpstan-type API_Error array{
29	* code: int,
30	* message: string,
31	* htmlMessage: string,
32	* }
33	*/
34	abstract class Base_Endpoint {
35	protected const ENDPOINT = '';
36
37	/**
38	* The default user capability needed to access endpoints.
39	*
40	* @since 3.14.0
41	*
42	* @var string
43	*/
44	protected const DEFAULT_ACCESS_CAPABILITY = 'publish_posts';
45
46	/**
47	* Parsely Instance.
48	*
49	* @since 3.11.0 Moved from Base_Endpoint_Remote into Base_Endpoint.
50	*
51	* @var Parsely
52	*/
53	protected $parsely;
54
55	/**
56	* Returns whether the endpoint is available for access by the current
57	* user.
58	*
59	* @since 3.14.0 Replaced `is_public_endpoint`, `user_capability` and `permission_callback()`.
60	*
61	* @return bool
62	*/
63	abstract public function is_available_to_current_user(): bool;
64
65	/**
66	* Constructor.
67	*
68	* @param Parsely $parsely Parsely instance.
69	*
70	* @since 3.2.0
71	* @since 3.7.0 Added user capability checks based on `is_public_endpoint` attribute.
72	* @since 3.11.0 Moved from Base_Endpoint_Remote into Base_Endpoint.
73	* @since 3.14.0 Moved capability filters functionality outside of the constructor.
74	*/
75	public function __construct( Parsely $parsely ) {
76	$this->parsely = $parsely;
77	}
78
79	/**
80	* Returns the user capability allowing access to the endpoint, after having
81	* applied capability filters.
82	*
83	* `DEFAULT_ACCESS_CAPABILITY` is not passed here by default, to allow for
84	* a more explicit declaration in child classes.
85	*
86	* @since 3.14.0
87	*
88	* @param string $capability The original capability allowing access.
89	* @return string The capability allowing access after applying the filters.
90	*/
91	protected function apply_capability_filters( string $capability ): string {
92	/**
93	* Filter to change the default user capability for all private endpoints.
94	*
95	* @var string
96	*/
97	$default_user_capability = apply_filters(
98	'wp_parsely_user_capability_for_all_private_apis',
99	$capability
100	);
101
102	/**
103	* Filter to change the user capability for the specific endpoint.
104	*
105	* @var string
106	*/
107	$endpoint_specific_user_capability = apply_filters(
108	'wp_parsely_user_capability_for_' . convert_endpoint_to_filter_key( static::ENDPOINT ) . '_api',
109	$default_user_capability
110	);
111
112	return $endpoint_specific_user_capability;
113	}
114
115	/**
116	* Registers the endpoint's WP REST route.
117	*
118	* @since 3.11.0 Moved from Base_Endpoint_Remote into Base_Endpoint.
119	*
120	* @param string $endpoint The endpoint's route.
121	* @param string $callback The callback function to call when the endpoint is hit.
122	* @param array<string> $methods The HTTP methods to allow for the endpoint.
123	*/
124	public function register_endpoint(
125	string $endpoint,
126	string $callback,
127	array $methods = array( 'GET' )
128	): void {
129	if ( ! apply_filters( 'wp_parsely_enable_' . convert_endpoint_to_filter_key( $endpoint ) . '_api_proxy', true ) ) {
130	return;
131	}
132
133	$get_items_args = array(
134	'query' => array(
135	'default' => array(),
136	'sanitize_callback' => function ( array $query ) {
137	$sanitized_query = array();
138	foreach ( $query as $key => $value ) {
139	$sanitized_query[ sanitize_key( $key ) ] = sanitize_text_field( $value );
140	}
141
142	return $sanitized_query;
143	},
144	),
145	);
146
147	$rest_route_args = array(
148	array(
149	'methods' => $methods,
150	'callback' => array( $this, $callback ),
151	'permission_callback' => array( $this, 'is_available_to_current_user' ),
152	'args' => $get_items_args,
153	'show_in_index' => static::is_available_to_current_user(),
154	),
155	);
156
157	register_rest_route( 'wp-parsely/v1', $endpoint, $rest_route_args );
158	}
159	}
160