WordPress.org

Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Class Reference/WP Comment Query

Description

WP_Comment_Query is a class, defined in wp-includes/class-wp-comment-query.php, that allows querying WordPress database tables 'wp_comments' and 'wp_commentmeta'. The class was introduced in Version 3.1.

Usage

<?php
$args = array(
   // args here
);

// The Query
$comments_query = new WP_Comment_Query;
$comments = $comments_query->query( $args );

// Comment Loop
if ( $comments ) {
	foreach ( $comments as $comment ) {
		echo '<p>' . $comment->comment_content . '</p>';
	}
} else {
	echo 'No comments found.';
}
?>

Default Usage

<?php
$args = array(
    'author_email' => '',    
    'author_url' => '',
    'author__in' => '',
    'author__not_in' => '',
    'include_unapproved' => '',
    'fields' => '',
    'ID' => '',
    'comment__in' => '',
    'comment__not_in' => '',
    'karma' => '',
    'number' => '',
    'offset' => '',
    'no_found_rows' => true,
    'orderby' => '',
    'order' => 'DESC',
    'parent' => '',
    'parent__in' => '',
    'parent__not_in' => '',
    'post_author__in' => '',
    'post_author__not_in' => '',
    'post_id' => 0,
    'post__in' => '',
    'post__not_in' => '',
    'post_author' => '',
    'post_name' => '',
    'post_parent' => '',
    'post_status' => '',
    'post_type' => '',
    'status' => 'all',
    'type' => '',
    'type__in' => '',
    'type__not_in' => '',
    'user_id' => '',
    'search' => '',
    'hierarchical' => false,
    'count' => false,
    'cache_domain' => 'core',
    'meta_key' => '',
    'meta_value' => '',
    'meta_query' => '',
    'date_query' => null, // See WP_Date_Query
    'update_comment_meta_cache' => true,
    'update_comment_post_cache' => false,
);
?>

Methods and Properties

Properties

Methods

Parameters

$status
(string) (optional) Only return comments with this status.
  • 'hold' - unapproved comments
  • 'approve' - approved comments
  • 'trash' - trash comments
Default: None
$orderby
(string) (optional) Set the field used to sort comments.
Default: comment_date_gmt
$order
(string) (optional) How to sort $orderby. Valid values:
  • 'ASC' - Ascending (lowest to highest).
  • 'DESC' - Descending (highest to lowest).
Default: DESC
$number
(integer) (optional) Number of comments to return. Leave blank to return all comments.
Default: unlimited
$offset
(integer) (optional) Offset from latest comment. You must include $number along with this.
Default: 0
$post_id
(integer) (optional) Only return comments for a particular post or page.
Default: None
$user_id
(integer) (optional) Only return comments for a particular user.
Default: None
$count
(integer) (optional) Only return the total count of comments.
Default: None
$type__in
(array) (optional) Allows specification of specific comment types
Default: None
$type__not_in
(array) (optional) Allows specifying all comment types except those in the array
Default: None
$meta_key
(string) (optional) Custom meta field key.
Default: None
$meta_value
(string) (optional) Custom meta field value.
Default: None
$meta_query
(array) (optional) Advanced meta query parameters (available with Version 3.5).
Default: None
$fields
(string) (optional) Which fields to return (available with Version 4.0).
  • 'ids' - Comments ID's
  • '*' - All comment fields.
Default: *

Custom Field Parameters

Show comments associated with a certain custom field.

  • meta_key (string) - Custom field key.
  • meta_value (string) - Custom field value.
  • meta_query (array) - Custom field parameters (available with Version 3.5).
    • key (string) - Custom field key.
    • value (string|array) - Custom field value (Note: Array support is limited to a compare value of 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS' or 'NOT EXISTS')
    • compare (string) - Operator to test. Possible values are '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS', and 'NOT EXISTS'. Default value is '='.
    • type (string) - Custom field type. Possible values are 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED'. Default value is 'CHAR'.

Display featured comments

$comment_query = new WP_Comment_Query( array( 'meta_key' => 'featured', 'meta_value' => '1' ) );

Multiple meta fields handling

$args = array(
	'meta_query' => array(
		'relation' => 'AND',
		array(
			'key' => 'featured',
			'value' => '1'
		),
		array(
			'key' => 'buried',
			'value' => '1',
			'type' => 'numeric',
			'compare' => '!='
		)
	)
 );
$comment_query = new WP_Comment_Query( $args );

Returns

(Array) 
Comment fields with the following index keys (or an empty array if there are no comments):
comment_ID 
(integer) The comment ID
comment_post_ID 
(integer) The ID of the post/page that this comment responds to
comment_author 
(string) The comment author's name
comment_author_email 
(string) The comment author's email
comment_author_url 
(string) The comment author's webpage
comment_author_IP 
(string) The comment author's IP
comment_date 
(string) The datetime of the comment (YYYY-MM-DD HH:MM:SS)
comment_date_gmt 
(string) The GMT datetime of the comment (YYYY-MM-DD HH:MM:SS)
comment_content 
(string) The comment's content
comment_karma 
(integer) The comment's karma
comment_approved 
(string) The comment approval level (0, 1 or "spam")
comment_agent 
(string) The commenter's user agent (browser, operating system, etc.)
comment_type 
(string) The comment's type if meaningfull (pingback|trackback), empty for normal comments
comment_parent 
(string) The parent comment's ID for nested comments (0 for top level)
user_id 
(integer) The comment author's ID if s/he is registered (0 otherwise)

Change Log

  • 4.6.0:
    • Add '$cache_domain' parameter.
  • 4.5.0:
    • Add '$author_url' parameter.
  • 4.4.0:
    • Add '$parent__in' and '$parent__not_in' parameters.
    • Add '$no_found_rows' and '$hierarchical' parameters.
    • Add '$update_comment_meta_cache' and '$update_comment_post_cache' parameters.
    • Add Order by 'comment__in'.
  • 4.1.0:
    • Add 'comment__in', 'comment__not_in', 'post_author__in', 'post_author__not_in', 'author__in', 'author__not_in', 'post__in', 'post__not_in', 'include_unapproved', 'type__in', and 'type__not_in' parameters.

Source File

WP_Comment_Query is located in wp-includes/class-wp-comment-query.php.

Resources

Related

See also index of Class Reference and index of Function Reference.