Ticket #22212: 22212.2.diff

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

@@ -48 +48 @@
          *
          * @since 4.2.0
          * @access public
-         * @var object WP_Meta_Query
+         * @var WP_Meta_Query
          */
         public $meta_query = false;
 
@@ -88 +88 @@
                 $defaults = array(
                         'blog_id' => $GLOBALS['blog_id'],
                         'role' => '',
+                        'role__in' => array(),
+                        'role__not_in' => array(),
                         'meta_key' => '',
                         'meta_value' => '',
                         'meta_compare' => '',
@@ -117 +119 @@
          * @since 4.2.0 Added 'meta_value_num' support for `$orderby` parameter. Added multi-dimensional array syntax
          *              for `$orderby` parameter.
          * @since 4.3.0 Added 'has_published_posts' parameter.
-         * @since 4.4.0 Added 'paged' parameter.
+         * @since 4.4.0 Added 'paged', 'role__in', and 'role__not_in' parameters. 'role' parameter was updated to
+         *              permit an array or comma-separated list of values.
          * @access public
          *
          * @global wpdb $wpdb
@@ -127 +130 @@
          *     Optional. Array or string of Query parameters.
          *
          *     @type int          $blog_id             The site ID. Default is the global blog id.
-         *     @type string       $role                Role name. Default empty.
+         *     @type string|array $role                An array or a comma-separated list of role names that users must match
+         *                                             to be included in results. Note that this is an inclusive list: users
+         *                                             must match *each* role. Default empty.
+         *     @type array        $role__in            An array of role names. Matched users must have at least one of these
+         *                                             roles. Default empty array.
+         *     @type array        $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       $meta_key            User meta key. Default empty.
          *     @type string       $meta_value          User meta value. Default empty.
          *     @type string       $meta_compare        Comparison operator to test the `$meta_value`. Accepts '=', '!=',
@@ -259 +268 @@
                 $this->meta_query = new WP_Meta_Query();
                 $this->meta_query->parse_query_vars( $qv );
 
-                $role = '';
+                $roles = array();
                 if ( isset( $qv['role'] ) ) {
-                        $role = trim( $qv['role'] );
+                        if ( is_array( $qv['role'] ) ) {
+                                $roles = $qv['role'];
+                        } elseif ( is_string( $qv['role'] ) && ! empty( $qv['role'] ) ) {
+                                $roles = array_map( 'trim', explode( ',', $qv['role'] ) );
+                        }
+                }
+
+                $role__in = array();
+                if ( isset( $qv['role__in'] ) ) {
+                        $role__in = (array) $qv['role__in'];
                 }
 
-                if ( $blog_id && ( $role || is_multisite() ) ) {
-                        $cap_meta_query = array();
-                        $cap_meta_query['key'] = $wpdb->get_blog_prefix( $blog_id ) . 'capabilities';
+                $role__not_in = array();
+                if ( isset( $qv['role__not_in'] ) ) {
+                        $role__not_in = (array) $qv['role__not_in'];
+                }
 
-                        if ( $role ) {
-                                $cap_meta_query['value'] = '"' . $role . '"';
-                                $cap_meta_query['compare'] = 'like';
+                if ( $blog_id && ( ! empty( $roles ) || ! empty( $role__in ) || ! empty( $role__not_in ) || is_multisite() ) ) {
+                        $role_queries  = array();
+
+                        $roles_clauses = array( 'relation' => 'AND' );
+                        if ( ! empty( $roles ) ) {
+                                foreach ( $roles as $role ) {
+                                        $roles_clauses[] = array(
+                                                'key'     => $wpdb->get_blog_prefix( $blog_id ) . 'capabilities',
+                                                'value'   => $role,
+                                                'compare' => 'LIKE',
+                                        );
+                                }
+
+                                // Sanity check: this clause may already have been added to the meta_query.
+                                if ( empty( $this->meta_query->queries ) || ! in_array( $roles_clauses, $this->meta_query->queries, true ) ) {
+                                        $role_queries[] = $roles_clauses;
+                                }
                         }
 
+                        $role__in_clauses = array( 'relation' => 'OR' );
+                        if ( ! empty( $role__in ) ) {
+                                foreach ( $role__in as $role ) {
+                                        $role__in_clauses[] = array(
+                                                'key'     => $wpdb->get_blog_prefix( $blog_id ) . 'capabilities',
+                                                'value'   => $role,
+                                                'compare' => 'LIKE',
+                                        );
+                                }
+
+                                // Sanity check: this clause may already have been added to the meta_query.
+                                if ( empty( $this->meta_query->queries ) || ! in_array( $role__in_clauses, $this->meta_query->queries, true ) ) {
+                                        $role_queries[] = $role__in_clauses;
+                                }
+                        }
+
+                        $role__not_in_clauses = array( 'relation' => 'AND' );
+                        if ( ! empty( $role__not_in ) ) {
+                                foreach ( $role__not_in as $role ) {
+                                        $role__not_in_clauses[] = array(
+                                                'key'     => $wpdb->get_blog_prefix( $blog_id ) . 'capabilities',
+                                                'value'   => $role,
+                                                'compare' => 'NOT LIKE',
+                                        );
+                                }
+
+                                // Sanity check: this clause may already have been added to the meta_query.
+                                if ( empty( $this->meta_query->queries ) || ! in_array( $role__not_in_clauses, $this->meta_query->queries, true ) ) {
+                                        $role_queries[] = $role__not_in_clauses;
+                                }
+                        }
+
+                        // If there are no specific roles named, make sure the user has at least one role.
+                        if ( empty( $role_queries ) ) {
+                                $role_queries[] = array(
+                                        'key' => $wpdb->get_blog_prefix( $blog_id ) . 'capabilities',
+                                        'compare' => 'EXISTS',
+                                );
+                        }
+
+                        // Specify that role queries should be joined with AND.
+                        $role_queries['relation'] = 'AND';
+
                         if ( empty( $this->meta_query->queries ) ) {
-                                $this->meta_query->queries = array( $cap_meta_query );
-                        } elseif ( ! in_array( $cap_meta_query, $this->meta_query->queries, true ) ) {
+                                $this->meta_query->queries = $role_queries;
+                        } 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, $cap_meta_query ),
+                                        array( $this->meta_query->queries, $role_queries ),
                                 );
                         }
 

tests/phpunit/tests/user/query.php

@@ -896 +896 @@
                         unset( $q->query_vars[ $k ] );
                 }
         }
+
+        /**
+         * @ticket 22212
+         */
+        public function test_get_single_role_by_user_query() {
+                $this->factory->user->create_many( 2, array(
+                        'role' => 'subscriber',
+                ) );
+
+                $this->factory->user->create( array(
+                        'role' => 'contributor',
+                ) );
+
+                $wp_user_search = new WP_User_Query( array( 'role' => 'subscriber' ) );
+                $users          = $wp_user_search->get_results();
+
+                $this->assertEquals( 2, count( $users ) );
+        }
+
+        /**
+         * @ticket 22212
+         */
+        public function test_get_multiple_roles_by_user_query() {
+                $this->factory->user->create_many( 2, array(
+                        'role' => 'subscriber',
+                ) );
+
+                $this->factory->user->create_many( 3, array(
+                        'role' => 'editor',
+                ) );
+
+                $this->factory->user->create( array(
+                        'role' => 'contributor',
+                ) );
+
+                $wp_user_search = new WP_User_Query( array( 'role__in' => array( 'subscriber', 'editor' ) ) );
+                $users          = $wp_user_search->get_results();
+                $this->assertEquals( 5, count( $users ) );
+        }
+
+        /**
+         * @ticket 22212
+         */
+        public function test_get_single_role_by_string() {
+                $this->factory->user->create_many( 2, array(
+                        'role' => 'subscriber',
+                ) );
+
+                $this->factory->user->create( array(
+                        'role' => 'contributor',
+                ) );
+
+                $users = get_users( array(
+                        'role' => 'subscriber',
+                ) );
+
+                $this->assertEquals( 2, count( $users ) );
+        }
+
+        /**
+         * @ticket 22212
+         */
+        public function test_get_single_role_by_array() {
+                $this->factory->user->create_many( 2, array(
+                        'role' => 'subscriber',
+                ) );
+
+                $this->factory->user->create( array(
+                        'role' => 'contributor',
+                ) );
+
+                $users = get_users( array(
+                        'role' => array( 'subscriber' ),
+                ) );
+
+                $this->assertEquals( 2, count( $users ) );
+        }
+
+        /**
+         * @ticket 22212
+         */
+        public function test_get_multiple_roles_should_only_match_users_who_have_each_role() {
+                $subscribers = $this->factory->user->create_many( 2, array(
+                        'role' => 'subscriber',
+                ) );
+
+                $this->factory->user->create_many( 3, array(
+                        'role' => 'editor',
+                ) );
+
+                $this->factory->user->create_many( 2, array(
+                        'role' => 'administrator',
+                ) );
+
+                $users = new WP_User_Query( array( 'role' => array( 'subscriber', 'editor' ) ) );
+                $users = $users->get_results();
+
+                $this->assertEmpty( $users );
+
+                foreach ( $subscribers as $subscriber ) {
+                        $subscriber = get_user_by( 'ID', $subscriber );
+                        $subscriber->add_role( 'editor' );
+                }
+
+                $users = new WP_User_Query( array( 'role' => array( 'subscriber', 'editor' ) ) );
+                $users = $users->get_results();
+
+                $this->assertEquals( 2, count( $users ) );
+
+                foreach ( $users as $user ) {
+                        $this->assertInstanceOf( 'WP_User', $user );
+                }
+        }
+
+        /**
+         * @ticket 22212
+         */
+        public function test_get_multiple_roles_or() {
+                $this->factory->user->create_many( 2, array(
+                        'role' => 'subscriber',
+                ) );
+
+                $this->factory->user->create_many( 3, array(
+                        'role' => 'editor',
+                ) );
+
+                $this->factory->user->create_many( 2, array(
+                        'role' => 'administrator',
+                ) );
+
+                $this->factory->user->create_many( 1, array(
+                        'role' => 'contributor',
+                ) );
+
+                $users = new WP_User_Query( array( 'role__in' => array( 'subscriber', 'editor', 'administrator' ) ) );
+                $users = $users->get_results();
+
+                // +1 for the default user created during installation.
+                $this->assertEquals( 8, count( $users ) );
+                foreach ( $users as $user ) {
+                        $this->assertInstanceOf( 'WP_User', $user );
+                }
+        }
+
+        /**
+         * @ticket 22212
+         */
+        public function test_get_multiple_roles_by_comma_separated_list() {
+                $subscribers = $this->factory->user->create_many( 2, array(
+                        'role' => 'subscriber',
+                ) );
+
+                $this->factory->user->create_many( 3, array(
+                        'role' => 'editor',
+                ) );
+
+                $users = get_users( array(
+                        'role' => 'subscriber, editor',
+                ) );
+
+                $this->assertEmpty( $users );
+
+                foreach ( $subscribers as $subscriber ) {
+                        $subscriber = get_user_by( 'ID', $subscriber );
+                        $subscriber->add_role( 'editor' );
+                }
+
+                $users = get_users( array(
+                        'role' => 'subscriber, editor',
+                ) );
+
+                $this->assertEquals( 2, count( $users ) );
+        }
+
+        /**
+         * @ticket 22212
+         */
+        public function test_get_multiple_roles_with_meta() {
+                // Create administrator user + meta
+                $administrator_id = $this->factory->user->create( array( 'role' => 'administrator' ) );
+                update_user_meta( $administrator_id, 'mk1', 1 );
+                update_user_meta( $administrator_id, 'mk2', 1 );
+
+                // Create editor user + meta
+                $editor_id = $this->factory->user->create( array( 'role' => 'editor' ) );
+                update_user_meta( $editor_id, 'mk1', 1 );
+                update_user_meta( $editor_id, 'mk2', 2 );
+
+                // Create subscriber user + meta
+                $subscriber_id = $this->factory->user->create( array( 'role' => 'subscriber' ) );
+                update_user_meta( $subscriber_id, 'mk1', 1 );
+                update_user_meta( $subscriber_id, 'mk2', 1 );
+
+                // Create contributor user + meta
+                $contributor_id = $this->factory->user->create( array( 'role' => 'contributor' ) );
+                update_user_meta( $contributor_id, 'mk1', 1 );
+                update_user_meta( $contributor_id, 'mk2', 2 );
+
+                // Fetch users
+                $users = get_users( array(
+                        'role__in'   => array( 'administrator', 'editor', 'subscriber' ),
+                        'meta_query' => array(
+                                'relation' => 'AND',
+                                array(
+                                        'key'     => 'mk1',
+                                        'value'   => '1',
+                                        'compare' => "=",
+                                        'type'    => 'numeric',
+                                ),
+                                array(
+                                        'key'     => 'mk2',
+                                        'value'   => '2',
+                                        'compare' => "=",
+                                        'type'    => 'numeric',
+                                ),
+                        ),
+                ) );
+
+                // Check results
+                $this->assertEquals( 1, count( $users ) );
+                $this->assertSame( $editor_id, (int) $users[0]->ID );
+        }
+
+        /**
+         * @ticket 22212
+         */
+        public function test_role_exclusion() {
+                $this->factory->user->create_many( 2, array(
+                        'role' => 'subscriber',
+                ) );
+
+                $this->factory->user->create_many( 3, array(
+                        'role' => 'editor',
+                ) );
+
+                $users = get_users( array(
+                        'role__not_in' => 'subscriber',
+                ) );
+
+                // +1 for the default user created during installation.
+                $this->assertEquals( 4, count( $users ) );
+
+                $users = get_users( array(
+                        'role__not_in' => 'editor',
+                ) );
+
+                // +1 for the default user created during installation.
+                $this->assertEquals( 3, count( $users ) );
+        }
+
+        /**
+         * @ticket 22212
+         */
+        public function test_role__in_role__not_in_combined() {
+                $subscribers = $this->factory->user->create_many( 2, array(
+                        'role' => 'subscriber',
+                ) );
+
+                $this->factory->user->create_many( 3, array(
+                        'role' => 'editor',
+                ) );
+
+                foreach ( $subscribers as $subscriber ) {
+                        $subscriber = get_user_by( 'ID', $subscriber );
+                        $subscriber->add_role( 'editor' );
+                }
+
+                $users = get_users( array(
+                        'role__in'     => 'editor',
+                ) );
+
+                $this->assertEquals( 5, count( $users ) );
+
+                $users = get_users( array(
+                        'role__in'     => 'editor',
+                        'role__not_in' => 'subscriber',
+                ) );
+
+                $this->assertEquals( 3, count( $users ) );
+        }
+
+        /**
+         * @ticket 22212
+         */
+        public function test_role__not_in_role_combined() {
+                $subscribers = $this->factory->user->create_many( 2, array(
+                        'role' => 'subscriber',
+                ) );
+
+                $this->factory->user->create_many( 3, array(
+                        'role' => 'editor',
+                ) );
+
+                $subscriber = get_user_by( 'ID', $subscribers[0] );
+                $subscriber->add_role( 'editor' );
+
+                $users = get_users( array(
+                        'role'         => 'subscriber',
+                        'role__not_in' => array( 'editor' ),
+                ) );
+
+                $this->assertEquals( 1, count( $users ) );
+        }
+
+        /**
+         * @ticket 22212
+         */
+        public function test_role__not_in_user_without_role() {
+                $user_without_rule = $this->factory->user->get_object_by_id( $this->factory->user->create( array(
+                        'role' => 'subscriber',
+                ) ) );
+
+                $user_without_rule->remove_role( 'subscriber' );
+
+                $this->factory->user->create_many( 3, array(
+                        'role' => 'editor',
+                ) );
+
+                $users = get_users( array(
+                        'role__not_in' => 'subscriber',
+                ) );
+
+                // +1 for the default user created during installation.
+                $this->assertEquals( 5, count( $users ) );
+
+                $users = get_users( array(
+                        'role__not_in' => 'editor',
+                ) );
+
+                // +1 for the default user created during installation.
+                $this->assertEquals( 2, count( $users ) );
+        }
+
+        /**
+         * @ticket 22212
+         */
+        public function test_blog_id_should_restrict_by_blog_without_requiring_a_named_role() {
+                if ( ! is_multisite() ) {
+                        $this->markTestSkipped( __METHOD__ . ' requires multisite.' );
+                }
+
+                $sites = $this->factory->blog->create_many( 2 );
+                $users = $this->factory->user->create_many( 2 );
+
+                add_user_to_blog( $sites[0], $users[0], 'author' );
+                add_user_to_blog( $sites[1], $users[1], 'author' );
+
+                $found = get_users( array(
+                        'blog_id' => $sites[1],
+                        'fields' => 'ID',
+                ) );
+
+                $this->assertEqualSets( array( $users[1] ), $found );
+        }
 }