[wp-trac] [WordPress Trac] #65313: Extend `WP_Comment_Query` 'fields' parameter to support individual column names

[WordPress Trac]

#65313: Extend `WP_Comment_Query` 'fields' parameter to support individual column
names
-------------------------+-----------------------------
 Reporter:  dd32         |      Owner:  (none)
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Awaiting Review
Component:  Comments     |    Version:
 Severity:  normal       |   Keywords:
  Focuses:  performance  |
-------------------------+-----------------------------
 == Background ==

 `WP_Comment_Query` currently accepts only two values for `fields`:

 * `''` (default) — full `WP_Comment` objects.
 * `'ids'` — comment IDs only.

 This is asymmetric with `WP_User_Query`, which accepts any valid user
 column as `fields` (e.g. `fields => 'user_email'`, or an array of column
 names), returning a flat or shaped result without hydrating `WP_User`
 objects.

 A common pattern in plugins that build "discussion-style" features on top
 of comments is to ask //"give me the distinct `comment_post_ID`s where
 comments match X"// — for example, listing posts the current user has
 commented on, or listing
 posts with comments tagged with a particular meta value. Today there are
 three options, none good:

 1. Use `fields => ''` and `array_column( $query->comments,
 'comment_post_ID' )` — hydrates every comment object only to throw all but
 one field away.
 2. Use `fields => 'ids'` and then `get_comment( $id )->comment_post_ID` in
 a loop — N+1 cache lookups, still O(comments).
 3. Drop to raw SQL — works, but bypasses `WP_Comment_Query`'s filters,
 caching, and meta-query machinery.

 == Real-world example ==

 The `gp-translation-helpers` plugin (translate.wordpress.org) was
 hydrating ~32K `WP_Comment` objects per page load for a heavy validator
 just to extract the distinct post IDs:

 {{{
 #!php
 <?php
 $query = new WP_Comment_Query( array(
     'meta_key'   => 'locale',
     'meta_value' => $locale_slug,
     'user_id'    => $user_id,
 ) );
 $post_ids = array_unique( array_column( $query->comments,
 'comment_post_ID' ) );
 }}}

 That call took ~6.6 s on the live database. The equivalent direct SQL
 returned the same 25,694 distinct post IDs in ~610 ms (an ~11× speedup),
 purely because it stopped hydrating comments. The plugin had to fall back
 to raw SQL
 ([https://github.com/GlotPress/gp-translation-helpers/pull/236 PR #236])
 for this reason.

 == Proposal ==

 Allow `fields` to accept any valid column name from the `$wpdb->comments`
 table, matching the `WP_User_Query` behaviour. At minimum,
 `'comment_post_ID'`, `'user_id'`, and `'comment_parent'` are high-value
 projections.

 Suggested API:

 {{{
 #!php
 <?php
 // Returns array of post IDs.
 $post_ids = ( new WP_Comment_Query() )->query( array(
     'meta_key'   => 'locale',
     'meta_value' => 'nl',
     'user_id'    => 42,
     'fields'     => 'comment_post_ID',
 ) );

 // Optional: support array of column names, returning stdClass per row.
 $rows = ( new WP_Comment_Query() )->query( array(
     'fields' => array( 'comment_ID', 'comment_post_ID', 'comment_date' ),
 ) );
 }}}

 == Backwards compatibility ==

 `'ids'` and `''` (default) keep their current meaning; new column-name
 values are purely additive.

 == Related ==

 * #28434 — original ticket that added the `fields` parameter
 (closed/fixed, 2014).



 ''This ticket was drafted with AI, and reviewed before submit''

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/65313>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform