--- a/wp/wp-includes/class-wp-comment-query.php Tue Dec 15 15:52:01 2020 +0100
+++ b/wp/wp-includes/class-wp-comment-query.php Wed Sep 21 18:19:35 2022 +0200
@@ -147,10 +147,10 @@
*
* @type string $author_email Comment author email address. Default empty.
* @type string $author_url Comment author URL. Default empty.
- * @type array $author__in Array of author IDs to include comments for. Default empty.
- * @type array $author__not_in Array of author IDs to exclude comments for. Default empty.
- * @type array $comment__in Array of comment IDs to include. Default empty.
- * @type array $comment__not_in Array of comment IDs to exclude. Default empty.
+ * @type int[] $author__in Array of author IDs to include comments for. Default empty.
+ * @type int[] $author__not_in Array of author IDs to exclude comments for. Default empty.
+ * @type int[] $comment__in Array of comment IDs to include. Default empty.
+ * @type int[] $comment__not_in Array of comment IDs to exclude. Default empty.
* @type bool $count Whether to return a comment count (true) or array of
* comment objects (false). Default false.
* @type array $date_query Date query clauses to limit comments by. See WP_Date_Query.
@@ -195,20 +195,20 @@
* Default: 'DESC'.
* @type int $parent Parent ID of comment to retrieve children of.
* Default empty.
- * @type array $parent__in Array of parent IDs of comments to retrieve children for.
+ * @type int[] $parent__in Array of parent IDs of comments to retrieve children for.
* Default empty.
- * @type array $parent__not_in Array of parent IDs of comments *not* to retrieve
+ * @type int[] $parent__not_in Array of parent IDs of comments *not* to retrieve
* children for. Default empty.
- * @type array $post_author__in Array of author IDs to retrieve comments for.
+ * @type int[] $post_author__in Array of author IDs to retrieve comments for.
* Default empty.
- * @type array $post_author__not_in Array of author IDs *not* to retrieve comments for.
+ * @type int[] $post_author__not_in Array of author IDs *not* to retrieve comments for.
* Default empty.
* @type int $post_ID Currently unused.
* @type int $post_id Limit results to those affiliated with a given post ID.
* Default 0.
- * @type array $post__in Array of post IDs to include affiliated comments for.
+ * @type int[] $post__in Array of post IDs to include affiliated comments for.
* Default empty.
- * @type array $post__not_in Array of post IDs to exclude affiliated comments for.
+ * @type int[] $post__not_in Array of post IDs to exclude affiliated comments for.
* Default empty.
* @type int $post_author Post author ID to limit results by. Default empty.
* @type string|array $post_status Post status or array of post statuses to retrieve
@@ -222,23 +222,24 @@
* Default empty.
* @type string $search Search term(s) to retrieve matching comments for.
* Default empty.
- * @type string|array $status Comment stati to limit results by. Accepts an array
+ * @type string|array $status Comment statuses to limit results by. Accepts an array
* or space/comma-separated list of 'hold' (`comment_status=0`),
* 'approve' (`comment_status=1`), 'all', or a custom
* comment status. Default 'all'.
* @type string|array $type Include comments of a given type, or array of types.
* Accepts 'comment', 'pings' (includes 'pingback' and
- * 'trackback'), or anycustom type string. Default empty.
- * @type array $type__in Include comments from a given array of comment types.
+ * 'trackback'), or any custom type string. Default empty.
+ * @type string[] $type__in Include comments from a given array of comment types.
* Default empty.
- * @type array $type__not_in Exclude comments from a given array of comment types.
+ * @type string[] $type__not_in Exclude comments from a given array of comment types.
* Default empty.
* @type int $user_id Include comments for a specific user ID. Default empty.
* @type bool|string $hierarchical Whether to include comment descendants in the results.
- * 'threaded' returns a tree, with each comment's children
- * stored in a `children` property on the `WP_Comment`
- * object. 'flat' returns a flat array of found comments plus
- * their children. Pass `false` to leave out descendants.
+ * - 'threaded' returns a tree, with each comment's children
+ * stored in a `children` property on the `WP_Comment` object.
+ * - 'flat' returns a flat array of found comments plus
+ * their children.
+ * - Boolean `false` leaves out descendants.
* The parameter is ignored (forced to `false`) when
* `$fields` is 'ids' or 'counts'. Accepts 'threaded',
* 'flat', or false. Default: false.
@@ -382,25 +383,42 @@
$comment_data = null;
/**
- * Filter the comments data before the query takes place.
+ * Filters the comments data before the query takes place.
*
- * Return a non-null value to bypass WordPress's default comment queries.
+ * Return a non-null value to bypass WordPress' default comment queries.
*
- * The expected return type from this filter depends on the value passed in the request query_vars.
- * When `$this->query_vars['count']` is set, the filter should return the comment count as an int.
- * When `'ids' === $this->query_vars['fields']`, the filter should return an array of comment IDs.
- * Otherwise the filter should return an array of WP_Comment objects.
+ * The expected return type from this filter depends on the value passed
+ * in the request query vars:
+ * - When `$this->query_vars['count']` is set, the filter should return
+ * the comment count as an integer.
+ * - When `'ids' === $this->query_vars['fields']`, the filter should return
+ * an array of comment IDs.
+ * - Otherwise the filter should return an array of WP_Comment objects.
+ *
+ * Note that if the filter returns an array of comment data, it will be assigned
+ * to the `comments` property of the current WP_Comment_Query instance.
+ *
+ * Filtering functions that require pagination information are encouraged to set
+ * the `found_comments` and `max_num_pages` properties of the WP_Comment_Query object,
+ * passed to the filter by reference. If WP_Comment_Query does not perform a database
+ * query, it will not have enough information to generate these values itself.
*
* @since 5.3.0
+ * @since 5.6.0 The returned array of comment data is assigned to the `comments` property
+ * of the current WP_Comment_Query instance.
*
* @param array|int|null $comment_data Return an array of comment data to short-circuit WP's comment query,
* the comment count as an integer if `$this->query_vars['count']` is set,
* or null to allow WP to run its normal queries.
- * @param WP_Comment_Query $this The WP_Comment_Query instance, passed by reference.
+ * @param WP_Comment_Query $query The WP_Comment_Query instance, passed by reference.
*/
$comment_data = apply_filters_ref_array( 'comments_pre_query', array( $comment_data, &$this ) );
if ( null !== $comment_data ) {
+ if ( is_array( $comment_data ) && ! $this->query_vars['count'] ) {
+ $this->comments = $comment_data;
+ }
+
return $comment_data;
}
@@ -439,7 +457,7 @@
// If querying for a count only, there's nothing more to do.
if ( $this->query_vars['count'] ) {
// $comment_ids is actually a count in this case.
- return intval( $comment_ids );
+ return (int) $comment_ids;
}
$comment_ids = array_map( 'intval', $comment_ids );
@@ -476,7 +494,7 @@
* @since 3.1.0
*
* @param WP_Comment[] $_comments An array of comments.
- * @param WP_Comment_Query $this Current instance of WP_Comment_Query (passed by reference).
+ * @param WP_Comment_Query $query Current instance of WP_Comment_Query (passed by reference).
*/
$_comments = apply_filters_ref_array( 'the_comments', array( $_comments, &$this ) );
@@ -886,7 +904,7 @@
* @since 3.1.0
*
* @param string[] $pieces An associative array of comment query clauses.
- * @param WP_Comment_Query $this Current instance of WP_Comment_Query (passed by reference).
+ * @param WP_Comment_Query $query Current instance of WP_Comment_Query (passed by reference).
*/
$clauses = apply_filters_ref_array( 'comments_clauses', array( compact( $pieces ), &$this ) );
@@ -925,7 +943,7 @@
$this->request = "{$this->sql_clauses['select']} {$this->sql_clauses['from']} {$where} {$this->sql_clauses['groupby']} {$this->sql_clauses['orderby']} {$this->sql_clauses['limits']}";
if ( $this->query_vars['count'] ) {
- return intval( $wpdb->get_var( $this->request ) );
+ return (int) $wpdb->get_var( $this->request );
} else {
$comment_ids = $wpdb->get_col( $this->request );
return array_map( 'intval', $comment_ids );