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

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$querystring|arrayoptional

Array or query string of comment query parameters. Default empty.Default: ''

• $author_emailstringdefault: empty

  Comment author email address.

• $author_urlstringdefault: empty

  Comment author URL.

• $author__inint[]default: empty

  Array of author IDs to include comments for.

• $author__not_inint[]default: empty

  Array of author IDs to exclude comments for.

• $comment__inint[]default: empty

  Array of comment IDs to include.

• $comment__not_inint[]default: empty

  Array of comment IDs to exclude.

• $countbooldefault: false

  Whether to return a comment count (true) or array of comment objects (false).

• $date_queryarraydefault: null

  Date query clauses to limit comments by. See WP_Date_Query.

• $fieldsstringdefault: empty

  Comment fields to return. Accepts 'ids' for comment IDs only or empty for all fields.

• $include_unapprovedarraydefault: empty

  Array of IDs or email addresses of users whose unapproved comments will be returned by the query regardless of $status.

• $karmaintdefault: empty

  Karma score to retrieve matching comments for.

• $meta_keystring|string[]

  Meta key or keys to filter by.

• $meta_valuestring|string[]

  Meta value or values to filter by.

• $meta_comparestring

  MySQL operator used for comparing the meta value. See WP_Meta_Query::construct() for accepted values and default value.

• $meta_compare_keystring

  MySQL operator used for comparing the meta key. See WP_Meta_Query::</strong>construct() for accepted values and default value.

• $meta_typestring

  MySQL data type that the meta_value column will be CAST to for comparisons. See WP_Meta_Query::construct() for accepted values and default value.

• $meta_type_keystring

  MySQL data type that the meta_key column will be CAST to for comparisons. See WP_Meta_Query::__construct() for accepted values and default value.

• $meta_queryarray

  An associative array of WP_Meta_Query arguments. See WP_Meta_Query::</strong>construct() for accepted values.

• $numberintdefault: empty (no limit)

  Maximum number of comments to retrieve.

• $pagedintdefault: 1

  When used with $number, defines the page of results to return. When used with $offset, $offset takes precedence.

• $offsetintdefault: 0

  Number of comments to offset the query. Used to build LIMIT clause.

• $no_found_rowsbooldefault: true

  Whether to disable the SQL_CALC_FOUND_ROWS query.

• $orderbystring|arraydefault: 'comment_date_gmt'

  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 - The array keys of $meta_query - false, an empty array, or 'none' to disable ORDER BY clause.

• $orderstringdefault: 'DESC'

  How to order retrieved comments. Accepts 'ASC', 'DESC'.

• $parentintdefault: empty

  Parent ID of comment to retrieve children of.

• $parent__inint[]default: empty

  Array of parent IDs of comments to retrieve children for.

• $parent__not_inint[]default: empty

  Array of parent IDs of comments not to retrieve children for.

• $post_author__inint[]default: empty

  Array of author IDs to retrieve comments for.

• $post_author__not_inint[]default: empty

  Array of author IDs not to retrieve comments for.

• $post_idintdefault: 0

  Limit results to those affiliated with a given post ID.

• $post__inint[]default: empty

  Array of post IDs to include affiliated comments for.

• $post__not_inint[]default: empty

  Array of post IDs to exclude affiliated comments for.

• $post_authorintdefault: empty

  Post author ID to limit results by.

• $post_statusstring|string[]default: empty

  Post status or array of post statuses to retrieve affiliated comments for. Pass 'any' to match any value.

• $post_typestring|string[]default: empty

  Post type or array of post types to retrieve affiliated comments for. Pass 'any' to match any value.

• $post_namestringdefault: empty

  Post name to retrieve affiliated comments for.

• $post_parentintdefault: empty

  Post parent ID to retrieve affiliated comments for.

• $searchstringdefault: empty

  Search term(s) to retrieve matching comments for.

• $statusstring|arraydefault: 'all'

  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.

• $typestring|string[]default: empty

  Include comments of a given type, or array of types. Accepts 'comment', 'pings' (includes 'pingback' and 'trackback'), or any custom type string.

• $type__instring[]default: empty

  Include comments from a given array of comment types.

• $type__not_instring[]default: empty

  Exclude comments from a given array of comment types.

• $user_idintdefault: empty

  Include comments for a specific user ID.

• $hierarchicalbool|stringdefault: false

  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. - Boolean false leaves out descendants. The parameter is ignored (forced to false) when $fields is 'ids' or 'counts'. Accepts 'threaded', 'flat', or false.

• $cache_domainstringdefault: is 'core'

  Unique cache key to be produced when this query is stored in an object cache.

• $update_comment_meta_cachebooldefault: true

  Whether to prime the metadata cache for found comments.

• $update_comment_post_cachebooldefault: false

  Whether to prime the cache for comment posts.

Performance profile

How much work a call to WP_Comment_Query::__construct() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Trivial

Reaches the database via ->query().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

6–9

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 9.

Plugin surface

None

Nothing here hands control to plugin code.

Called by

9

9 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• sqldatabase query->query()called directly

What one call costs · 2 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost WP_Comment_Query::__construct() can have, taken from its control-flow graph on PHP 8.5.

Uses · 1

• WP_Comment_Query::query()Sets up the WordPress query for retrieving comments.

Used by · 9

• WP_REST_Comments_Controller::get_items()Retrieves a list of comment items.
• build_comment_query_vars_from_block()Helper function that constructs a comment query vars array from the passed block properties.
• comments_template()Loads the comment template specified in $file.
• get_approved_comments()Retrieves the approved comments for a post.
• get_comments()Retrieves a list of comments.
• get_page_of_comment()Calculates what page number a comment will appear on for comment paging.
• render_block_core_comment_template()Renders the `core/comment-template` block on the server.
• render_block_core_comments_pagination_next()Renders the `core/comments-pagination-next` block on the server.
• render_block_core_comments_pagination_numbers()Renders the `core/comments-pagination-numbers` block on the server.

Source code

View on Trac ↗View on GitHub ↗

278	public function __construct( $query = '' ) {279		$this->query_var_defaults = array(280			'author_email'              => '',281			'author_url'                => '',282			'author__in'                => '',283			'author__not_in'            => '',284			'include_unapproved'        => '',285			'fields'                    => '',286			'ID'                        => '',287			'comment__in'               => '',288			'comment__not_in'           => '',289			'karma'                     => '',290			'number'                    => '',291			'offset'                    => '',292			'no_found_rows'             => true,293			'orderby'                   => '',294			'order'                     => 'DESC',295			'paged'                     => 1,296			'parent'                    => '',297			'parent__in'                => '',298			'parent__not_in'            => '',299			'post_author__in'           => '',300			'post_author__not_in'       => '',301			'post_ID'                   => '',302			'post_id'                   => 0,303			'post__in'                  => '',304			'post__not_in'              => '',305			'post_author'               => '',306			'post_name'                 => '',307			'post_parent'               => '',308			'post_status'               => '',309			'post_type'                 => '',310			'status'                    => 'all',311			'type'                      => '',312			'type__in'                  => '',313			'type__not_in'              => '',314			'user_id'                   => '',315			'search'                    => '',316			'count'                     => false,317			'meta_key'                  => '',318			'meta_value'                => '',319			'meta_query'                => '',320			'date_query'                => null, // See WP_Date_Query.321			'hierarchical'              => false,322			'cache_domain'              => 'core',323			'update_comment_meta_cache' => true,324			'update_comment_post_cache' => false,325		);326 327		if ( ! empty( $query ) ) {328			$this->query( $query );329		}330	}

Changelog

Introduced in 5.3.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/class-wp-comment-query.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.