Changeset 51943 for trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php

Timestamp:

10/27/2021 06:42:13 PM (3 years ago)

Author:

swissspidy

Message:

Role/Capability: Add 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.

Under the hood, this will check all existing roles on the site and perform a LIKE query against the capabilities user meta field to find:

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

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.

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 places like author dropdowns.

This updates any usage of 'who' => 'authors' in core to use capability queries instead.

Subsequently, 'who' => 'authors' queries are being deprecated in favor of these new query arguments.

Also adds a new capabilities parameter (mapping to capability__in in WP_User_Query) to the REST API users controller.

Also updates twentyfourteen_list_authors() in Twenty Fourteen to make use of this new functionality, adding a new twentyfourteen_list_authors_query_args filter to make it easier to override this behavior.

Props scribu, lgladdly, boonebgorges, spacedmonkey, peterwilsoncc, SergeyBiryukov, swissspidy.
Fixes #16841.

File:

• trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php (modified) (3 diffs)

trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php

@@ -199 +199 @@
         }
 
+        // Check if capabilities is specified in GET request and if user can list users.
+        if ( ! empty( $request['capabilities'] ) && ! current_user_can( 'list_users' ) ) {
+            return new WP_Error(
+                'rest_user_cannot_view',
+                __( 'Sorry, you are not allowed to filter users by capability.' ),
+                array( 'status' => rest_authorization_required_code() )
+            );
+        }
+
         if ( 'edit' === $request['context'] && ! current_user_can( 'list_users' ) ) {
             return new WP_Error(
@@ -255 +264 @@
          */
         $parameter_mappings = array(
-            'exclude'  => 'exclude',
-            'include'  => 'include',
-            'order'    => 'order',
-            'per_page' => 'number',
-            'search'   => 'search',
-            'roles'    => 'role__in',
-            'slug'     => 'nicename__in',
+            'exclude'      => 'exclude',
+            'include'      => 'include',
+            'order'        => 'order',
+            'per_page'     => 'number',
+            'search'       => 'search',
+            'roles'        => 'role__in',
+            'capabilities' => 'capability__in',
+            'slug'         => 'nicename__in',
         );
 
@@ -1555 +1565 @@
         );
 
+        $query_params['capabilities'] = array(
+            'description' => __( 'Limit result set to users matching at least one specific capability provided. Accepts csv list or single capability.' ),
+            'type'        => 'array',
+            'items'       => array(
+                'type' => 'string',
+            ),
+        );
+
         $query_params['who'] = array(
             'description' => __( 'Limit result set to users who are considered authors.' ),