gutenberg / lib / experimental / dashboard-widgets / class-wp-rest-widget-modules-controller.php

class-wp-rest-widget-modules-controller.php in Gutenberg 23.3.1, at lib/experimental/dashboard-widgets/class-wp-rest-widget-modules-controller.php

257 lines 8.1 KB

Raw Download Zip

1	<?php
2	/**
3	* Widget Modules REST API: WP_REST_Widget_Modules_Controller class.
4	*
5	* @package gutenberg
6	*/
7
8	if ( ! class_exists( 'WP_REST_Widget_Modules_Controller' ) ) {
9
10	/**
11	* Internal REST controller exposing the widget type registry.
12	*
13	* Reads from `WP_Widget_Type_Registry`. Read-only collection and item
14	* endpoints. Render and encode endpoints are intentionally absent:
15	* consumers import the render module on the client and render in JS,
16	* so there is no server-rendered HTML to expose.
17	*
18	* The endpoint lives at `/wp/v2/widget-modules` because the entity
19	* `(kind: 'root', name: 'widgetType')` and the path
20	* `/wp/v2/widget-types` are already taken by the legacy widgets API.
21	*/
22	class WP_REST_Widget_Modules_Controller extends WP_REST_Controller {
23
24	/**
25	* Constructor.
26	*/
27	public function __construct() {
28	$this->namespace = 'wp/v2';
29	$this->rest_base = 'widget-modules';
30	}
31
32	/**
33	* Registers the widget module routes.
34	*/
35	public function register_routes() {
36	register_rest_route(
37	$this->namespace,
38	'/' . $this->rest_base,
39	array(
40	array(
41	'methods' => WP_REST_Server::READABLE,
42	'callback' => array( $this, 'get_items' ),
43	'permission_callback' => array( $this, 'get_items_permissions_check' ),
44	'args' => $this->get_collection_params(),
45	),
46	'schema' => array( $this, 'get_public_item_schema' ),
47	)
48	);
49
50	register_rest_route(
51	$this->namespace,
52	'/' . $this->rest_base . '/(?P<id>[a-z0-9-]+\/[a-z0-9-]+)',
53	array(
54	'args' => array(
55	'id' => array(
56	'description' => __( 'Widget module name including namespace.', 'gutenberg' ),
57	'type' => 'string',
58	),
59	),
60	array(
61	'methods' => WP_REST_Server::READABLE,
62	'callback' => array( $this, 'get_item' ),
63	'permission_callback' => array( $this, 'get_item_permissions_check' ),
64	'args' => array(),
65	),
66	'schema' => array( $this, 'get_public_item_schema' ),
67	)
68	);
69	}
70
71	/**
72	* Checks whether a given request has permission to read widget
73	* modules.
74	*
75	* @param WP_REST_Request $request Full details about the request.
76	* @return true\|WP_Error True if the request has read access, WP_Error
77	* otherwise.
78	*/
79	public function get_items_permissions_check( $request ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
80	return $this->check_read_permission();
81	}
82
83	/**
84	* Checks whether a given request has permission to read a single
85	* widget module.
86	*
87	* @param WP_REST_Request $request Full details about the request.
88	* @return true\|WP_Error True if the request has read access, WP_Error
89	* otherwise.
90	*/
91	public function get_item_permissions_check( $request ) {
92	$check = $this->check_read_permission();
93	if ( is_wp_error( $check ) ) {
94	return $check;
95	}
96
97	$widget_type = WP_Widget_Type_Registry::get_instance()->get_registered( $request['id'] );
98	if ( null === $widget_type ) {
99	return new WP_Error(
100	'rest_widget_module_invalid',
101	__( 'Invalid widget module name.', 'gutenberg' ),
102	array( 'status' => 404 )
103	);
104	}
105
106	return true;
107	}
108
109	/**
110	* Verifies the user has the basic read capability.
111	*
112	* Widget modules are not sensitive data; they describe what is
113	* available to render. Gating at the same level as the dashboard
114	* page menu (which requires `read`) keeps the surface consistent.
115	*
116	* @return true\|WP_Error True if the request is allowed, WP_Error
117	* otherwise.
118	*/
119	protected function check_read_permission() {
120	if ( ! current_user_can( 'read' ) ) {
121	return new WP_Error(
122	'rest_cannot_view_widget_modules',
123	__( 'Sorry, you are not allowed to view widget modules.', 'gutenberg' ),
124	array( 'status' => rest_authorization_required_code() )
125	);
126	}
127
128	return true;
129	}
130
131	/**
132	* Retrieves the list of all registered widget modules.
133	*
134	* @param WP_REST_Request $request Full details about the request.
135	* @return WP_REST_Response Response object on success.
136	*/
137	public function get_items( $request ) {
138	$registered = WP_Widget_Type_Registry::get_instance()->get_all_registered();
139	$data = array();
140
141	foreach ( $registered as $widget_type ) {
142	$item = $this->prepare_item_for_response( $widget_type, $request );
143	$data[] = $this->prepare_response_for_collection( $item );
144	}
145
146	return rest_ensure_response( $data );
147	}
148
149	/**
150	* Retrieves a single widget module from the collection.
151	*
152	* @param WP_REST_Request $request Full details about the request.
153	* @return WP_REST_Response\|WP_Error Response object on success, or
154	* WP_Error on failure.
155	*/
156	public function get_item( $request ) {
157	$widget_type = WP_Widget_Type_Registry::get_instance()->get_registered( $request['id'] );
158	if ( null === $widget_type ) {
159	return new WP_Error(
160	'rest_widget_module_invalid',
161	__( 'Invalid widget module name.', 'gutenberg' ),
162	array( 'status' => 404 )
163	);
164	}
165
166	return rest_ensure_response( $this->prepare_item_for_response( $widget_type, $request ) );
167	}
168
169	/**
170	* Prepares a widget type object for serialization.
171	*
172	* @param WP_Widget_Type $item Widget type instance.
173	* @param WP_REST_Request $request Full details about the request.
174	* @return WP_REST_Response Response object containing the serialized
175	* widget module data.
176	*/
177	public function prepare_item_for_response( $item, $request ) {
178	$widget_type = $item;
179	$fields = $this->get_fields_for_response( $request );
180	$data = array();
181
182	if ( rest_is_field_included( 'name', $fields ) ) {
183	$data['name'] = $widget_type->name;
184	}
185
186	if ( rest_is_field_included( 'render_module', $fields ) ) {
187	$data['render_module'] = $widget_type->render_module;
188	}
189
190	if ( rest_is_field_included( 'widget_module', $fields ) ) {
191	$data['widget_module'] = $widget_type->widget_module;
192	}
193
194	if ( rest_is_field_included( 'presentation', $fields ) ) {
195	$data['presentation'] = $widget_type->presentation;
196	}
197
198	$context = ! empty( $request['context'] ) ? $request['context'] : 'view';
199	$data = $this->add_additional_fields_to_object( $data, $request );
200	$data = $this->filter_response_by_context( $data, $context );
201
202	return rest_ensure_response( $data );
203	}
204
205	/**
206	* Retrieves the widget module schema, conforming to JSON Schema.
207	*
208	* @return array Item schema data.
209	*/
210	public function get_item_schema() {
211	if ( $this->schema ) {
212	return $this->add_additional_fields_schema( $this->schema );
213	}
214
215	$schema = array(
216	'$schema' => 'http://json-schema.org/draft-04/schema#',
217	'title' => 'widget-module',
218	'type' => 'object',
219	'properties' => array(
220	'name' => array(
221	'description' => __( 'Widget module name including namespace.', 'gutenberg' ),
222	'type' => 'string',
223	'context' => array( 'view', 'edit', 'embed' ),
224	'readonly' => true,
225	),
226
227	'render_module' => array(
228	'description' => __( 'Script-module handle for the widget render entry point.', 'gutenberg' ),
229	'type' => array( 'string', 'null' ),
230	'context' => array( 'view', 'edit', 'embed' ),
231	'readonly' => true,
232	),
233
234	'widget_module' => array(
235	'description' => __( 'Script-module handle for the widget metadata entry point.', 'gutenberg' ),
236	'type' => array( 'string', 'null' ),
237	'context' => array( 'view', 'edit', 'embed' ),
238	'readonly' => true,
239	),
240
241	'presentation' => array(
242	'description' => __( 'Authoring intent about how the widget wants to render.', 'gutenberg' ),
243	'type' => array( 'string', 'null' ),
244	'enum' => array_merge( WP_Widget_Type::PRESENTATION_VALUES, array( null ) ),
245	'context' => array( 'view', 'edit', 'embed' ),
246	'readonly' => true,
247	),
248	),
249	);
250
251	$this->schema = $schema;
252
253	return $this->add_additional_fields_schema( $this->schema );
254	}
255	}
256	}
257