redirection / api / api-group.php

api-group.php in Redirection 5.6.0, at api/api-group.php

372 lines 10.8 KB

Raw Download Zip

1	<?php
2
3	/**
4	* @api {get} /redirection/v1/group Get groups
5	* @apiName GetGroups
6	* @apiDescription Get a paged list of groups based after applying a set of filters and result ordering.
7	* @apiGroup Group
8	*
9	* @apiUse GroupQueryParams
10	*
11	* @apiUse GroupList
12	* @apiUse 401Error
13	* @apiUse 404Error
14	*/
15
16	/**
17	* @api {post} /redirection/v1/group Create group
18	* @apiName CreateGroup
19	* @apiDescription Create a new group, and return a paged list of groups.
20	* @apiGroup Group
21	*
22	* @apiUse GroupItem
23	* @apiUse GroupQueryParams
24	*
25	* @apiUse GroupList
26	* @apiUse 401Error
27	* @apiUse 404Error
28	* @apiError (Error 400) redirect_group_invalid Invalid group or parameters
29	* @apiErrorExample {json} 404 Error Response:
30	* HTTP/1.1 400 Bad Request
31	* {
32	* "code": "redirect_group_invalid",
33	* "message": "Invalid group or parameters"
34	* }
35	*/
36
37	/**
38	* @api {post} /redirection/v1/group/:id Update group
39	* @apiName UpdateGroup
40	* @apiDescription Update an existing group.
41	* @apiGroup Group
42	*
43	* @apiParam (URL) {Integer} :id Group ID to update
44	* @apiUse GroupList
45	*
46	* @apiSuccess {String} item The updated group
47	* @apiSuccess {Integer} item.id ID of group
48	* @apiSuccess {String} item.name Name of this group
49	* @apiSuccess {Boolean} item.enabled `true` if group (and redirects) are enabled, `false` otherwise
50	* @apiSuccess {Integer} item.redirects Number of redirects in this group
51	* @apiSuccess {String} item.moduleName Name of the module this group belongs to
52	* @apiSuccess {Integer} item.module_id ID of the module this group belongs to
53	*
54	* @apiUse 401Error
55	* @apiUse 404Error
56	*
57	* @apiError (Error 400) redirect_group_invalid Invalid group or parameters
58	* @apiErrorExample {json} 404 Error Response:
59	* HTTP/1.1 400 Bad Request
60	* {
61	* "code": "redirect_group_invalid",
62	* "message": "Invalid group or parameters"
63	* }
64	*/
65
66	/**
67	* @api {post} /redirection/v1/bulk/group/:type Bulk action
68	* @apiName BulkAction
69	* @apiDescription Enable, disable, and delete a set of groups. The endpoint will return the next page of results after.
70	* performing the action, based on the supplied query parameters. This information can be used to refresh a list displayed to the client.
71	* @apiGroup Group
72	*
73	* @apiParam (URL) {String="delete","enable","disable"} :type Type of bulk action that is applied to every group ID.
74	* Enabling or disabling a group will also enable or disable all redirects in that group
75	*
76	* @apiParam (Query Parameter) {String[]} [items] Array of group IDs to perform the action on
77	* @apiParam (Query Parameter) {Boolean=false} [global] Perform action globally using the filter parameters
78	* @apiUse GroupQueryParams
79	*
80	* @apiUse GroupList
81	* @apiUse 401Error
82	* @apiUse 404Error
83	* @apiUse 400MissingError
84	*/
85
86	/**
87	* @apiDefine GroupQueryParams
88	*
89	* @apiParam (Query Parameter) {String} [filterBy[name]] Filter the results by the supplied name
90	* @apiParam (Query Parameter) {String="enabled","disabled"} [filterBy[status]] Filter the results by the supplied status
91	* @apiParam (Query Parameter) {Integer="1","2","3"} [filterBy[module]] Filter the results by the supplied module ID
92	* @apiParam (Query Parameter) {String="name"} [orderby] Order in which results are returned
93	* @apiParam (Query Parameter) {String="asc","desc"} [direction=desc] Direction to order the results by (ascending or descending)
94	* @apiParam (Query Parameter) {Integer{1...200}} [per_page=25] Number of results per request
95	* @apiParam (Query Parameter) {Integer} [page=0] Current page of results
96	*/
97
98	/**
99	* @apiDefine GroupItem
100	*
101	* @apiParam (JSON Body) {String} name Name of the group
102	* @apiParam (JSON Body) {Integer="1","2","3"} moduleID Module ID of the group, with 1 being WordPress, 2 is Apache, and 3 is Nginx
103	*/
104
105	/**
106	* @apiDefine GroupList
107	*
108	* @apiSuccess {Object[]} items Array of group objects
109	* @apiSuccess {Integer} items.id ID of group
110	* @apiSuccess {String} items.name Name of this group
111	* @apiSuccess {Boolean} items.enabled `true` if group (and redirects) are enabled, `false` otherwise
112	* @apiSuccess {Integer} items.redirects Number of redirects in this group
113	* @apiSuccess {String} items.moduleName Name of the module this group belongs to
114	* @apiSuccess {Integer} items.module_id ID of the module this group belongs to
115	* @apiSuccess {Integer} total Number of items
116	*
117	* @apiSuccessExample {json} Success 200:
118	* HTTP/1.1 200 OK
119	* {
120	* "items": [
121	* {
122	* "id": 3,
123	* "enabled": true,
124	* "moduleName": "WordPress",
125	* "module_id": 1,
126	* "name": "Redirections",
127	* "redirects": 0,
128	* }
129	* ],
130	* "total": 1
131	* }
132	*/
133
134	/**
135	* Group API endpoint
136	*
137	* @phpstan-type GroupListResponse array{
138	* items: list<array<string, mixed>>,
139	* total: int
140	* }
141	*/
142	class Redirection_Api_Group extends Redirection_Api_Filter_Route {
143	/**
144	* 404 API endpoint constructor
145	*
146	* @param string $api_namespace Namespace.
147	*/
148	public function __construct( $api_namespace ) {
149	$orders = [ 'name', 'id', '' ];
150	$filters = [ 'status', 'module', 'name' ];
151
152	// GET /group - List groups
153	// POST /group - Create group
154	register_rest_route(
155	$api_namespace,
156	'/group',
157	[
158	[
159	'methods' => WP_REST_Server::READABLE,
160	'callback' => [ $this, 'route_list' ],
161	'permission_callback' => [ $this, 'permission_callback_manage' ],
162	'args' => $this->get_filter_args( $orders, $filters ),
163	],
164	[
165	'methods' => WP_REST_Server::EDITABLE,
166	'callback' => [ $this, 'route_create' ],
167	'permission_callback' => [ $this, 'permission_callback_add' ],
168	'args' => array_merge(
169	$this->get_filter_args( $orders, $filters ),
170	$this->get_group_args()
171	),
172	],
173	]
174	);
175
176	// POST /group/:id - Update group
177	register_rest_route(
178	$api_namespace,
179	'/group/(?P<id>[\d]+)',
180	[
181	[
182	'methods' => WP_REST_Server::EDITABLE,
183	'callback' => [ $this, 'route_update' ],
184	'permission_callback' => [ $this, 'permission_callback_add' ],
185	'args' => $this->get_group_args(),
186	],
187	]
188	);
189
190	// POST /bulk/group/:bulk - Bulk actions on groups
191	register_rest_route(
192	$api_namespace,
193	'/bulk/group/(?P<bulk>delete\|enable\|disable)',
194	[
195	[
196	'methods' => WP_REST_Server::EDITABLE,
197	'callback' => [ $this, 'route_bulk' ],
198	'permission_callback' => [ $this, 'permission_callback_bulk' ],
199	'args' => array_merge(
200	$this->get_filter_args( $orders, $filters ),
201	[
202	'items' => [
203	'description' => 'Comma separated list of item IDs to perform action on',
204	'type' => 'array',
205	'items' => [
206	'description' => 'Item ID',
207	'type' => [ 'string', 'number' ],
208	],
209	],
210	]
211	),
212	],
213	]
214	);
215	}
216
217	/**
218	* Checks a manage capability
219	*
220	* Access to group data is required by the CAP_GROUP_MANAGE and CAP_REDIRECT_MANAGE caps
221	*
222	* @param WP_REST_Request<array<string, mixed>> $request Request.
223	* @return bool
224	*/
225	public function permission_callback_manage( WP_REST_Request $request ) {
226	return Redirection_Capabilities::has_access( Redirection_Capabilities::CAP_GROUP_MANAGE ) \|\| Redirection_Capabilities::has_access( Redirection_Capabilities::CAP_REDIRECT_MANAGE );
227	}
228
229	/**
230	* Checks a bulk capability
231	*
232	* @param WP_REST_Request<array<string, mixed>> $request Request.
233	* @return bool
234	*/
235	public function permission_callback_bulk( WP_REST_Request $request ) {
236	if ( $request['bulk'] === 'delete' ) {
237	return Redirection_Capabilities::has_access( Redirection_Capabilities::CAP_GROUP_DELETE );
238	}
239
240	return $this->permission_callback_add( $request );
241	}
242
243	/**
244	* Checks a create capability
245	*
246	* @param WP_REST_Request<array<string, mixed>> $request Request.
247	* @return bool
248	*/
249	public function permission_callback_add( WP_REST_Request $request ) {
250	return Redirection_Capabilities::has_access( Redirection_Capabilities::CAP_GROUP_ADD );
251	}
252
253	/**
254	* @return array<string, array<string, mixed>>
255	*/
256	private function get_group_args() {
257	return array(
258	'moduleId' => array(
259	'description' => 'Module ID',
260	'type' => 'integer',
261	'minimum' => 0,
262	'maximum' => 3,
263	'required' => true,
264	),
265	'name' => array(
266	'description' => 'Group name',
267	'type' => 'string',
268	'required' => true,
269	),
270	'status' => [
271	'description' => 'Status of the group',
272	],
273	);
274	}
275
276	/**
277	* Get group list
278	*
279	* @param WP_REST_Request<array<string, mixed>> $request The request.
280	* @return GroupListResponse
281	*/
282	public function route_list( WP_REST_Request $request ) {
283	return Red_Group::get_filtered( $request->get_params() ); // @phpstan-ignore-line
284	}
285
286	/**
287	* Create a group
288	*
289	* @param WP_REST_Request<array<string, mixed>> $request The request.
290	* @return GroupListResponse\|WP_Error
291	*/
292	public function route_create( WP_REST_Request $request ) {
293	$params = $request->get_params();
294	$name = '';
295	$module = 0;
296
297	if ( isset( $params['name'] ) ) {
298	$name = sanitize_text_field( $params['name'] );
299	}
300
301	if ( isset( $params['moduleId'] ) ) {
302	$module = intval( $params['moduleId'], 10 );
303	}
304
305	$group = Red_Group::create( $name, $module );
306
307	if ( $group !== false ) {
308	return Red_Group::get_filtered( $params ); // @phpstan-ignore-line
309	}
310
311	return $this->add_error_details( new WP_Error( 'redirect_group_invalid', 'Invalid group or parameters' ), __LINE__ );
312	}
313
314	/**
315	* Update a group
316	*
317	* @param WP_REST_Request<array<string, mixed>> $request The request.
318	* @return array{item: array<string, mixed>}\|WP_Error
319	*/
320	public function route_update( WP_REST_Request $request ) {
321	$params = $request->get_params();
322	$group = Red_Group::get( intval( $request['id'], 10 ) );
323
324	if ( $group !== false ) {
325	$result = $group->update( $params );
326
327	if ( $result !== false ) {
328	return array( 'item' => $group->to_json() );
329	}
330	}
331
332	return $this->add_error_details( new WP_Error( 'redirect_group_invalid', 'Invalid group details' ), __LINE__ );
333	}
334
335	/**
336	* Perform action on groups
337	*
338	* @param WP_REST_Request<array<string, mixed>> $request The request.
339	* @return GroupListResponse\|WP_Error
340	*/
341	public function route_bulk( WP_REST_Request $request ) {
342	$params = $request->get_params();
343	$action = $request['bulk'];
344
345	$items = [];
346	if ( isset( $params['items'] ) && is_array( $params['items'] ) ) {
347	// Array of integers, sanitized below
348	$items = $params['items'];
349	} elseif ( isset( $params['global'] ) && $params['global'] !== false ) {
350	// Groups have additional actions that fire and so we need to action them individually
351	$groups = Red_Group::get_all( $params );
352	$items = array_column( $groups, 'id' );
353	}
354
355	foreach ( $items as $item ) {
356	$group = Red_Group::get( intval( $item, 10 ) );
357
358	if ( is_object( $group ) ) {
359	if ( $action === 'delete' ) {
360	$group->delete();
361	} elseif ( $action === 'disable' ) {
362	$group->disable();
363	} elseif ( $action === 'enable' ) {
364	$group->enable();
365	}
366	}
367	}
368
369	return $this->route_list( $request );
370	}
371	}
372