redirection / api / api-log.php

api-log.php in Redirection 5.8.1, at api/api-log.php

235 lines 8.1 KB

Raw Download Zip

1	<?php
2
3	/**
4	* @api {get} /redirection/v1/log Get logs
5	* @apiName GetLogs
6	* @apiDescription Get a paged list of redirect logs after applying a set of filters and result ordering.
7	* @apiGroup Log
8	*
9	* @apiUse LogQueryParams
10	*
11	* @apiUse LogList
12	* @apiUse 401Error
13	* @apiUse 404Error
14	*/
15
16	/**
17	* @api {post} /redirection/v1/log Delete logs
18	* @apiName DeleteLogs
19	* @apiDescription Delete logs by filter. If no filter is supplied then all entries will be deleted. The endpoint will return the next page of results after.
20	* performing the action, based on the supplied query parameters. This information can be used to refresh a list displayed to the client.
21	* @apiGroup Log
22	*
23	* @apiParam (Query Parameter) {String} filterBy[ip] Filter the results by the supplied IP
24	* @apiParam (Query Parameter) {String} filterBy[url] Filter the results by the supplied URL
25	* @apiParam (Query Parameter) {String} filterBy[url-exact] Filter the results by the exact URL (not a substring match, as per `url`)
26	* @apiParam (Query Parameter) {String} filterBy[referrer] Filter the results by the supplied referrer
27	* @apiParam (Query Parameter) {String} filterBy[agent] Filter the results by the supplied user agent
28	* @apiParam (Query Parameter) {String} filterBy[target] Filter the results by the supplied redirect target
29	*
30	* @apiUse LogList
31	* @apiUse 401Error
32	* @apiUse 404Error
33	*/
34
35	/**
36	* @api {post} /redirection/v1/bulk/log/:type Bulk action
37	* @apiName BulkAction
38	* @apiDescription Delete logs by ID
39	* @apiGroup Log
40	*
41	* @apiParam (URL) {String="delete"} :type Type of bulk action that is applied to every log ID.
42	* @apiParam (Query Parameter) {String[]} [items] Array of group IDs to perform the action on
43	* @apiParam (Query Parameter) {Boolean=false} [global] Perform action globally using the filter parameters
44	* @apiUse LogQueryParams
45	*
46	* @apiUse LogList
47	* @apiUse 401Error
48	* @apiUse 404Error
49	* @apiUse 400MissingError
50	*/
51
52	/**
53	* @apiDefine LogQueryParams Log query parameters
54	*
55	* @apiParam (Query Parameter) {String} [filterBy[ip]] Filter the results by the supplied IP
56	* @apiParam (Query Parameter) {String} [filterBy[url]] Filter the results by the supplied URL
57	* @apiParam (Query Parameter) {String} [filterBy[url-]exact] Filter the results by the exact URL (not a substring match, as per `url`)
58	* @apiParam (Query Parameter) {String} [filterBy[referrer]] Filter the results by the supplied referrer
59	* @apiParam (Query Parameter) {String} [filterBy[agent]] Filter the results by the supplied user agent
60	* @apiParam (Query Parameter) {String} [filterBy[target]] Filter the results by the supplied redirect target
61	* @apiParam (Query Parameter) {String} [filterBy[domain]] Filter the results by the supplied domain name
62	* @apiParam (Query Parameter) {String} [filterBy[redirect_by]] Filter the results by the redirect agent
63	* @apiParam (Query Parameter) {String="head","get","post"} [filterBy[method]] Filter the results by the supplied HTTP request method
64	* @apiParam (Query Parameter) {String="ip","url"} [orderby] Order by IP or URL
65	* @apiParam (Query Parameter) {String="asc","desc"} [direction=desc] Direction to order the results by (ascending or descending)
66	* @apiParam (Query Parameter) {Integer{1...200}} [per_page=25] Number of results per request
67	* @apiParam (Query Parameter) {Integer} [page=0] Current page of results
68	* @apiParam (Query Parameter) {String="ip","url"} [groupBy] Group by IP or URL
69	*/
70
71	/**
72	* @apiDefine LogList
73	*
74	* @apiSuccess {Object[]} items Array of log objects
75	* @apiSuccess {Integer} items.id ID of log entry
76	* @apiSuccess {String} items.created Date the log entry was recorded
77	* @apiSuccess {Integer} items.created_time Unix time value for `created`
78	* @apiSuccess {Integer} items.url The requested URL that caused the log entry
79	* @apiSuccess {String} items.agent User agent of the client initiating the request
80	* @apiSuccess {Integer} items.referrer Referrer of the client initiating the request
81	* @apiSuccess {Integer} total Number of items
82	*
83	* @apiSuccessExample {json} Success 200:
84	* HTTP/1.1 200 OK
85	* {
86	* "items": [
87	* {
88	* "id": 3,
89	* "created": "2019-01-01 12:12:00,
90	* "created_time": "12345678",
91	* "url": "/the-url",
92	* "agent": "FancyBrowser",
93	* "referrer": "http://site.com/previous/,
94	* }
95	* ],
96	* "total": 1
97	* }
98	*/
99
100	/**
101	* @phpstan-type RedirectLogResponse array{
102	* items: list<array<string, mixed>\|object>,
103	* total: int
104	* }
105	*
106	* Log API endpoint
107	*/
108	class Redirection_Api_Log extends Redirection_Api_Filter_Route {
109	/**
110	* Log API endpoint constructor
111	*
112	* @param non-falsy-string $api_namespace Namespace.
113	*/
114	public function __construct( $api_namespace ) {
115	$orders = [ 'url', 'ip', 'total', 'count', '' ];
116	$filters = [ 'ip', 'url-exact', 'referrer', 'agent', 'url', 'target', 'domain', 'method', 'http', 'redirect_by' ];
117
118	// GET /log - Get redirect logs
119	register_rest_route(
120	$api_namespace,
121	'/log',
122	[
123	[
124	'methods' => WP_REST_Server::READABLE,
125	'callback' => [ $this, 'route_log' ],
126	'permission_callback' => [ $this, 'permission_callback_manage' ],
127	'args' => $this->get_filter_args( $orders, $filters ),
128	],
129	]
130	);
131
132	// POST /bulk/log/:bulk - Bulk delete logs
133	register_rest_route(
134	$api_namespace,
135	'/bulk/log/(?P<bulk>delete)',
136	[
137	[
138	'methods' => WP_REST_Server::EDITABLE,
139	'callback' => [ $this, 'route_bulk' ],
140	'permission_callback' => [ $this, 'permission_callback_delete' ],
141	'args' => array_merge(
142	$this->get_filter_args( $orders, $filters ),
143	[
144	'items' => [
145	'description' => 'Comma separated list of item IDs to perform action on',
146	'type' => 'array',
147	'items' => [
148	'description' => 'Item ID',
149	'type' => [ 'string', 'number' ],
150	],
151	],
152	]
153	),
154	],
155	]
156	);
157	}
158
159	/**
160	* Checks a manage capability
161	*
162	* @param WP_REST_Request<array<string, mixed>> $request Request.
163	* @return bool
164	*/
165	public function permission_callback_manage( WP_REST_Request $request ) {
166	return Redirection_Capabilities::has_access( Redirection_Capabilities::CAP_LOG_MANAGE );
167	}
168
169	/**
170	* Checks a delete capability
171	*
172	* @param WP_REST_Request<array<string, mixed>> $request Request.
173	* @return bool
174	*/
175	public function permission_callback_delete( WP_REST_Request $request ) {
176	return Redirection_Capabilities::has_access( Redirection_Capabilities::CAP_LOG_DELETE );
177	}
178
179	/**
180	* Get log list
181	*
182	* @param WP_REST_Request<array<string, mixed>> $request The request.
183	* @return RedirectLogResponse
184	*/
185	public function route_log( WP_REST_Request $request ) {
186	return $this->get_logs( $request->get_params() );
187	}
188
189	/**
190	* Perform bulk action on logs
191	*
192	* @param WP_REST_Request<array<string, mixed>> $request The request.
193	* @return RedirectLogResponse
194	*/
195	public function route_bulk( WP_REST_Request $request ) {
196	$params = $request->get_params();
197
198	if ( isset( $params['items'] ) && is_array( $params['items'] ) && count( $params['items'] ) > 0 ) {
199	$items = $params['items'];
200
201	foreach ( $items as $item ) {
202	if ( is_numeric( $item ) ) {
203	Red_Redirect_Log::delete( intval( $item, 10 ) );
204	} elseif ( isset( $params['groupBy'] ) ) {
205	$delete_by = 'url-exact';
206
207	if ( in_array( $params['groupBy'], [ 'ip', 'agent' ], true ) ) {
208	$delete_by = sanitize_text_field( $params['groupBy'] );
209	}
210
211	Red_Redirect_Log::delete_all( [ 'filterBy' => [ $delete_by => $item ] ] ); // @phpstan-ignore-line
212	}
213	}
214	} elseif ( isset( $params['global'] ) && $params['global'] !== false ) {
215	Red_Redirect_Log::delete_all( $params );
216	}
217
218	return $this->route_log( $request );
219	}
220
221	/**
222	* Get redirect logs
223	*
224	* @param array<string, mixed> $params The request parameters.
225	* @return RedirectLogResponse
226	*/
227	private function get_logs( array $params ) {
228	if ( isset( $params['groupBy'] ) && in_array( $params['groupBy'], [ 'ip', 'url', 'agent' ], true ) ) {
229	return Red_Redirect_Log::get_grouped( sanitize_text_field( $params['groupBy'] ), $params );
230	}
231
232	return Red_Redirect_Log::get_filtered( $params );
233	}
234	}
235