How to target only the get_comments() query in comment_template()

[birgire]

It would be handy to be able to target only the get_comments() query within the comment_template(), to avoid messing around with other get_comments() calls, e.g. in the widgets.

Suggestion A)

We can do this to target the main query:

    add_action( 'pre_get_posts', function( \WP_Query $q ) {
        if( $q->is_main_query() ) {
            // stuff here
        }
    });

so it would be great if we could use:

    add_action( 'pre_get_comments', function( \WP_Comment_Query $q ) {
        if( $q->is_main_query() ) {
            // stuff here
        }
    });

We could also call that method is_main_comment_query() or is_comment_template_query().

How could we construct such a method?

It might be just a query variable

     $args = array(
        'order'    => 'ASC',
        'post_id' => $post->ID,  
        'status'   => 'approve',
        'comment_template_query' => true
    );

I'm not sure if that would be a good idea, so maybe we could find a way to create and compare it to an object like $wp_the_comment_query, similar to the idea within the is_main_query() method of WP_Query?

Suggestion B)

Another approach would be to introduce an argument filter, e.g. comment_template_query_args, for the get_comments() within the comment_template() function:

    $comments = get_comments( $args = apply_filters( 'comment_template_query_args', $args ) );

This might be an easier approach, to start with.

Current workarounds

We could of course modify our theme by adding:

    add_action( 'pre_get_comments', 'some_callback' );

just before comment_template() is called and then use:

    function some_callback( \WP_Comment_Query $q ) {
        // Run only once
        remove_action( current_action(), __FUNCTION__ );

        // some stuff ...
    }

but what if we would like this done through a plugin?

A possible workarounds would be to match the default query variables within pre_get_comments.

Maybe there's a much better way, or something I'm missing within the current setup ;-)

[birgire]

I just looked at the 4.4 trunk, and there seems to be few changes from 4.3.1, so the suggestion B) above would be:

    $comment_args = apply_filters( 'comments_template_query_args', $comment_args );

    $comment_query = new WP_Comment_Query( $comment_args );

ps: it should of course be comments_template() in my previous post ;-)

[boonebgorges]

Yes, this seems like a good idea.

[boonebgorges]

In 36235:

Introduce comments_template_query_args filter.

This new filter gives developers a way to target the arguments used for comment
queries specifically when populating the main comment template.

Props birgire.
Fixes #34442.

[birgire]

Added include_unapproved to the inline documentation

[birgire]

Great ;-)

I added the patch 34442-2.diff to include the inline documentation for include_unapproved, since it's also part of the $comment_args setup within comments_template():

if ( $user_ID ) {
    $comment_args['include_unapproved'] = array( $user_ID );
} elseif ( ! empty( $comment_author_email ) ) {
    $comment_args['include_unapproved'] = array( $comment_author_email );
}

I used the parameter description from the inline WP_Comment_Query class documentation.

[birgire]

I also wonder if we should make it more developer friendly and pass on the $file and $seperate_comments from the

comments_template( $file, $seperate_comments )

Additionally the $commenter array, the $post object and the $user_ID used in the comments_template() function.

Example:

       /** 
	* Filters the arguments used to query comments in comments_template(). 
 	* 
 	* @since 4.5.0 
 	* 
 	* @param array $comment_args { 
 	*     Array of arguments. See WP_Comment_Query::__construct() for detailed descriptions. 
 	* 
 	*     @type string|array $orderby                   Field(s) to order by. 
 	*     @type string       $order                     Order of results. Accepts 'ASC' or 'DESC'. 
 	*     @type string       $status                    Comment status. 
 	*     @type int          $post_id                   ID of the post. 
 	*     @type bool         $no_found_rows             Whether to refrain from querying for found rows. 
 	*     @type bool         $update_comment_meta_cache Whether to prime cache for comment meta. 
 	*     @type bool|string  $hierarchical              Whether to query for comments hierarchically. 
 	*     @type int          $offset                    Comment offset. 
 	*     @type int          $number                    Number of comments to fetch. 
 	* } 
 	* @param string $file              The comments template file to load. Default '/comments.php'.
	* @param bool   $separate_comments Whether to separate the comments by comment type. Default false.
	* @param array $commenter {
	*     Array of arguments. See wp_get_current_commenter() for detailed descriptions. 
	*     @type string|array $orderby                   Field(s) to order by. 
	*     @type string       $order                     Order of results. Accepts 'ASC' or 'DESC'. 
	*     @type string       $status                    Comment status. 
	* }  	
	* @param WP_Post $post Post object
	* @param int $user_ID The Current user ID. Is 0 if not logged in.
	*/ 
	$comment_args = apply_filters( 'comments_template_query_args', $comment_args, $file, $seperate_comments, $commenter, $post, $user_ID ); 

[boonebgorges]

In 36256:

Add missing param to 'comments_template_query_args'.

As introduced in [36235].

Props birgire.
See #34442.

[boonebgorges]

@birgire Thanks for the additional thoughts. $post and $user_ID are already available as globals, and passing them here is likely to cause by-reference confusion. $commenter is available using wp_get_current_commenter(), should one want it in the callback. I think we should not pass them to the filter, as it'll provide more noise than benefit.

I suppose passing $file and $separate_comments is relatively harmless, but perhaps you can share you thoughts on what the purpose would be? The filter we've added is on the arguments passed to WP_Comment_Query - that is, which comments to display - while $file and $separate_comments both have to do with *how* the comments are displayed. Of what use would these values be in a callback?

[birgire]

@boonebgorges thanks for your reply.

Regarding my extra arguments speculations:

I thought it would make it easer to target the relevant comments_template( $file ), to pass on the $file argument to the filter. I then just added $seperate_comments for the completion, but I think it would be less valuable than the $file argument.

As you mentioned it's much easier to get the $post, $user_ID and $commenter (in the case when we need to modify the query arguments for a given post type or some group of users, these will be handy.)

But what I had in mind was to decrease duplication, better contain it and hopefully reduce explicit usage of globals (though they are used implicitly).

But if you think any of these extra arguments would cause more confusion than benefit, then we should skip it.

[boonebgorges]

Hi @birgire - Thanks for the follow-up. In the interest of being conservative about what we commit ourselves too, I'd like to opt out of passing the additional values to the filter for the time being. If someone demonstrates a specific need for them in the future, we can add them, but in the meantime, it makes things a bit easier to maintain down the road if we are minimalistic about the params for the new filter.

[birgire]

yes I agree, that sounds sensible to me ;-)

[DrewAPicture]

In 36918:

Docs: Improve the usefulness of associated reference info in the hook doc for the comments_template_query_args filter, introduced in [36235].

See #34442. See #35986.