Comment REST API route: add support for filtering by multiple statuses. by adamsilverstein · Pull Request #9870 · WordPress/wordpress-develop

adamsilverstein · 2025-09-14T19:59:35Z

Add support for filtering the comments collection endpoint by multiple statuses, eg. /wp/v2/comments?status=approve,hold or status[]=approve&status[]=hold. WP_Comment_Query already accepts an array of statuses, so this brings the REST endpoint in line with what the underlying query supports. Single string values continue to work as before.

Originally extracted from the Notes work, see WordPress/gutenberg#71271 (WordPress/gutenberg#71271 (comment))

Changes:

Define the status collection param as an array of strings, each sanitized with sanitize_key, following the pattern of the posts controller.
Update the status check in get_items_permissions_check to handle array values. Behavior is unchanged: unauthenticated requests can only use the default approve status, anything else requires edit_posts.
Add tests covering single, multiple, comma separated and all status queries, sanitization of the param, and the authorization boundary.
Regenerate the QUnit REST schema fixture.

Note: I did not add an enum of allowed values here - WP_Comment_Query explicitly supports custom comment statuses and the endpoint currently accepts any string (eg. spam and trash work today for authorized users), so an enum limited to the registered statuses would be a back compat break.

Testing instructions

On a test site, create some comments and mark a few as approved and a few as pending (the Comments screen works for this).
As an authorized user (I used an application password), request multiple statuses and verify comments from both lists are returned:
curl --user admin:APP_PASSWORD "https://example.test/wp-json/wp/v2/comments?status=approve,hold"
Request a single status, eg. ?status=hold, and verify only pending comments are returned.
Without authentication, verify ?status=approve still returns approved comments and ?status=approve,hold returns a rest_forbidden_param error.
Run the unit tests: npm run test:php -- --filter WP_Test_REST_Comments_Controller

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

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

github-actions · 2025-09-14T20:28:03Z

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

The Plugin and Theme Directories cannot be accessed within Playground.
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.

github-actions · 2025-09-15T05:19:02Z

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 adamsilverstein, westonruter, swissspidy, timothyblynjacobs, mukesh27, wildworks.

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

t-hamano · 2025-09-15T12:35:57Z

We might not need to extend the REST API itself. See WordPress/gutenberg#71271 (comment)

Co-authored-by: Pascal Birchler <pascal.birchler@gmail.com>

adamsilverstein · 2025-09-15T14:44:52Z

We might not need to extend the REST API itself. See WordPress/gutenberg#71271 (comment)

Good point; that said its probably worth adding as its a simple change and reflects what the underlying core comments class already supports (so it feels like a bug or oversight that it isn't supported already). While we don't need it yet, I could easily see us or a plugin wanting this.

TimothyBJacobs · 2025-09-15T15:03:12Z

@@ -1681,7 +1681,7 @@ public function get_collection_params() {
 			'default'           => 'approve',
 			'description'       => __( 'Limit result set to comments assigned a specific status. Requires authorization.' ),
 			'sanitize_callback' => 'sanitize_key',


This is an issue since it only does anything for strings.

Good point. I'll expand this to handle arrays based on what we do in posts. Should be straightforward to recuse existing code for each item.

Added handling in 5fba5f6 calling sanitize_key for each status.

Actually @TimothyBJacobs I'm not sure we need this -

sanitization only called when creating or updating a comment - in this case we should still only accept a single status value, right? sanitize_key would throw an error, maybe thats what we want?

Also, while writing tests, I noticed as far as I can see we already strictly enforce status values from a list in WP_Test_REST_Comments_Controller::handle_status_param. Shouldn't the endpoint accept custom status values like WP_Comment_Query?

handle_status_param is for the writes though, right? This is the arg list for the query parameters so they'd be a bit different.

Are custom comment status really supported by Core? wp_get_comment_status makes it seem like the list is fixed.

We should probably have an enum keyword with all of the supported statuses I think?

Thanks for the feedback @TimothyBJacobs

We don't need this immediately so I am deprioritizing it for the moment.

Picking this back up. I updated the param to a proper array of strings with each value run through sanitize_key, following the pattern of the posts controller, and added tests for the sanitize callback directly.

On the enum question: I looked at it and decided against for now. WP_Comment_Query explicitly accepts custom comment statuses, and the endpoint currently accepts any string here (eg. spam and trash work today for users with edit_posts), so an enum limited to the registered statuses would be a back compat break. What do you think?

Worth noting that while testing I found the status comparison in get_items_permissions_check needed updating too - with the param now an array it never string-matched approve, which broke unauthenticated requests. Fixed by comparing against the parsed list, with tests covering the authorization boundary.

…roller.php Co-authored-by: Mukesh Panchal <mukeshpanchal27@users.noreply.github.com>

Co-authored-by: Mukesh Panchal <mukeshpanchal27@users.noreply.github.com>

With the status collection param now an array, the sanitized value never string-matches 'approve', so unauthenticated requests using the default status were rejected. Compare against the parsed list instead, define the schema as an array of strings per review feedback, and regenerate the QUnit fixture to match.

…e-string>

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

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

westonruter · 2026-07-23T21:01:16Z

+	public function sanitize_comment_statuses( $statuses ): array {
+		$statuses = wp_parse_list( $statuses );
+		return array_values( array_filter( array_unique( array_map( 'sanitize_key', $statuses ) ) ) );
+	}


True, but '0' is not a valid status. So this doesn't seem necessary.

I thought so too, but it turns out '0' is queryable: WP_Comment_Query passes unrecognized statuses straight through to a comment_approved match (its default case), and held comments are stored with comment_approved of '0'. So ?status=0 works today as an alias for hold for authorized users, and sanitize_key preserves it - only the bare array_filter() dropped it. I made the filter explicit in 6dd63d2 and added the '0' cases to the sanitization tests.

westonruter

Good to add this test: #9870 (comment)

Otherwise, pre-approving.

westonruter · 2026-07-23T21:03:52Z

 					foreach ( $protected_params as $param ) {
 						if ( 'status' === $param ) {
-							if ( 'approve' !== $request[ $param ] ) {
+							if ( array( 'approve' ) !== $request[ $param ] ) {


Oh, is there a back-compat concern with the status arg now becoming an array of strings? Could there be any plugins that are looking at this parsed request param which would fail now?

Good question. The raw query string is unchanged, but once sanitization runs (which happens before the permission callback), $request['status'] is always an array - so a plugin doing a string comparison against the parsed param, eg. 'approve' === $request['status'] inside a rest_comment_query filter callback, would now see array( 'approve' ) and fail. $prepared_args['status'] handed to WP_Comment_Query also becomes an array, though that part is transparent since the query class accepts both forms.

So yes, there is a narrow back compat surface for code inspecting the parsed request param directly. It matches the shape the posts controller status param has had since 4.7 ([39104], https://core.trac.wordpress.org/ticket/38420), so the pattern is well established. I'd rather call this out in the dev note than try to preserve the string shape for single values, which would make the parsed type unpredictable. What do you think?

I can try searching https://veloria.dev/ but may be hard to be sure without a ton of digging. I can also merge this in early 7.2 so there is plenty of time to get feedback.

Yeah, I think it's ok.

The unauthenticated 401 boundary was only covered for the array form of the status parameter. Since the permission check now relies on the sanitize callback having parsed the raw value, the comma-separated form needs its own case so it cannot regress independently. Convert the test to a data provider covering both forms.

array_filter() without a callback drops all falsy strings, including '0'. WP_Comment_Query treats a literal '0' status as a direct comment_approved match (how held comments are stored), so ?status=0 is a working query today and must survive sanitization. Filter only empty strings instead.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

mukeshpanchal27 · 2026-07-24T04:49:48Z

@@ -1777,9 +1777,12 @@ public function get_collection_params() {

 		$query_params['status'] = array(
 			'default'           => 'approve',


@adamsilverstein Why this one is still string instead of array?

I guess the endpoint will accept a string or array? Still for consistency you are right this should probably be an array.

adamsilverstein added 4 commits September 14, 2025 12:58

Comments REST endpoint - support for multiple status values

82c76fa

Add tests for getting comments by status, statuses or ‘all’

1fc983f

spacing fixes for linter

4ee6fe8

Use count

bdd5a6d

Complete tests for status field

b878d8b

adamsilverstein changed the title ~~Add/comment rest api types support~~ Comment REST API route: add support for status as array Sep 15, 2025

adamsilverstein marked this pull request as ready for review September 15, 2025 05:18

adamsilverstein mentioned this pull request Sep 15, 2025

Block comments: Add comment indicators in the block toolbar WordPress/gutenberg#71271

Merged

adamsilverstein changed the title ~~Comment REST API route: add support for status as array~~ Comment REST API route: add support multiple statuses Sep 15, 2025

update wp-api-generated

f435d93

swissspidy reviewed Sep 15, 2025

View reviewed changes

Comment thread tests/phpunit/tests/rest-api/rest-comments-controller.php Outdated

Update tests/phpunit/tests/rest-api/rest-comments-controller.php

7b22c39

Co-authored-by: Pascal Birchler <pascal.birchler@gmail.com>

hello yoda my old friend

6225ae6

TimothyBJacobs reviewed Sep 15, 2025

View reviewed changes

Comment thread src/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php Outdated

TimothyBJacobs reviewed Sep 15, 2025

View reviewed changes

adamsilverstein added 3 commits September 15, 2025 15:26

API handles strings automatically when array type given

f121b3e

Handle multiple status sanitization

5fba5f6

Add additional tests

1ee7a86

mukeshpanchal27 reviewed Sep 16, 2025

View reviewed changes

Comment thread src/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php Outdated

Update src/wp-includes/rest-api/endpoints/class-wp-rest-comments-cont…

3bf3121

…roller.php Co-authored-by: Mukesh Panchal <mukeshpanchal27@users.noreply.github.com>

mukeshpanchal27 reviewed Sep 18, 2025

View reviewed changes

Comment thread tests/phpunit/tests/rest-api/rest-comments-controller.php Outdated

Update tests/phpunit/tests/rest-api/rest-comments-controller.php

f210ce5

Co-authored-by: Mukesh Panchal <mukeshpanchal27@users.noreply.github.com>

adamsilverstein changed the title ~~Comment REST API route: add support multiple statuses~~ [WIP] Comment REST API route: add support multiple statuses Sep 18, 2025

pento force-pushed the trunk branch from 3af2d27 to 64ede28 Compare July 6, 2026 03:10

adamsilverstein added 2 commits July 23, 2026 09:06

Merge trunk into add/comment-rest-api-types-support

faca069

westonruter added 4 commits July 23, 2026 13:39

Tighten sanitize_comment_statuses() to return list<non-empty-lowercas…

cd4496f

…e-string>

Add typing to data_sanitize_comment_statuses

c1c7823

Add native type hints to test class properties

f44de34

Address PHPStan issues in tests

b9b22de

Copilot AI review requested due to automatic review settings July 23, 2026 20:49

Copilot started reviewing on behalf of westonruter July 23, 2026 20:50 View session

Apply suggestions from code review

9a34a07

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

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread src/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php

Copilot AI review requested due to automatic review settings July 23, 2026 20:53

Copilot started reviewing on behalf of adamsilverstein July 23, 2026 20:54 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

adamsilverstein requested review from dmsnell, joedolson, t-hamano and westonruter and removed request for dmsnell, joedolson, t-hamano and westonruter July 23, 2026 20:56

westonruter approved these changes Jul 23, 2026

View reviewed changes

westonruter reviewed Jul 23, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 23, 2026 22:52

Copilot started reviewing on behalf of adamsilverstein July 23, 2026 22:55 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 23, 2026 22:59

Copilot started reviewing on behalf of adamsilverstein July 23, 2026 22:59 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

mukeshpanchal27 reviewed Jul 24, 2026

View reviewed changes

		@@ -1777,9 +1777,12 @@ public function get_collection_params() {

		$query_params['status'] = array(
		'default' => 'approve',

Uh oh!

Conversation

adamsilverstein commented Sep 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Testing instructions

Uh oh!

github-actions Bot commented Sep 14, 2025

Test using WordPress Playground

Some things to be aware of

Uh oh!

github-actions Bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

t-hamano commented Sep 15, 2025

Uh oh!

adamsilverstein commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamsilverstein Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamsilverstein Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

westonruter left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

adamsilverstein commented Sep 14, 2025 •

edited

Loading

github-actions Bot commented Sep 15, 2025 •

edited

Loading

adamsilverstein commented Sep 15, 2025 •

edited

Loading

adamsilverstein Sep 15, 2025 •

edited

Loading

adamsilverstein Jul 23, 2026 •

edited

Loading