wp-parsely / src / rest-api / class-base-api-controller.php

class-base-api-controller.php in Parse.ly 3.18.0, at src/rest-api/class-base-api-controller.php

205 lines 4.1 KB

Raw Download Zip

1	<?php
2	/**
3	* Base API Controller
4	*
5	* @package Parsely
6	* @since 3.17.0
7	*/
8
9	declare(strict_types=1);
10
11	namespace Parsely\REST_API;
12
13	use Parsely\Parsely;
14
15	/**
16	* Base API Controller.
17	*
18	* Used to define the namespace, version, and endpoints for an API controller. API controllers
19	* should extend this class and implement the `init` method to register endpoints.
20	*
21	* @since 3.17.0
22	*/
23	abstract class Base_API_Controller {
24	/**
25	* The endpoints.
26	*
27	* @since 3.17.0
28	*
29	* @var array<string, Base_Endpoint>
30	*/
31	private $endpoints;
32
33	/**
34	* The Parsely instance.
35	*
36	* @since 3.17.0
37	*
38	* @var Parsely
39	*/
40	private $parsely;
41
42	/**
43	* Constructor.
44	*
45	* @since 3.17.0
46	*
47	* @param Parsely $parsely The Parsely instance.
48	*/
49	public function __construct( Parsely $parsely ) {
50	$this->parsely = $parsely;
51	$this->endpoints = array();
52	}
53
54	/**
55	* Initializes the API controller.
56	*
57	* This method should be overridden by child classes and used to register
58	* endpoints.
59	*
60	* @since 3.17.0
61	*
62	* @return void
63	*/
64	abstract protected function init(): void;
65
66	/**
67	* Gets the namespace for the API.
68	*
69	* This method should be overridden by child classes to define the namespace.
70	*
71	* @since 3.17.0
72	*
73	* @return string The namespace.
74	*/
75	abstract protected function get_namespace(): string;
76
77	/**
78	* Gets the version for the API.
79	*
80	* This method can be overridden by child classes to define the version.
81	*
82	* @since 3.17.0
83	*
84	* @return string The version.
85	*/
86	protected function get_version(): string {
87	return '';
88	}
89
90	/**
91	* Gets the route prefix, which acts as a namespace for the endpoints.
92	*
93	* This method can be overridden by child classes to define the route prefix.
94	*
95	* @since 3.17.0
96	*
97	* @return string The route prefix.
98	*/
99	public static function get_route_prefix(): string {
100	return '';
101	}
102
103	/**
104	* Returns the full namespace for the API, including the version if defined.
105	*
106	* @since 3.17.0
107	*
108	* @return string
109	*/
110	public function get_full_namespace(): string {
111	$namespace = $this->get_namespace();
112
113	if ( '' !== $this->get_version() ) {
114	$namespace .= '/' . $this->get_version();
115	}
116
117	return $namespace;
118	}
119
120	/**
121	* Gets the Parsely instance.
122	*
123	* @since 3.17.0
124	*
125	* @return Parsely The Parsely instance.
126	*/
127	public function get_parsely(): Parsely {
128	return $this->parsely;
129	}
130
131	/**
132	* Gets the registered endpoints.
133	*
134	* @since 3.17.0
135	*
136	* @return Base_Endpoint[] The registered endpoints.
137	*/
138	public function get_endpoints(): array {
139	return $this->endpoints;
140	}
141
142	/**
143	* Registers a single endpoint.
144	*
145	* @since 3.17.0
146	*
147	* @param Base_Endpoint $endpoint The endpoint to register.
148	*/
149	protected function register_endpoint( Base_Endpoint $endpoint ): void {
150	$this->endpoints[ $endpoint->get_endpoint_slug() ] = $endpoint;
151	$endpoint->init();
152	}
153
154	/**
155	* Registers multiple endpoints.
156	*
157	* @since 3.17.0
158	*
159	* @param Base_Endpoint[] $endpoints The endpoints to register.
160	*/
161	protected function register_endpoints( array $endpoints ): void {
162	foreach ( $endpoints as $endpoint ) {
163	$this->register_endpoint( $endpoint );
164	}
165	}
166
167	/**
168	* Prefixes a route with the route prefix.
169	*
170	* @since 3.17.0
171	*
172	* @param string $route The route to prefix.
173	* @return string The prefixed route.
174	*/
175	public function prefix_route( string $route ): string {
176	if ( '' === static::get_route_prefix() ) {
177	return $route;
178	}
179
180	return static::get_route_prefix() . '/' . $route;
181	}
182
183	/**
184	* Returns a specific endpoint by name.
185	*
186	* @since 3.17.0
187	*
188	* @param string $endpoint The endpoint name/path.
189	* @return Base_Endpoint\|null The endpoint object, or null if not found.
190	*/
191	protected function get_endpoint( string $endpoint ): ?Base_Endpoint {
192	return $this->endpoints[ $endpoint ] ?? null;
193	}
194
195	/**
196	* Checks if a specific endpoint is available to the current user.
197	*
198	* @since 3.17.0
199	*
200	* @param string $endpoint The endpoint to check.
201	* @return bool True if the controller is available to the current user, false otherwise.
202	*/
203	abstract public function is_available_to_current_user( string $endpoint ): bool;
204	}
205