[adamsilverstein]

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

1. On a test site, create some comments and mark a few as approved and a few as pending (the Comments screen works for this).
2. 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"
3. Request a single status, eg. ?status=hold, and verify only pending comments are returned.
4. Without authentication, verify ?status=approve still returns approved comments and ?status=approve,hold returns a rest_forbidden_param error.
5. 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.

Commit message

REST API: Allow filtering comments by multiple statuses.

Fix an issue where the comments collection endpoint only accepted a single `status` value, even though `WP_Comment_Query` has always supported an array of statuses. This forced clients that need comments in more than one status, such as approved and pending notes, to make a separate request for each. The `status` collection parameter is now defined as an array of strings, so it accepts a comma-separated list (`?status=approve,hold`) or an array (`?status[]=approve&status[]=hold`). Values are sanitized by the new `WP_REST_Comments_Controller::sanitize_comment_statuses()` method.

Single status requests work as before, and the permission check is unchanged: unauthenticated requests may only use the default `approve` status. Because the parameter is now always an array after sanitization, code reading `$request['status']` or `status` in the `rest_comment_query` filter receives an array instead of a string.

Props adamsilverstein, westonruter, swissspidy, timothyblynjacobs, mukesh27, wildworks.
Fixes #63982.

[github-actions]

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]

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]

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

[adamsilverstein]

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.

[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.

[t-hamano]

@adamsilverstein, this PR looks good to merge, but do you have any concerns?

[adamsilverstein]

@adamsilverstein, this PR looks good to merge, but do you have any concerns?

I think its ready, sweeping for unaddressed feedback.

[adamsilverstein]

@adamsilverstein, this PR looks good to merge, but do you have any concerns?

Looks good to me!

[t-hamano]

Looks good from my end. It might be worth noting the definition change under miscellaneous dev notes.

[adamsilverstein]

Drafted with Claude for the WordPress 7.2 miscellaneous developer changes post:

Comments REST API: filter by multiple statuses

The comments collection endpoint (/wp/v2/comments) now accepts more than one value for the status parameter, either as a comma-separated list or as an array:

/wp/v2/comments?status=approve,hold
/wp/v2/comments?status[]=approve&status[]=hold

WP_Comment_Query has always accepted an array of statuses, so this brings the REST endpoint in line with the underlying query. Single values like ?status=hold work exactly as before, and the permission rules are unchanged: unauthenticated requests can only use the default approve status, anything else requires authorization.

To support this, the definition of the status collection parameter changed:

• type is now array (with items of type string) instead of string.
• default is now array( 'approve' ) instead of 'approve'.
• Values are sanitized with the new WP_REST_Comments_Controller::sanitize_comment_statuses() method, which runs each status through sanitize_key() and removes duplicates and empty values.

Code that reads the status as a string may need an update. After sanitization, $request['status'] is always an array, even for a single status, so $prepared_args['status'] in the rest_comment_query filter is now an array too. Code that compares it to a string (eg. 'approve' === $prepared_args['status']) or passes it to string functions should handle an array instead. Plugins that change the status parameter through the rest_comment_collection_params filter, and clients that read the endpoint schema, should also expect the new array definition.

See https://core.trac.wordpress.org/ticket/63982 for more details.

[github-actions]

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 64494
GitHub commit: a17507f

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.

[dmsnell]

some late follow-up here is that we’re performing a lot of needless allocation here, and while the performance impact of this function is likely not relevant in the overall picture, it’s still part of painting that.

effectively this could be replaced by one big iteration, rather than the current five passes with intermediate arrays.

here is an alternative idea skipping that allocation.

if ( is_string( $statuses ) ) {
	$statuses = wp_parse_list( $statuses );
}

$sanitized = array();
$seen      = array();
foreach ( $statuses as $status ) {
	if ( ! is_scalar( $status ) ) {
		continue;
	}

	$key = sanitize_key( $status );
	if ( '' === $key || isset( $seen[ $key ] ) ) {
		continue;
	}

	$seen[ $key ] = true;
	$sanitized[]  = $key;
}

return $sanitized;

[adamsilverstein]

Thanks for the feedback @dmsnell, I'll open a follow up PR to optimize this.

[westonruter]

Good point. And since the number of statuses is going to be very very small, then a hash lookup for $seen would be less performant than just a regular list. So this would seem to be even better:

if ( is_string( $statuses ) ) {
	$statuses = wp_parse_list( $statuses );
}

$sanitized = array();
foreach ( $statuses as $status ) {
	if ( ! is_scalar( $status ) ) {
		continue;
	}

	$key = sanitize_key( $status );
	if ( '' !== $key && ! in_array( $key, $sanitized, true ) ) {
		$sanitized[] = $key;
	}
}

return $sanitized;

[westonruter]

Note to self: widen the $key param in sanitize_key() from string to scalar since it is explicitly supported.

[dmsnell]

since the number of statuses is going to be very very small

it depends if we can guarantee that @westonruter. I have been using this pattern too, but if the list of statuses is user-provided, then there are catastrophic cases that lead to DoS

so if we assume the list is small, we should make sure before we introduce quadtratic lookup.