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( string $name, array $arguments )

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

Arguments

Name Type(s) Default Value Description
$name string

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|array $status                    Comment stati 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.
                                              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<mixed,\WP_Comment> $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<mixed,WP_Comment>

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.

Returns

integer | array

A single count of comment IDs if a count query. An array of comment IDs if a full query.

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 informed of new chapter releases, important WordPress API updates and more.