Comments: Allow WP_Comment_Query fields to select arbitrary columns by dd32 · Pull Request #11934 · WordPress/wordpress-develop

dd32 · 2026-05-22T05:44:51Z

Trac ticket: https://core.trac.wordpress.org/ticket/65313

Summary

Extends WP_Comment_Query's fields argument to accept:

A column name from $wpdb->comments (e.g. 'comment_post_ID') — returns a flat array of distinct values for that column.
A 'col_a=>col_b' pair (e.g. 'comment_ID=>comment_post_ID') — returns an associative array keyed by col_a's value with col_b's value as the entry, mirroring the 'id=>parent' idiom in WP_Query and WP_Term_Query.

'ids' and '' (default) are unchanged — the new behaviour is purely additive.

Why

Plugins that want "the distinct comment_post_IDs matching X" have three options today, none good:

fields => '' + array_column( $q->comments, 'comment_post_ID' ) — hydrates every matched comment just to discard all but one field.
fields => 'ids' + get_comment( $id )->comment_post_ID in a loop — N+1 cache lookups.
Drop to raw SQL — bypasses filters, caching, and meta-query.

In the gp-translation-helpers reference case in the Trac ticket, hydrating ~32K comments to extract distinct post IDs took ~6.6s; the equivalent raw SQL returned the same 25,694 IDs in ~610ms (~11x speedup, all of it from skipping hydration).

API

// Distinct comment_post_IDs — replaces array_unique( wp_list_pluck( ... ) ).
$post_ids = ( new WP_Comment_Query() )->query( array(
    'meta_key'   => 'locale',
    'meta_value' => 'nl',
    'user_id'    => 42,
    'fields'     => 'comment_post_ID',
) );

// [ comment_ID => comment_post_ID ] map — same shape as WP_Query's 'id=>parent'.
$by_id = ( new WP_Comment_Query() )->query( array(
    'post_id' => $post_id,
    'fields'  => 'comment_ID=>comment_post_ID',
) );

Column names must be passed in their exact case. The only exception is the ID suffix of comment_ID / comment_post_ID, which is accepted in any case (comment_id, comment_Id, comment_ID). Unknown columns fall through to the default behaviour (WP_Comment objects), keeping the path forward-compatible.

Test plan

npm run test:php -- tests/phpunit/tests/comment/query.php — 166 tests / 489 assertions pass.
npm run test:php -- --group comment — 540 tests / 1367 assertions pass (no regressions).
New tests cover:
- Single-column form returns distinct values.
- 'col_a=>col_b' map form returns associative array.
- Case-flexibility of the ID suffix on both sides of =>; strict case for non-ID columns.
- Unknown column (single + map form) falls back to full WP_Comment objects.
- 'ids' semantics unchanged.
- Empty result sets return array() without a follow-up query.
phpcs --standard=phpcs.xml.dist clean on both changed files (only pre-existing warnings on untouched lines).

🤖 Generated with Claude Code

github-actions · 2026-05-22T05:45:01Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props dd32, westonruter.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2026-05-22T05:47:52Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

Extends the `fields` argument of `WP_Comment_Query` to accept: - A column name from the `$wpdb->comments` table (e.g. `'comment_post_ID'`). Returns a flat array of distinct values for that column. - A `'col_a=>col_b'` pair (e.g. `'comment_ID=>comment_post_ID'`). Returns an associative array keyed by col_a's value, with col_b's value as the entry — mirroring `WP_Query` / `WP_Term_Query`'s `'id=>parent'` idiom. - An array of column names. Returns an array of `stdClass` objects with the requested columns as properties (one entry per matched comment, no deduplication). The motivation is to avoid hydrating full `WP_Comment` objects when the caller only needs a subset of columns. In one reference case (gp-translation-helpers), hydrating ~32K comments to extract distinct post IDs took ~6.6s; the equivalent raw SQL took ~610ms (~11x), all of it from skipping hydration. Single-column results apply `DISTINCT` in SQL so callers can drop the surrounding `array_unique( wp_list_pluck( ... ) )`. The array form does not — it returns one row per matched comment, like a hand-written projection. Field-selection results are cached separately from the base comment-ID query, sharing the comment `last_changed` salt so any comment mutation invalidates both layers together. A repeat call with identical args runs zero SQL queries. Column names must be passed in their exact case; the only exception is the `ID` suffix of `comment_ID` / `comment_post_ID`, which is accepted in any case. `'ids'` and `''` retain their existing meaning; the new behaviour is purely additive. Props dd32. See #65313. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

westonruter

An initial review pass. I'll have some more suggestions, but I'm short on time for this week.

westonruter · 2026-05-22T19:56:36Z

+	 * Return shapes:
+	 *   - `array( 'col', $column )`            — single column, DISTINCT.
+	 *   - `array( 'map', $key_col, $val_col )` — `'col_a=>col_b'` associative map.
+	 *   - `array( 'list', $columns )`          — array form, returns `stdClass[]`.


I was analyzing this method with PHPStan and this doesn't seem to be correct. It seems this is actually:

Suggested change

* - `array( 'list', $columns )` — array form, returns `stdClass[]`.

* - `array( 'list', $columns )` — array form, returns `string[]`.

I merged this, as it sounded right, and then Claude told me no-no.

Also worth re-checking: line 1048 was changed from returns stdClass[] to returns string[]. The user-facing return of the 'list' case is still stdClass[] (from $wpdb->get_results() default OBJECT mode). westonruter's PHPStan was describing the tuple payload (which holds string[] column names) — that's true but ambiguous in the prose docblock, which reads as "what the user gets back". Either keep stdClass[] and reword the line to make clear it describes the tuple's payload separately, or drop the "returns" suffix entirely.

I don't understand. What I see is this:

$columns = array(); foreach ( $fields as $field ) { $col = is_string( $field ) ? $this->parse_field_column( $field ) : null; if ( null !== $col ) { $columns[ $col ] = $col; } } return $columns ? array( 'list', array_values( $columns ) ) : null;

The $columns variable is only ever populated with the return value of $this->parse_field_column( $field ), in both its keys and values. That method returns a string (if not null).

How could it be stdClass?

Co-authored-by: Weston Ruter <westonruter@gmail.com>

Drops the stray `*/` and duplicate `@param` on `parse_fields()` that made the file fail to parse. Promotes the list of `$wpdb->comments` columns to a `private const COLUMNS`, reused by both `parse_field_column()` and `parse_orderby()`. See #65313. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

dd32 force-pushed the 65313-comment-query-fields-projections branch from 9115f83 to 5f33400 Compare May 22, 2026 05:50

dd32 force-pushed the 65313-comment-query-fields-projections branch from 5f33400 to 908e631 Compare May 22, 2026 05:55

westonruter mentioned this pull request May 22, 2026

Trac #65313: Extend WP_Comment_Query 'fields' to support individual c… #11935

Closed

westonruter reviewed May 22, 2026

View reviewed changes

dd32 and others added 2 commits May 25, 2026 13:56

Use more specific explicit data types

47d29de

Co-authored-by: Weston Ruter <westonruter@gmail.com>

dd32 force-pushed the 65313-comment-query-fields-projections branch from c40fb88 to 6174765 Compare May 25, 2026 04:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments: Allow WP_Comment_Query fields to select arbitrary columns#11934

Comments: Allow WP_Comment_Query fields to select arbitrary columns#11934
dd32 wants to merge 3 commits into
WordPress:trunkfrom
dd32:65313-comment-query-fields-projections

dd32 commented May 22, 2026

Uh oh!

github-actions Bot commented May 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 22, 2026

Uh oh!

westonruter left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

westonruter May 22, 2026

Uh oh!

dd32 May 25, 2026

Uh oh!

westonruter May 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	* - `array( 'list', $columns )` — array form, returns `stdClass[]`.
	* - `array( 'list', $columns )` — array form, returns `string[]`.

Conversation

dd32 commented May 22, 2026

Summary

Why

API

Test plan

Uh oh!

github-actions Bot commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 22, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

westonruter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

westonruter May 22, 2026

Choose a reason for hiding this comment

Uh oh!

dd32 May 25, 2026

Choose a reason for hiding this comment

Uh oh!

westonruter May 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented May 22, 2026 •

edited

Loading