Mr Branding: Mastering WP_Comment

Monday, October 26, 2015

Mastering WP_Comment_Query

We're almost coming to the end of our series, "Mastering WP_Query", and it's time to introduce the siblings of the WP_Query class. In the previous part, we went over WP_User_Query, and in this article, we're going to learn about the WP_Comment_Query class.

Let's begin!

What Is WP_Comment_Query?

Introduced in WordPress version 3.1, the WP_Comment_Query class does almost all the heavy work on querying comments in WordPress. It allows the querying of two database tables, wp_comments and wp_commentmeta, in essence.

Here's the skeleton of a comment query loop using the WP_Comment_Query class:

<?php

$args = array(
    // Arguments for your query.
);

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

if ( $comments ) {
    
    foreach ( $comments as $comment ) {
        
        // Do what you do for each comment here.
        
    }
    
} else {
    
    // Display message because there are no comments.
    
}

?>

Pretty easy, right? We'll get to do an example just a few steps later, but let's see under the hood first.

Properties and Methods of the WP_Comment_Query Class

Since there aren't many properties (public variables of the class) and methods (public functions of the class), I'll quickly go over them in two mini-sections. Here we go!

Properties of WP_Comment_Query

Unlike WP_Query which has more than 30 properties (25 of them being the equivalents for Conditional Tags), the WP_Comment_Query class has only five properties:

$request: A string that contains the SQL query.
$meta_query: An array to make a "meta query" with the help of the WP_Meta_Query class.
$date_query: An array to make a "date query" with the help of the WP_Date_Query class.
$query_vars: An array of the variables of the query.
$comments: An array of comments fetched with the query.

The Only Method of WP_Comment_Query

Yep, there's just one method to use with the WP_Comment_Query class, and that method's name is query().

The query() method basically executes the query, using the parameters which we'll be going through in the next section; but let's see what we get in an array when we use this method:

comment_ID: The comment's ID.
comment_post_ID: The post's ID which the comment is made to.
comment_author: The comment author's name.
comment_author_email: The comment author's email address.
comment_author_url: The comment author's website URL.
comment_author_IP: The comment IP address.
comment_date: The comment date.
comment_date_gmt: The comment in GMT time format.
comment_content: The content of the comment.
comment_karma: An unused database field for each comment—plugins can use this to store, well, the comment's karma.
comment_approved: The comment's approval status.
comment_agent: The comment author's user agent.
comment_type: The comment's type if it's a pingback or a trackback.
comment_parent: For nested comments, this is the parent comment's ID. If it's the top-level comment, this will be 0.
user_id: 0 if the comment author isn't registered with the website, the ID of the user otherwise.

Let's see the parameters of the WP_Comment_Query class now.

Parameters of the WP_Comment_Query Class

There are 34 parameters we can use with WP_Comment_Query, but don't let them scare you: You can already recognize them from their names, and the others are equally easy to explain and use.

author_email (string): Comment author email address.
author__in (array): Author IDs to include in the query.
author__not_in (array): Author IDs to exclude from the query.
post_author__in (array): Same as author__in.
post_author__not_in (array): Same as author__not_in.
include_unapproved (array): An array of user IDs or email addresses whose comments should be returned regardless of their approval status.
fields (string): Comment fields to return. Accepts 'ids' only, used to return only the comment IDs.
comment__in (array): Comment IDs to include in the query.
comment__not_in (array): Comment IDs to exclude from the query.
karma (integer): The "karma" score to return matching comments for. (Remember comment_karma from the previous section?)
number (integer): The maximum number of comments to return.
offset (integer): The number of comments to pass over in the query.
orderby (string or array): A comment status or an array of statuses to order the query results. Accepts all the keys returned from the query() method, plus 'meta_value', 'meta_value_num', value of $meta_key, FALSE, empty array or 'none'. (The last three disable the ORDER BY clause in the query.)
order (string): How to order retrieved comments—'ASC' for ascending or 'DESC' for descending. (Default: 'DESC')
parent (integer): Parent comment's ID to retrieve children.
post_id (integer): Post ID to retrieve comments. (Default: 0)
post__in (array): Post IDs to include in the results.
post__not_in (array): Post IDs to exclude from the results.
post_author (integer): Post author's ID to limit results by.
post_name (string): Post slug to get comments from.
post_parent (integer): Parent post ID to get comments from.
post_type (string): Post type to get comments from.
post_status (string): Post status to get comments from.
status (string): Comment status to limit results by. Accepts 'hold', 'approve', 'all' or a custom comment status. (Default: 'all')
type (string or array): A comment type or an array of comment types to filter the query. Accepts 'comment', 'pings' (meaning pingbacks and trackbacks combined), or custom comment types.
type__in (array): Comment types to include in the query.
type__not_in (array): Comment types to exclude from the query.
user_id (integer): User ID to include comments of a specific user.
search (string): Search terms to get matching comments for.
count (boolean): Return the comment count (TRUE) or an array of comments (FALSE). (Default: FALSE)
meta_key (string): A custom meta key to include matching comments only.
meta_value (string): A custom meta value to include matching comments only.
meta_query (array): An array of WP_Meta_Query clauses (which we'll see in the next part of this series).
date_query (array): An array of WP_Date_Query clauses (which we'll see in the next part of this series). (Default: NULL)

Note: The default values of all parameters are empty, unless stated otherwise above.

A Quick Example to Understand How WP_Comment_Query Works

It wouldn't feel like a complete tutorial if we didn't see how it works, would it? Let's think of a simple scenario and do a quick example, then.

Let's say that you're going to list the comments made by the post's author and order the list by comment IDs (instead of comment dates). Here's what you do:

<?php

// Get the global `$wp_query` object...
global $wp_query;

// ...and use it to get post author's id.
$post_author_id = $wp_query->post->post_author;

// Setup arguments.
$args = array (
    'user_id' => $post_author_id,
    'orderby' => 'comment_ID'
);

// Custom comment query.
$my_comment_query = new WP_Comment_Query;
$comments = $my_comment_query->query( $args );

// Check for comments.
if ( $comments ) {

    // Start listing comments.
    echo '<ul class="author-comments">';

        // Loop over comments.
        foreach( $comments as $comment ) {
    
            echo '<li>' . $comment->comment_content . '</li>';
    
        }

    // Stop listing comments.
    echo '</ul>';

} else {

    // Display message if no comments are found.
    echo '<p class="no-author-comments">' . __( 'The post author didn\'t post any comments.', 'tutsplus' ) . '</p>';

}

?>

Quick Tip: If you want to build comment queries but want to use a GUI instead of typing code, you can use GenerateWP's WP_Comment_Query Generator.

Wrapping Everything Up

As I said, we're coming to the end of this series. In the next part, we're going to learn about the WP_Meta_Query and WP_Date_Query classes together.

Do you have anything to add to this article? Share your thoughts with us in the Comments section below. And if you liked the article, don't forget to share it with your friends.

by Barış Ünver via Tuts+ Code

Mr Branding