Changeset 51943 for trunk/src/wp-includes/class-wp-user-query.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/class-wp-user-query.php (modified) (6 diffs)

trunk/src/wp-includes/class-wp-user-query.php

@@ -94 +94 @@
             'role__in'            => array(),
             'role__not_in'        => array(),
+            'capability'          => '',
+            'capability__in'      => array(),
+            'capability__not_in'  => array(),
             'meta_key'            => '',
             'meta_value'          => '',
@@ -134 +137 @@
      * @since 4.7.0 Added 'nicename', 'nicename__in', 'nicename__not_in', 'login', 'login__in',
      *              and 'login__not_in' parameters.
+     * @since 5.9.0 Added 'capability', 'capability__in', and 'capability__not_in' parameters.
      *
      * @global wpdb $wpdb WordPress database abstraction object.
@@ -149 +153 @@
      *     @type string[]     $role__not_in        An array of role names to exclude. Users matching one or more of these
      *                                             roles will not be included in results. Default empty array.
+     *     @type string       $capability          An array or a comma-separated list of capability names that users must match
+     *                                             to be included in results. Note that this is an inclusive list: users
+     *                                             must match *each* capability.
+     *                                             Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}.
+     *                                             Default empty.
+     *     @type string[]     $capability__in      An array of capability names. Matched users must have at least one of these
+     *                                             capabilities.
+     *                                             Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}.
+     *                                             Default empty array.
+     *     @type string[]     $capability__not_in  An array of capability names to exclude. Users matching one or more of these
+     *                                             capabilities will not be included in results.
+     *                                             Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}.
+     *                                             Default empty array.
      *     @type string       $meta_key            User meta key. Default empty.
      *     @type string       $meta_value          User meta value. Default empty.
@@ -321 +338 @@
 
         if ( isset( $qv['who'] ) && 'authors' === $qv['who'] && $blog_id ) {
+            _deprecated_argument(
+                'WP_User_Query',
+                '5.9.0',
+                sprintf(
+                    /* translators: 1: who, 2: capability */
+                    __( '%1$s is deprecated. Use %2$s instead.' ),
+                    '<code>who</code>',
+                    '<code>capability</code>'
+                )
+            );
+
             $who_query = array(
                 'key'     => $wpdb->get_blog_prefix( $blog_id ) . 'user_level',
@@ -344 +372 @@
         }
 
+        // Roles.
         $roles = array();
         if ( isset( $qv['role'] ) ) {
@@ -361 +390 @@
         if ( isset( $qv['role__not_in'] ) ) {
             $role__not_in = (array) $qv['role__not_in'];
+        }
+
+        // Capabilities.
+        $available_roles = array();
+
+        if ( ! empty( $qv['capability'] ) || ! empty( $qv['capability__in'] ) || ! empty( $qv['capability__not_in'] ) ) {
+            global $wp_roles;
+
+            $wp_roles->for_site( $blog_id );
+            $available_roles = $wp_roles->roles;
+        }
+
+        $capabilities = array();
+        if ( ! empty( $qv['capability'] ) ) {
+            if ( is_array( $qv['capability'] ) ) {
+                $capabilities = $qv['capability'];
+            } elseif ( is_string( $qv['capability'] ) ) {
+                $capabilities = array_map( 'trim', explode( ',', $qv['capability'] ) );
+            }
+        }
+
+        $capability__in = array();
+        if ( ! empty( $qv['capability__in'] ) ) {
+            $capability__in = (array) $qv['capability__in'];
+        }
+
+        $capability__not_in = array();
+        if ( ! empty( $qv['capability__not_in'] ) ) {
+            $capability__not_in = (array) $qv['capability__not_in'];
+        }
+
+        // Keep track of all capabilities and the roles they're added on.
+        $caps_with_roles = array();
+
+        foreach ( $available_roles as $role => $role_data ) {
+            $role_caps = array_keys( array_filter( $role_data['capabilities'] ) );
+
+            foreach ( $capabilities as $cap ) {
+                if ( in_array( $cap, $role_caps, true ) ) {
+                    $caps_with_roles[ $cap ][] = $role;
+                    break;
+                }
+            }
+
+            foreach ( $capability__in as $cap ) {
+                if ( in_array( $cap, $role_caps, true ) ) {
+                    $role__in[] = $role;
+                    break;
+                }
+            }
+
+            foreach ( $capability__not_in as $cap ) {
+                if ( in_array( $cap, $role_caps, true ) ) {
+                    $role__not_in[] = $role;
+                    break;
+                }
+            }
+        }
+
+        $role__in     = array_merge( $role__in, $capability__in );
+        $role__not_in = array_merge( $role__not_in, $capability__not_in );
+
+        $roles        = array_unique( $roles );
+        $role__in     = array_unique( $role__in );
+        $role__not_in = array_unique( $role__not_in );
+
+        // Support querying by capabilities added directly to users.
+        if ( $blog_id && ! empty( $capabilities ) ) {
+            $capabilities_clauses = array( 'relation' => 'AND' );
+
+            foreach ( $capabilities as $cap ) {
+                $clause = array( 'relation' => 'OR' );
+
+                $clause[] = array(
+                    'key'     => $wpdb->get_blog_prefix( $blog_id ) . 'capabilities',
+                    'value'   => '"' . $cap . '"',
+                    'compare' => 'LIKE',
+                );
+
+                if ( ! empty( $caps_with_roles[ $cap ] ) ) {
+                    foreach ( $caps_with_roles[ $cap ] as $role ) {
+                        $clause[] = array(
+                            'key'     => $wpdb->get_blog_prefix( $blog_id ) . 'capabilities',
+                            'value'   => '"' . $role . '"',
+                            'compare' => 'LIKE',
+                        );
+                    }
+                }
+
+                $capabilities_clauses[] = $clause;
+            }
+
+            $role_queries[] = $capabilities_clauses;
+
+            if ( empty( $this->meta_query->queries ) ) {
+                $this->meta_query->queries[] = $capabilities_clauses;
+            } else {
+                // Append the cap query to the original queries and reparse the query.
+                $this->meta_query->queries = array(
+                    'relation' => 'AND',
+                    array( $this->meta_query->queries, array( $capabilities_clauses ) ),
+                );
+            }
+
+            $this->meta_query->parse_query_vars( $this->meta_query->queries );
         }