diff -r 34716fd837a4 -r be944660c56a wp/wp-includes/class-wp-comment-query.php --- 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 );