class.wpcom-json-api-list-comments-endpoint.php — Jetpack – WP Security, Backup, Speed, & Growth 15.9-a.3

jetpack / json-endpoints / class.wpcom-json-api-list-comments-endpoint.php

jetpack / json-endpoints Last commit date

class.wpcom-json-api-list-comments-endpoint.php

387 lines

1	<?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName
2
3	if ( ! defined( 'ABSPATH' ) ) {
4	exit( 0 );
5	}
6
7	/**
8	* Comments Walker Class.
9	*/
10	class WPCOM_JSON_API_List_Comments_Walker extends Walker {
11
12	/**
13	* Tree type.
14	*
15	* @var string
16	*/
17	public $tree_type = 'comment';
18
19	/**
20	* Database fields.
21	*
22	* @var array
23	*/
24	public $db_fields = array(
25	'parent' => 'comment_parent',
26	'id' => 'comment_ID',
27	);
28
29	/**
30	* Start the element output.
31	*
32	* @param array $output - the output.
33	* @param object $object - the object.
34	* @param int $depth - depth.
35	* @param array $args - the arguments.
36	* @param int $current_object_id - the object ID.
37	*/
38	public function start_el( &$output, $object, $depth = 0, $args = array(), $current_object_id = 0 ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
39	if ( ! is_array( $output ) ) {
40	$output = array();
41	}
42
43	$output[] = $object->comment_ID;
44	}
45
46	/**
47	* Taken from WordPress's Walker_Comment::display_element()
48	*
49	* This function is designed to enhance Walker::display_element() to
50	* display children of higher nesting levels than selected inline on
51	* the highest depth level displayed. This prevents them being orphaned
52	* at the end of the comment list.
53	*
54	* Example: max_depth = 2, with 5 levels of nested content.
55	* 1
56	* 1.1
57	* 1.1.1
58	* 1.1.1.1
59	* 1.1.1.1.1
60	* 1.1.2
61	* 1.1.2.1
62	* 2
63	* 2.2
64	*
65	* @see Walker_Comment::display_element()
66	* @see Walker::display_element()
67	* @see wp_list_comments()
68	*
69	* @param object $element — Data object.
70	* @param array $children_elements - List of elements to continue traversing (passed by reference).
71	* @param int $max_depth — Max depth to traverse.
72	* @param int $depth — Depth of current element.
73	* @param array $args — An array of arguments.
74	* @param string $output — Used to append additional content (passed by reference).
75	*/
76	public function display_element( $element, &$children_elements, $max_depth, $depth, $args, &$output ) {
77
78	if ( ! $element ) {
79	return;
80	}
81
82	$id_field = $this->db_fields['id'];
83	$id = $element->$id_field;
84
85	parent::display_element( $element, $children_elements, $max_depth, $depth, $args, $output );
86
87	// If we're at the max depth, and the current element still has children, loop over those and display them at this level
88	// This is to prevent them being orphaned to the end of the list.
89	if ( $max_depth <= $depth + 1 && isset( $children_elements[ $id ] ) ) {
90	foreach ( $children_elements[ $id ] as $child ) {
91	$this->display_element( $child, $children_elements, $max_depth, $depth, $args, $output );
92	}
93
94	unset( $children_elements[ $id ] );
95	}
96	}
97	}
98
99	new WPCOM_JSON_API_List_Comments_Endpoint(
100	array(
101	'description' => 'Get a list of recent comments.',
102	'group' => 'comments',
103	'stat' => 'comments',
104
105	'method' => 'GET',
106	'path' => '/sites/%s/comments/',
107	'path_labels' => array(
108	'$site' => '(int\|string) Site ID or domain',
109	),
110
111	'allow_fallback_to_jetpack_blog_token' => true,
112
113	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/comments/?number=2',
114	)
115	);
116
117	new WPCOM_JSON_API_List_Comments_Endpoint(
118	array(
119	'description' => 'Get a list of recent comments on a post.',
120	'group' => 'comments',
121	'stat' => 'posts:1:replies',
122
123	'method' => 'GET',
124	'path' => '/sites/%s/posts/%d/replies/',
125	'path_labels' => array(
126	'$site' => '(int\|string) Site ID or domain',
127	'$post_ID' => '(int) The post ID',
128	),
129
130	'allow_fallback_to_jetpack_blog_token' => true,
131
132	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/posts/7/replies/?number=2',
133	)
134	);
135
136	/**
137	* List comment endpoint.
138	*
139	* /sites/%s/comments/ -> $blog_id
140	* /sites/%s/posts/%d/replies/ -> $blog_id, $post_id
141	* /sites/%s/comments/%d/replies/ -> $blog_id, $comment_id
142	*
143	* @todo permissions
144	*
145	* @phan-constructor-used-for-side-effects
146	*/
147	class WPCOM_JSON_API_List_Comments_Endpoint extends WPCOM_JSON_API_Comment_Endpoint { // phpcs:ignore
148
149	/**
150	* The response format.
151	*
152	* @var array
153	*/
154	public $response_format = array(
155	'found' => '(int) The total number of comments found that match the request (ignoring limits, offsets, and pagination).',
156	'site_ID' => '(int) The site ID',
157	'comments' => '(array:comment) An array of comment objects.',
158	);
159
160	/**
161	* Constructor function.
162	*
163	* @param array $args - the arguments.
164	*/
165	public function __construct( $args ) {
166	parent::__construct( $args );
167	$this->query = array_merge(
168	$this->query,
169	array(
170	'number' => '(int=20) The number of comments to return. Limit: 100. When using hierarchical=1, number refers to the number of top-level comments returned.',
171	'offset' => '(int=0) 0-indexed offset. Not available if using hierarchical=1.',
172	'page' => '(int) Return the Nth 1-indexed page of comments. Takes precedence over the <code>offset</code> parameter. When using hierarchical=1, pagination is a bit different. See the note on the number parameter.',
173	'order' => array(
174	'DESC' => 'Return comments in descending order from newest to oldest.',
175	'ASC' => 'Return comments in ascending order from oldest to newest.',
176	),
177	'hierarchical' => array(
178	'false' => '',
179	'true' => '(BETA) Order the comment list hierarchically.',
180	),
181	'after' => '(ISO 8601 datetime) Return comments dated on or after the specified datetime. Not available if using hierarchical=1.',
182	'before' => '(ISO 8601 datetime) Return comments dated on or before the specified datetime. Not available if using hierarchical=1.',
183	'type' => array(
184	'any' => 'Return all comments regardless of type.',
185	'comment' => 'Return only regular comments.',
186	'trackback' => 'Return only trackbacks.',
187	'pingback' => 'Return only pingbacks.',
188	'pings' => 'Return both trackbacks and pingbacks.',
189	),
190	'status' => array(
191	'approved' => 'Return only approved comments.',
192	'unapproved' => 'Return only comments in the moderation queue.',
193	'spam' => 'Return only comments marked as spam.',
194	'trash' => 'Return only comments in the trash.',
195	'all' => 'Return comments of all statuses.',
196	),
197	'author_wpcom_data' => array(
198	'false' => 'Do not add wpcom_id and wpcom_login fields to comment author responses (default)',
199	'true' => 'Add wpcom_id and wpcom_login fields to comment author responses',
200	),
201	)
202	);
203	}
204
205	/**
206	* The callback.
207	*
208	* @param string $path - the path.
209	* @param int $blog_id - the blog ID.
210	* @param int $object_id - the object ID.
211	*/
212	public function callback( $path = '', $blog_id = 0, $object_id = 0 ) {
213	$blog_id = $this->api->switch_to_blog_and_validate_user( $this->api->get_blog_id( $blog_id ) );
214	if ( is_wp_error( $blog_id ) ) {
215	return $blog_id;
216	}
217
218	$args = $this->query_args();
219
220	if ( $args['number'] < 1 ) {
221	$args['number'] = 20;
222	} elseif ( 100 < $args['number'] ) {
223	return new WP_Error( 'invalid_number', 'The NUMBER parameter must be less than or equal to 100.', 400 );
224	}
225
226	if ( str_contains( $path, '/posts/' ) ) {
227	// We're looking for comments of a particular post.
228	$post_id = $object_id;
229	$comment_id = 0;
230	} else {
231	// We're looking for comments for the whole blog, or replies to a single comment.
232	$comment_id = $object_id;
233	$post_id = 0;
234	}
235
236	// We can't efficiently get the number of replies to a single comment.
237	$count = false;
238	$found = -1;
239
240	if ( ! $comment_id ) {
241	// We can get comment counts for the whole site or for a single post, but only for certain queries.
242	if ( 'any' === $args['type'] && ! isset( $args['after'] ) && ! isset( $args['before'] ) ) {
243	$count = $this->api->wp_count_comments( $post_id );
244	}
245	}
246
247	switch ( $args['status'] ) {
248	case 'approved':
249	$status = 'approve';
250	if ( $count ) {
251	$found = $count->approved;
252	}
253	break;
254	default:
255	if ( ! current_user_can( 'edit_posts' ) ) {
256	return new WP_Error( 'unauthorized', 'User cannot read non-approved comments', 403 );
257	}
258	if ( 'unapproved' === $args['status'] ) {
259	$status = 'hold';
260	$count_status = 'moderated';
261	} elseif ( 'all' === $args['status'] ) {
262	$status = 'all';
263	$count_status = 'total_comments';
264	} else {
265	$status = $args['status'];
266	$count_status = $args['status'];
267	}
268	if ( $count ) {
269	$found = $count->$count_status;
270	}
271	}
272
273	/** This filter is documented in class.json-api.php */
274	$exclude = apply_filters(
275	'jetpack_api_exclude_comment_types',
276	array( 'order_note', 'webhook_delivery', 'review', 'action_log' )
277	);
278
279	$query = array(
280	'order' => $args['order'],
281	'type' => 'any' === $args['type'] ? false : $args['type'],
282	'status' => $status,
283	'type__not_in' => $exclude,
284	);
285
286	if ( isset( $args['page'] ) ) {
287	if ( $args['page'] < 1 ) {
288	$args['page'] = 1;
289	}
290	} elseif ( $args['offset'] < 0 ) {
291	$args['offset'] = 0;
292	}
293
294	if ( ! $args['hierarchical'] ) {
295	$query['number'] = $args['number'];
296
297	if ( isset( $args['page'] ) ) {
298	$query['offset'] = ( $args['page'] - 1 ) * $args['number'];
299	} else {
300	$query['offset'] = $args['offset'];
301	}
302
303	$is_before = isset( $args['before_gmt'] );
304	$is_after = isset( $args['after_gmt'] );
305
306	if ( $is_before \|\| $is_after ) {
307	$query['date_query'] = array(
308	'column' => 'comment_date_gmt',
309	'inclusive' => true,
310	);
311
312	if ( $is_before ) {
313	$query['date_query']['before'] = $args['before_gmt'];
314	}
315
316	if ( $is_after ) {
317	$query['date_query']['after'] = $args['after_gmt'];
318	}
319	}
320	}
321	if ( $args['hierarchical'] && $found > 5000 ) {
322	// Massive comment thread found; don't pre-load comment metadata to reduce memory used.
323	$query['update_comment_meta_cache'] = false;
324	}
325
326	if ( $post_id ) {
327	$post = get_post( $post_id );
328	if ( ! $post \|\| is_wp_error( $post ) ) {
329	return new WP_Error( 'unknown_post', 'Unknown post', 404 );
330	}
331	$query['post_id'] = $post->ID;
332	if ( $this->api->ends_with( $this->path, '/replies' ) ) {
333	$query['parent'] = 0;
334	}
335	} elseif ( $comment_id ) {
336	$comment = get_comment( $comment_id );
337	if ( ! $comment \|\| is_wp_error( $comment ) ) {
338	return new WP_Error( 'unknown_comment', 'Unknown comment', 404 );
339	}
340	$query['parent'] = $comment_id;
341	}
342
343	$comments = get_comments( $query );
344
345	if ( $args['hierarchical'] ) {
346	$walker = new WPCOM_JSON_API_List_Comments_Walker();
347	$comment_ids = $walker->paged_walk( $comments, get_option( 'thread_comments_depth', -1 ), isset( $args['page'] ) ? $args['page'] : 1, $args['number'] );
348	if ( ! empty( $comment_ids ) ) {
349	$comments = array_map( 'get_comment', $comment_ids );
350	}
351	}
352
353	$return = array();
354
355	foreach ( array_keys( $this->response_format ) as $key ) {
356	switch ( $key ) {
357	case 'found':
358	$return[ $key ] = (int) $found;
359	break;
360	case 'site_ID':
361	$return[ $key ] = (int) $blog_id;
362	break;
363	case 'comments':
364	$return_comments = array();
365	if ( ! empty( $comments ) ) {
366	foreach ( $comments as $comment ) {
367	$the_comment = $this->get_comment( $comment->comment_ID, $args['context'] );
368	if ( $the_comment && ! is_wp_error( $the_comment ) ) {
369	$return_comments[] = $the_comment;
370	}
371	}
372	}
373
374	if ( $return_comments ) {
375	/** This action is documented in json-endpoints/class.wpcom-json-api-site-settings-endpoint.php */
376	do_action( 'wpcom_json_api_objects', 'comments', count( $return_comments ) );
377	}
378
379	$return[ $key ] = $return_comments;
380	break;
381	}
382	}
383
384	return $return;
385	}
386	}
387