145 * @param string|array $query { |
145 * @param string|array $query { |
146 * Optional. Array or query string of comment query parameters. Default empty. |
146 * Optional. Array or query string of comment query parameters. Default empty. |
147 * |
147 * |
148 * @type string $author_email Comment author email address. Default empty. |
148 * @type string $author_email Comment author email address. Default empty. |
149 * @type string $author_url Comment author URL. Default empty. |
149 * @type string $author_url Comment author URL. Default empty. |
150 * @type array $author__in Array of author IDs to include comments for. Default empty. |
150 * @type int[] $author__in Array of author IDs to include comments for. Default empty. |
151 * @type array $author__not_in Array of author IDs to exclude comments for. Default empty. |
151 * @type int[] $author__not_in Array of author IDs to exclude comments for. Default empty. |
152 * @type array $comment__in Array of comment IDs to include. Default empty. |
152 * @type int[] $comment__in Array of comment IDs to include. Default empty. |
153 * @type array $comment__not_in Array of comment IDs to exclude. Default empty. |
153 * @type int[] $comment__not_in Array of comment IDs to exclude. Default empty. |
154 * @type bool $count Whether to return a comment count (true) or array of |
154 * @type bool $count Whether to return a comment count (true) or array of |
155 * comment objects (false). Default false. |
155 * comment objects (false). Default false. |
156 * @type array $date_query Date query clauses to limit comments by. See WP_Date_Query. |
156 * @type array $date_query Date query clauses to limit comments by. See WP_Date_Query. |
157 * Default null. |
157 * Default null. |
158 * @type string $fields Comment fields to return. Accepts 'ids' for comment IDs |
158 * @type string $fields Comment fields to return. Accepts 'ids' for comment IDs |
193 * Default: 'comment_date_gmt'. |
193 * Default: 'comment_date_gmt'. |
194 * @type string $order How to order retrieved comments. Accepts 'ASC', 'DESC'. |
194 * @type string $order How to order retrieved comments. Accepts 'ASC', 'DESC'. |
195 * Default: 'DESC'. |
195 * Default: 'DESC'. |
196 * @type int $parent Parent ID of comment to retrieve children of. |
196 * @type int $parent Parent ID of comment to retrieve children of. |
197 * Default empty. |
197 * Default empty. |
198 * @type array $parent__in Array of parent IDs of comments to retrieve children for. |
198 * @type int[] $parent__in Array of parent IDs of comments to retrieve children for. |
199 * Default empty. |
199 * Default empty. |
200 * @type array $parent__not_in Array of parent IDs of comments *not* to retrieve |
200 * @type int[] $parent__not_in Array of parent IDs of comments *not* to retrieve |
201 * children for. Default empty. |
201 * children for. Default empty. |
202 * @type array $post_author__in Array of author IDs to retrieve comments for. |
202 * @type int[] $post_author__in Array of author IDs to retrieve comments for. |
203 * Default empty. |
203 * Default empty. |
204 * @type array $post_author__not_in Array of author IDs *not* to retrieve comments for. |
204 * @type int[] $post_author__not_in Array of author IDs *not* to retrieve comments for. |
205 * Default empty. |
205 * Default empty. |
206 * @type int $post_ID Currently unused. |
206 * @type int $post_ID Currently unused. |
207 * @type int $post_id Limit results to those affiliated with a given post ID. |
207 * @type int $post_id Limit results to those affiliated with a given post ID. |
208 * Default 0. |
208 * Default 0. |
209 * @type array $post__in Array of post IDs to include affiliated comments for. |
209 * @type int[] $post__in Array of post IDs to include affiliated comments for. |
210 * Default empty. |
210 * Default empty. |
211 * @type array $post__not_in Array of post IDs to exclude affiliated comments for. |
211 * @type int[] $post__not_in Array of post IDs to exclude affiliated comments for. |
212 * Default empty. |
212 * Default empty. |
213 * @type int $post_author Post author ID to limit results by. Default empty. |
213 * @type int $post_author Post author ID to limit results by. Default empty. |
214 * @type string|array $post_status Post status or array of post statuses to retrieve |
214 * @type string|array $post_status Post status or array of post statuses to retrieve |
215 * affiliated comments for. Pass 'any' to match any value. |
215 * affiliated comments for. Pass 'any' to match any value. |
216 * Default empty. |
216 * Default empty. |
220 * Default empty. |
220 * Default empty. |
221 * @type int $post_parent Post parent ID to retrieve affiliated comments for. |
221 * @type int $post_parent Post parent ID to retrieve affiliated comments for. |
222 * Default empty. |
222 * Default empty. |
223 * @type string $search Search term(s) to retrieve matching comments for. |
223 * @type string $search Search term(s) to retrieve matching comments for. |
224 * Default empty. |
224 * Default empty. |
225 * @type string|array $status Comment stati to limit results by. Accepts an array |
225 * @type string|array $status Comment statuses to limit results by. Accepts an array |
226 * or space/comma-separated list of 'hold' (`comment_status=0`), |
226 * or space/comma-separated list of 'hold' (`comment_status=0`), |
227 * 'approve' (`comment_status=1`), 'all', or a custom |
227 * 'approve' (`comment_status=1`), 'all', or a custom |
228 * comment status. Default 'all'. |
228 * comment status. Default 'all'. |
229 * @type string|array $type Include comments of a given type, or array of types. |
229 * @type string|array $type Include comments of a given type, or array of types. |
230 * Accepts 'comment', 'pings' (includes 'pingback' and |
230 * Accepts 'comment', 'pings' (includes 'pingback' and |
231 * 'trackback'), or anycustom type string. Default empty. |
231 * 'trackback'), or any custom type string. Default empty. |
232 * @type array $type__in Include comments from a given array of comment types. |
232 * @type string[] $type__in Include comments from a given array of comment types. |
233 * Default empty. |
233 * Default empty. |
234 * @type array $type__not_in Exclude comments from a given array of comment types. |
234 * @type string[] $type__not_in Exclude comments from a given array of comment types. |
235 * Default empty. |
235 * Default empty. |
236 * @type int $user_id Include comments for a specific user ID. Default empty. |
236 * @type int $user_id Include comments for a specific user ID. Default empty. |
237 * @type bool|string $hierarchical Whether to include comment descendants in the results. |
237 * @type bool|string $hierarchical Whether to include comment descendants in the results. |
238 * 'threaded' returns a tree, with each comment's children |
238 * - 'threaded' returns a tree, with each comment's children |
239 * stored in a `children` property on the `WP_Comment` |
239 * stored in a `children` property on the `WP_Comment` object. |
240 * object. 'flat' returns a flat array of found comments plus |
240 * - 'flat' returns a flat array of found comments plus |
241 * their children. Pass `false` to leave out descendants. |
241 * their children. |
|
242 * - Boolean `false` leaves out descendants. |
242 * The parameter is ignored (forced to `false`) when |
243 * The parameter is ignored (forced to `false`) when |
243 * `$fields` is 'ids' or 'counts'. Accepts 'threaded', |
244 * `$fields` is 'ids' or 'counts'. Accepts 'threaded', |
244 * 'flat', or false. Default: false. |
245 * 'flat', or false. Default: false. |
245 * @type string $cache_domain Unique cache key to be produced when this query is stored in |
246 * @type string $cache_domain Unique cache key to be produced when this query is stored in |
246 * an object cache. Default is 'core'. |
247 * an object cache. Default is 'core'. |
380 } |
381 } |
381 |
382 |
382 $comment_data = null; |
383 $comment_data = null; |
383 |
384 |
384 /** |
385 /** |
385 * Filter the comments data before the query takes place. |
386 * Filters the comments data before the query takes place. |
386 * |
387 * |
387 * Return a non-null value to bypass WordPress's default comment queries. |
388 * Return a non-null value to bypass WordPress' default comment queries. |
388 * |
389 * |
389 * The expected return type from this filter depends on the value passed in the request query_vars. |
390 * The expected return type from this filter depends on the value passed |
390 * When `$this->query_vars['count']` is set, the filter should return the comment count as an int. |
391 * in the request query vars: |
391 * When `'ids' === $this->query_vars['fields']`, the filter should return an array of comment IDs. |
392 * - When `$this->query_vars['count']` is set, the filter should return |
392 * Otherwise the filter should return an array of WP_Comment objects. |
393 * the comment count as an integer. |
|
394 * - When `'ids' === $this->query_vars['fields']`, the filter should return |
|
395 * an array of comment IDs. |
|
396 * - Otherwise the filter should return an array of WP_Comment objects. |
|
397 * |
|
398 * Note that if the filter returns an array of comment data, it will be assigned |
|
399 * to the `comments` property of the current WP_Comment_Query instance. |
|
400 * |
|
401 * Filtering functions that require pagination information are encouraged to set |
|
402 * the `found_comments` and `max_num_pages` properties of the WP_Comment_Query object, |
|
403 * passed to the filter by reference. If WP_Comment_Query does not perform a database |
|
404 * query, it will not have enough information to generate these values itself. |
393 * |
405 * |
394 * @since 5.3.0 |
406 * @since 5.3.0 |
|
407 * @since 5.6.0 The returned array of comment data is assigned to the `comments` property |
|
408 * of the current WP_Comment_Query instance. |
395 * |
409 * |
396 * @param array|int|null $comment_data Return an array of comment data to short-circuit WP's comment query, |
410 * @param array|int|null $comment_data Return an array of comment data to short-circuit WP's comment query, |
397 * the comment count as an integer if `$this->query_vars['count']` is set, |
411 * the comment count as an integer if `$this->query_vars['count']` is set, |
398 * or null to allow WP to run its normal queries. |
412 * or null to allow WP to run its normal queries. |
399 * @param WP_Comment_Query $this The WP_Comment_Query instance, passed by reference. |
413 * @param WP_Comment_Query $query The WP_Comment_Query instance, passed by reference. |
400 */ |
414 */ |
401 $comment_data = apply_filters_ref_array( 'comments_pre_query', array( $comment_data, &$this ) ); |
415 $comment_data = apply_filters_ref_array( 'comments_pre_query', array( $comment_data, &$this ) ); |
402 |
416 |
403 if ( null !== $comment_data ) { |
417 if ( null !== $comment_data ) { |
|
418 if ( is_array( $comment_data ) && ! $this->query_vars['count'] ) { |
|
419 $this->comments = $comment_data; |
|
420 } |
|
421 |
404 return $comment_data; |
422 return $comment_data; |
405 } |
423 } |
406 |
424 |
407 /* |
425 /* |
408 * Only use the args defined in the query_var_defaults to compute the key, |
426 * Only use the args defined in the query_var_defaults to compute the key, |
437 } |
455 } |
438 |
456 |
439 // If querying for a count only, there's nothing more to do. |
457 // If querying for a count only, there's nothing more to do. |
440 if ( $this->query_vars['count'] ) { |
458 if ( $this->query_vars['count'] ) { |
441 // $comment_ids is actually a count in this case. |
459 // $comment_ids is actually a count in this case. |
442 return intval( $comment_ids ); |
460 return (int) $comment_ids; |
443 } |
461 } |
444 |
462 |
445 $comment_ids = array_map( 'intval', $comment_ids ); |
463 $comment_ids = array_map( 'intval', $comment_ids ); |
446 |
464 |
447 if ( 'ids' === $this->query_vars['fields'] ) { |
465 if ( 'ids' === $this->query_vars['fields'] ) { |
474 * Filters the comment query results. |
492 * Filters the comment query results. |
475 * |
493 * |
476 * @since 3.1.0 |
494 * @since 3.1.0 |
477 * |
495 * |
478 * @param WP_Comment[] $_comments An array of comments. |
496 * @param WP_Comment[] $_comments An array of comments. |
479 * @param WP_Comment_Query $this Current instance of WP_Comment_Query (passed by reference). |
497 * @param WP_Comment_Query $query Current instance of WP_Comment_Query (passed by reference). |
480 */ |
498 */ |
481 $_comments = apply_filters_ref_array( 'the_comments', array( $_comments, &$this ) ); |
499 $_comments = apply_filters_ref_array( 'the_comments', array( $_comments, &$this ) ); |
482 |
500 |
483 // Convert to WP_Comment instances. |
501 // Convert to WP_Comment instances. |
484 $comments = array_map( 'get_comment', $_comments ); |
502 $comments = array_map( 'get_comment', $_comments ); |
884 * Filters the comment query clauses. |
902 * Filters the comment query clauses. |
885 * |
903 * |
886 * @since 3.1.0 |
904 * @since 3.1.0 |
887 * |
905 * |
888 * @param string[] $pieces An associative array of comment query clauses. |
906 * @param string[] $pieces An associative array of comment query clauses. |
889 * @param WP_Comment_Query $this Current instance of WP_Comment_Query (passed by reference). |
907 * @param WP_Comment_Query $query Current instance of WP_Comment_Query (passed by reference). |
890 */ |
908 */ |
891 $clauses = apply_filters_ref_array( 'comments_clauses', array( compact( $pieces ), &$this ) ); |
909 $clauses = apply_filters_ref_array( 'comments_clauses', array( compact( $pieces ), &$this ) ); |
892 |
910 |
893 $fields = isset( $clauses['fields'] ) ? $clauses['fields'] : ''; |
911 $fields = isset( $clauses['fields'] ) ? $clauses['fields'] : ''; |
894 $join = isset( $clauses['join'] ) ? $clauses['join'] : ''; |
912 $join = isset( $clauses['join'] ) ? $clauses['join'] : ''; |
923 $this->sql_clauses['limits'] = $limits; |
941 $this->sql_clauses['limits'] = $limits; |
924 |
942 |
925 $this->request = "{$this->sql_clauses['select']} {$this->sql_clauses['from']} {$where} {$this->sql_clauses['groupby']} {$this->sql_clauses['orderby']} {$this->sql_clauses['limits']}"; |
943 $this->request = "{$this->sql_clauses['select']} {$this->sql_clauses['from']} {$where} {$this->sql_clauses['groupby']} {$this->sql_clauses['orderby']} {$this->sql_clauses['limits']}"; |
926 |
944 |
927 if ( $this->query_vars['count'] ) { |
945 if ( $this->query_vars['count'] ) { |
928 return intval( $wpdb->get_var( $this->request ) ); |
946 return (int) $wpdb->get_var( $this->request ); |
929 } else { |
947 } else { |
930 $comment_ids = $wpdb->get_col( $this->request ); |
948 $comment_ids = $wpdb->get_col( $this->request ); |
931 return array_map( 'intval', $comment_ids ); |
949 return array_map( 'intval', $comment_ids ); |
932 } |
950 } |
933 } |
951 } |