Mark who=authors as deprecated in docblock

[kkmuffme]

when editing a post/page e.g. /wp-json/wp/v2/users?context=view&who=authors&per_page=50&_fields=id%2Cname&_locale=user

WP_User_Query was called with an argument that is deprecated since version 5.9.0! "who" is deprecated. Use "capability" instead.

Caused by wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php

---

Additionally, this is there (and incorrectly documented?) in function wp_dropdown_users:

@type string $who Which type of users to query. Accepts only an empty string or 'authors'. Default empty.

And even in the function that deprecates it itself: public function prepare_query
The docs for $who still says 'authors', which is deprecated though.

[swissspidy]

This is already being tracked in ​https://github.com/WordPress/gutenberg/issues/39986

[kkmuffme]

That ticket is solely about gutenberg using the deprecated way and that's a separate issue - besides the point it seems it has been forgotten, since the last comment was almost 2 years ago stating it should now be fixed.

The issue here is that the function PHPDoc in WP is wrong too, since the WP PHPDoc still states that "authors" is a valid "who", while the function reports it as deprecated.

[swissspidy]

It‘s not separate, it‘s literally what‘s reported here.

[kkmuffme]

Maybe I'm blind, but all I see there is changes needed to gutenberg?
But the files with issues are completely unrelated to gutenberg:
​https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/class-wp-user-query.php#L245
​https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/user.php#L1583
​https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php#L309

It's not only gutenberg that uses that, but any plugin or theme can use that.

Type changed from defect (bug) to enhancement

How is fixing a deprecated error and docs an enhancement?

[swissspidy]

Simple:

There is no issue in core.

The who=authors usage was deprecated in core in favor of a new way (capability queries). Gutenberg has still not adopted the new feature, hence the deprecation warning.
This needs to be fixed solely in Gutenberg, by using capability queries. No change is needed im core.

The second part of the ticket suggested improving the docblock for the deprecated usage.

[kkmuffme]

The second part of the ticket suggested improving the docblock for the deprecated usage.

Don't want to get philosophical but if something is wrong and you correct it, it's generally called fixing a bug, isn't it? :-)

This needs to be fixed solely in Gutenberg

Yes, the caller needs to be fixed in gutenberg. What I mean is that once that's fixed there, this condition ​https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php#L309 should be removed in core too (as there's no mention of that on the gutenberg issue)

[swissspidy]

No, it must not be removed for backward compatibility reasons.

[kkmuffme]

And at what point should it get removed? It was deprecated in 5.9, which is 7 versions and more than 2 years ago.

[swissspidy]

It might never get removed if there‘s no need & no harm in keeping in it. WordPress never really removes deprecated functions either.

[SergeyBiryukov]

In 58172:

Docs: Add a note that the who parameter in WP_User_Query is deprecated.

Any usage of 'who' => 'authors' should be updated to use capability queries instead.

Includes documenting the capability query parameters in wp_dropdown_users().

Follow-up to [51943].

Props kkmuffme, swissspidy, SergeyBiryukov.
See #61243.

[swissspidy]

Nothing else to be done here