Make WordPress Core

Opened 6 months ago

Closed 6 months ago

#61243 closed defect (bug) (fixed)

Mark who=authors as deprecated in docblock

Reported by: kkmuffme's profile kkmuffme Owned by:
Milestone: 6.6 Priority: low
Severity: trivial Version: 5.9
Component: Users Keywords:
Focuses: docs Cc:

Description

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.

Change History (11)

#1 @swissspidy
6 months ago

  • Component changed from Users to Editor
  • Milestone Awaiting Review deleted
  • Resolution set to reported-upstream
  • Status changed from new to closed

#2 @kkmuffme
6 months ago

  • Resolution reported-upstream deleted
  • Status changed from closed to reopened

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.

#3 @swissspidy
6 months ago

  • Component changed from Editor to Users
  • Focuses docs added
  • Milestone set to 6.6
  • Priority changed from normal to low
  • Severity changed from major to trivial
  • Summary changed from Deprecated notices who=authors and invalid documentation to Mark who=authors as deprecated in docblock
  • Type changed from defect (bug) to enhancement

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

#4 @kkmuffme
6 months ago

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?

#5 @swissspidy
6 months ago

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.

#6 @kkmuffme
6 months ago

  • Type changed from enhancement to defect (bug)

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)

#7 @swissspidy
6 months ago

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

#8 @kkmuffme
6 months ago

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

#9 @swissspidy
6 months ago

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

#10 @SergeyBiryukov
6 months ago

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.

#11 @swissspidy
6 months ago

  • Resolution set to fixed
  • Status changed from reopened to closed

Nothing else to be done here

Note: See TracTickets for help on using tickets.