wpdevtools.io Logo

Class: WP_Comment_Query

Core class used for querying comments.

Properties

Methods

Properties

Name Type(s) Default Value Summary
request string SQL for database query.
meta_query object Metadata query container
meta_query_clauses array Metadata query clauses.
sql_clauses array SQL query clauses.
filtered_where_clause string SQL WHERE clause.

Stored after the \'comments_clauses' filter is run on the compiled WHERE sub-clauses.
date_query object Date query container
query_vars array Query vars set by the user.
query_var_defaults array Default values for query vars.
comments array List of comments located by the query.
found_comments integer The amount of found comments for the current query.
max_num_pages integer The number of pages.

Methods

WP_Comment_Query:: __call( callable $name, array $arguments )

Make private/protected methods readable for backward compatibility. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$name callable

Method to call.
$arguments array

Arguments to pass when calling.

Returns

mixed | false

Return value of the callback, false otherwise.

WP_Comment_Query:: __construct( string | array $query = '' )

Constructor. Since 4.2.0. Since 4.4.0. Since 4.4.0. Since 4.5.0. Since 4.6.0. Since 4.9.0.

Sets up the comment query, based on the query vars passed.

Arguments

Name Type(s) Default Value Description
$query string | array

{ Optional. Array or query string of comment query parameters. Default empty.

@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 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.
                                              Default null.
@type string       $fields                    Comment fields to return. Accepts 'ids' for comment IDs
                                              only or empty for all fields. Default empty.
@type int          $ID                        Currently unused.
@type array        $include_unapproved        Array of IDs or email addresses of users whose unapproved
                                              comments will be returned by the query regardless of
                                              `$status`. Default empty.
@type int          $karma                     Karma score to retrieve matching comments for.
                                              Default empty.
@type string       $meta_key                  Include comments with a matching comment meta key.
                                              Default empty.
@type string       $meta_value                Include comments with a matching comment meta value.
                                              Requires `$meta_key` to be set. Default empty.
@type array        $meta_query                Meta query clauses to limit retrieved comments by.
                                              See WP_Meta_Query. Default empty.
@type int          $number                    Maximum number of comments to retrieve.
                                              Default empty (no limit).
@type int          $paged                     When used with $number, defines the page of results to return.
                                              When used with $offset, $offset takes precedence. Default 1.
@type int          $offset                    Number of comments to offset the query. Used to build
                                              LIMIT clause. Default 0.
@type bool         $no_found_rows             Whether to disable the `SQL_CALC_FOUND_ROWS` query.
                                              Default: true.
@type string|array $orderby                   Comment status or array of statuses. To use 'meta_value'
                                              or 'meta_value_num', `$meta_key` must also be defined.
                                              To sort by a specific `$meta_query` clause, use that
                                              clause's array key. Accepts 'comment_agent',
                                              'comment_approved', 'comment_author',
                                              'comment_author_email', 'comment_author_IP',
                                              'comment_author_url', 'comment_content', 'comment_date',
                                              'comment_date_gmt', 'comment_ID', 'comment_karma',
                                              'comment_parent', 'comment_post_ID', 'comment_type',
                                              'user_id', 'comment__in', 'meta_value', 'meta_value_num',
                                              the value of $meta_key, and the array keys of
                                              `$meta_query`. Also accepts false, an empty array, or
                                              'none' to disable `ORDER BY` clause.
                                              Default: 'comment_date_gmt'.
@type string       $order                     How to order retrieved comments. Accepts 'ASC', 'DESC'.
                                              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.
                                              Default empty.
@type array        $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.
                                              Default empty.
@type array        $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.
                                              Default empty.
@type array        $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
                                              affiliated comments for. Pass 'any' to match any value.
                                              Default empty.
@type string       $post_type                 Post type or array of post types to retrieve affiliated
                                              comments for. Pass 'any' to match any value. Default empty.
@type string       $post_name                 Post name to retrieve affiliated comments for.
                                              Default empty.
@type int          $post_parent               Post parent ID to retrieve affiliated comments for.
                                              Default empty.
@type string       $search                    Search term(s) to retrieve matching comments for.
                                              Default empty.
@type string       $status                    Comment status to limit results by. Accepts '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.
                                              Default empty.
@type array        $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.
                                              The parameter is ignored (forced to `false`) when
                                              `$fields` is 'ids' or 'counts'. Accepts 'threaded',
                                              'flat', or false. Default: false.
@type string       $cache_domain              Unique cache key to be produced when this query is stored in
                                              an object cache. Default is 'core'.
@type bool         $update_comment_meta_cache Whether to prime the metadata cache for found comments.
                                              Default true.
@type bool         $update_comment_post_cache Whether to prime the cache for comment posts.
                                              Default false.

}

WP_Comment_Query:: fill_descendants( array $comments )

Fetch descendants for located comments. Since 4.4.0.

Instead of calling get_children() separately on each child comment, we do a single set of queries to fetch the descendant trees for all matched top-level comments.

Arguments

Name Type(s) Default Value Description
$comments array

Array of top-level comments whose descendants should be filled in.

Returns

array

WP_Comment_Query:: get_comment_ids( )

Used internally to get a list of comment IDs matching the query vars. Since 4.4.0.

WP_Comment_Query:: get_comments( )

Get a list of comments matching the query vars. Since 4.2.0.

Returns

integer | array

List of comments or number of found comments if $count argument is true.

WP_Comment_Query:: get_search_sql( string $string, array $cols )

Used internally to generate an SQL string for searching across multiple columns Since 3.1.0.

Arguments

Name Type(s) Default Value Description
$string string
$cols array

Returns

string

WP_Comment_Query:: parse_order( string $order )

Parse an 'order' query variable and cast it to ASC or DESC as necessary. Since 4.2.0.

Arguments

Name Type(s) Default Value Description
$order string

The 'order' query variable.

Returns

string

The sanitized 'order' query variable.

WP_Comment_Query:: parse_orderby( string $orderby )

Parse and sanitize 'orderby' keys passed to the comment query. Since 4.2.0.

Arguments

Name Type(s) Default Value Description
$orderby string

Alias for the field to order by.

Returns

string | false

Value to used in the ORDER clause. False otherwise.

WP_Comment_Query:: parse_query( string | array $query = '' )

Parse arguments passed to the comment query with default query parameters. Since 4.2.0.

Arguments

Name Type(s) Default Value Description
$query string | array

WP_Comment_Query arguments. See WP_Comment_Query::__construct()

WP_Comment_Query:: query( string | array $query )

Sets up the WordPress query for retrieving comments. Since 3.1.0. Since 4.1.0. Since 4.2.0.

Arguments

Name Type(s) Default Value Description
$query string | array

Array or URL query string of parameters.

Returns

array | integer

List of comments, or number of comments when 'count' is passed as a query var.

WP_Comment_Query:: set_found_comments( )

Populates found_comments and max_num_pages properties for the current query if the limit clause was used. Since 4.6.0.

WordPress Developer Newsletter

Stay on top of the latest WordPress API changes, developer tool updates, security alerts and more.