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

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

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