Improve role-related arguments in `WP_User_Query`.

* 'role' now accepts an array or comma-separated list of role names. When passing multiple values for 'role', `WP_User_Query` will only match users that have all of the specified roles.
* 'role__in' accepts an array of role names, and allow the filtering of matched users to those with at least one of the specified roles.
* 'role__not_in' accepts an array of role names, and allows the filtering of matched users to those who have none of the specified roles.

Props swissspidy, mordauk, barrykooij, sirbrillig.
Fixes #22212.
Built from https://develop.svn.wordpress.org/trunk@34875


git-svn-id: http://core.svn.wordpress.org/trunk@34840 1a063a9b-81f0-0310-95a4-ce76da25c4cd

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

@@ -88,6 +88,8 @@ class WP_User_Query {
 		$defaults = array(
 			'blog_id' => $GLOBALS['blog_id'],
 			'role' => '',
+			'role__in' => array(),
+			'role__not_in' => array(),
 			'meta_key' => '',
 			'meta_value' => '',
 			'meta_compare' => '',
@@ -117,7 +119,8 @@ class WP_User_Query {
 	 * @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,7 +130,13 @@ class WP_User_Query {
 	 *     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,27 +268,76 @@ class WP_User_Query {
 		$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'] ) );
+			}
 		}
 
-		if ( $blog_id && ( $role || is_multisite() ) ) {
+		$role__in = array();
-			$cap_meta_query = array();
+		if ( isset( $qv['role__in'] ) ) {
-			$cap_meta_query['key'] = $wpdb->get_blog_prefix( $blog_id ) . 'capabilities';
+			$role__in = (array) $qv['role__in'];
+		}
 
-			if ( $role ) {
+		$role__not_in = array();
-				$cap_meta_query['value'] = '"' . $role . '"';
+		if ( isset( $qv['role__not_in'] ) ) {
-				$cap_meta_query['compare'] = 'like';
+			$role__not_in = (array) $qv['role__not_in'];
+		}
+
+		if ( $blog_id && ( ! empty( $roles ) || ! empty( $role__in ) || ! empty( $role__not_in ) || is_multisite() ) ) {
+			$role_queries  = array( 'relation' => 'AND' );
+			$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->clauses ) || ! in_array( $roles_clauses, $this->meta_query_clauses, 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',
+					);
+				}
+
+				$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',
+					);
+				}
+
+				$role_queries[] = $role__not_in_clauses;
 			}
 
 			if ( empty( $this->meta_query->queries ) ) {
-				$this->meta_query->queries = array( $cap_meta_query );
+				$this->meta_query->queries = $role_queries;
-			} elseif ( ! in_array( $cap_meta_query, $this->meta_query->queries, true ) ) {
+			} 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 ),
 				);
 			}
 

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.4-alpha-34874';
+$wp_version = '4.4-alpha-34875';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.