New Capability Queries in WordPress 5.9

WordPress 5.9 adds support for capability queries in WP_User_Query. Similar to the existing role/role__in/role__not_in query arguments, this adds support for three new query arguments in WP_User_Query:

  • capability
  • capability__in
  • capability__not_in

These can be used to fetch users with (or without) a specific set of capabilities, for example to get all users with the capability to edit a certain post type.

A new capabilities parameter (mapping to capability__in in WP_User_Query) was added to the REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) users controller so you can also perform these queries via the REST API.

Under the hood, this will check all existing roles on the site and perform a LIKE query against the capabilities user metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. field to find:

  • all users with a role that has this capability
  • all users with the capability being assigned directly

Important note: In WordPress, not all capabilities are stored in the database. Capabilities can also be modified using filters like map_meta_cap. These new query arguments do not work for such capabilities.

The prime use case for capability queries is to get all “authors”, i.e. users with the capability to edit a certain post type. This is needed for the post author dropdown in the post editor, for instance.

Until now, 'who' => 'authors' was used for this, which relies on user levels. However, user levels were deprecated a long time ago and thus never added to custom roles. This led to constant frustration due to users with custom roles missing from author dropdowns.

Thanks to this new feature, any usage of 'who' => 'authors' in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. was updated to use capability queries instead.

Subsequently, 'who' => 'authors' queries were deprecated in favor of these new query arguments. The same goes for ?who=authors queries for thewp/v2/users REST API endpoint.

In the same run, the twentyfourteen_list_authors() function in the Twenty Fourteen theme was updated to make use of this new functionality, adding a new twentyfourteen_list_authors_query_args filterFilter Filters are one of the two types of Hooks They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. to make it easier to override this behavior.

Making use of capability queries while retaining compatibility for older WordPress versions, one could use code as follows to support both:

$args = array(
	'orderby'    => 'post_count',
	'order'      => 'DESC',
	'capability' => array( 'edit_posts' ),

// Capability queries were only introduced in WP 5.9.
if ( version_compare( $GLOBALS['wp_version'], '5.9-alpha', '<' ) ) {
	$args['who'] = 'authors';
	unset( $args['capability'] );

$authors = get_users( $args );

To learn more about this change and the 11-year-old bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. it fixed, check out #16841, [51943], and [52290]

#5-9, #dev-notes