It’s always nice to show how many comments and pingbacks your posts have, right? There are also plugins that can show off how many comments have been blocked as spam as a sidebar widget, although I don’t see how useful that could be to your readers :)

Today we’ll talk about comment moderation and how to show off the number of comments held for moderation for a particular post. In addition to that we’ll try to list the authors of such comments which can sometimes be useful.

Getting Started

Before you get started make sure you’re familiar with WordPress actions and filters. I’ll be working with the Twenty Eleven theme and I’ll be creating a child theme to house my code, although in this case a plugin is fine. Here’s what we’re going to do today:

Short off-topic: when customizing WordPress, how do you determine whether to use a child theme or a plugin for your specific customization? I’m sure there are several reasons to pick one or another and sometimes it’s also a matter of personal preferences.

When it comes to visual customizations, i.e. something that’s altering the look of your theme, I prefer to stick to child themes, even if there’s minimal or no styling at all. I also pick child theming for minor things like what we’re going to discuss today although it can easily be taken forward, wrapped into a plugin and shared publicly. Anyhow, it’s up to you :)

Assuming you have created your child theme or plugin, let’s talk a little bit about comments.

Comments in WordPress

It’s not very important to understand the details of how comments in WordPress work, but an overview wouldn’t do any harm. Comments are stored in the wp_comments table, have relations to entries in wp_posts, the author name, e-mail, comment content and other fields as well as a status field called comment_approved. This is where the moderation magic happens.

Basically, when a new comment is published to a post of yours, there are several tests that run against the comment to see if it’s spam, whether it should be automatically approved or held for moderation. Spam and unapproved comments are not the same thing although I like to think of it as a certain threshold, but anyway, comments held for moderation are less likely to be spam than spam comments (doh!)

You can further inspect the wp_comments table using phpMyAdmin or the MySQL command line interface, like this:

SHOW CREATE TABLE `wp_comments`

But you don’t really have to get into the details of that, as I mentioned a brief overview is enough. There’s also a good article in the Codex called Comment Moderation which briefly explains how moderation works.

Fetching Moderated Comments

You’re probably familiar with template tags such as comments_template and others used in your theme files but today we’ll talk about a function called get_comments which is used to retrieve a list of comments. The codex entry doesn’t list all the available arguments but as seen in the core code it’s a wrapper to the WP_Comment_Query‘s query method.

Note that count argument which is set to false as a default value. If set to true the method will return the number of found comments rather then the comments themselves which is nice from the performance point of view. So in theory, something like this:

$count = get_comments( array( 'post_ID' => 123, 'count' => true ) );
echo $count;

Would output the total number of comments for the post number 123. That will include unapproved comments. Let’s try add the status argument to filter out approved comments:

$count = get_comments( array( 'status' => 'hold', 'post_ID' => 123, 'count' => true ) );
echo $count;

That would be exactly what we need, if we add it to the right context of course. Let’s go ahead and do that!

Hooking to the Right Place

It’s up to you where you’d like to display the number of moderated comments but keep in mind that whatever it is, note that the global $post should be available since that’s where we’ll get our current post’s ID.

After looking at the Twenty Eleven comment templates I found it called the comment_form template tag which renders the reply form. I thought of adding the moderated comments count before the comment form so I inspected the core files and found this action called comment_form_before. Sweet, so I don’t even have to override any of Twenty Eleven’s templates!

So in your functions.php file, write something like this:

add_action( 'comment_form_before', 'my_comment_form_before' );
function my_comment_form_before() {
    global $post;

    $count = get_comments( array(
        'post_ID' => $post->ID,
        'status' => 'hold',
        'count' => true
    ) );

    echo "<p>And $count more in the moderation queue.</p>";
}

That’s all there is to it, seriously. We’re getting the post ID from the global $post object and firing a call to get_comments that fetches the number (count) of comments with the hold status. Nothing more, nothing less.

Now with that in mind, let’s try something more interesting, shall we?

Moderated Comment Authors

That’s right, we’ll display a list of authors who’s comments are held for moderation. We’ll use a similar approach but we’ll get rid of that count argument since we’ll have to retrieve the actual comments. Here’s what the new snippet looks like:

add_action( 'comment_form_before', 'my_comment_form_before' );
function my_comment_form_before() {
    global $post;

    $comments = get_comments( array(
        'post_ID' => $post->ID,
        'status' => 'hold'
    ) );

    $authors = array();
    foreach ( $comments as $comment )
        $authors[] = $comment->comment_author;

    $authors = implode( ', ', $authors );
    $count = count( $comments );

    echo "<p>And $count more in the moderation queue by $authors.</p>";
}

The first part is not too different from what you have already seen. Since the count argument was removed (and is defaulted to false) the get_comments function now returns an array of comment objects, so we use a foreach loop to gather the comment authors and then stick them using implode. Here’s what the final output looks like:

Recap & Conclusion

While being a post about getting the number of comments held for moderation, today we talked about WordPress comments in general, including a brief overview of how comments are stored in WordPress and the correct way to retrieve them by querying with the get_comments function. We’ve also learned how easy it is to find things in the WordPress core when something’s missing from the Codex.

Thank you for reading and share your thoughts in our comments section. Don’t forget to tell us when you go with creating a child theme over a plugin and feel free to ask a question if something’s not clear. Stay tuned to our RSS feed for more tips on customizing WordPress!