From 9b0c0c72010110d607168b7dc056822e7042924b Mon Sep 17 00:00:00 2001
From: Adam Silverstein <adamsilverstein@earthboundhosting.com>
Date: Sat, 29 Dec 2018 16:06:50 +0000
Subject: [PATCH] Users: Add a `users_pre_query` filter to short circuit
 WP_User_Query results.

Add a new filter `users_pre_query` - filters the users array before the query takes place. Return a non-null value to bypass WordPress's default user queries. Similar to the `posts_pre_query` filter for WP_Query added in #36687. This filter lets you short circuit the WP_User_Query MySQL query to return your own results.

Developers should note that filtering functions that require pagination information are encouraged to set the `total_users` property of the WP_User_Query object, passed to the filter by reference. If WP_User_Query does not perform a database query, it will not have enough information to generate these values itself.

Props tlovett1, birgire, boonebgorges, spacedmonkey.
Fixes #44169.

Built from https://develop.svn.wordpress.org/trunk@44373


git-svn-id: http://core.svn.wordpress.org/trunk@44203 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/class-wp-user-query.php | 58 +++++++++++++++++++----------
 wp-includes/version.php             |  2 +-
 2 files changed, 39 insertions(+), 21 deletions(-)

diff --git a/wp-includes/class-wp-user-query.php b/wp-includes/class-wp-user-query.php
index c75f392c24..23f108dbd3 100644
--- a/wp-includes/class-wp-user-query.php
+++ b/wp-includes/class-wp-user-query.php
@@ -592,29 +592,47 @@ class WP_User_Query {
 
 		$qv =& $this->query_vars;
 
-		$this->request = "SELECT $this->query_fields $this->query_from $this->query_where $this->query_orderby $this->query_limit";
+		/**
+		 * Filters the users array before the query takes place.
+		 *
+		 * Return a non-null value to bypass WordPress's default user queries.
+		 * Filtering functions that require pagination information are encouraged to set
+		 * the `total_users` property of the WP_User_Query object, passed to the filter
+		 * by reference. If WP_User_Query does not perform a database query, it will not
+		 * have enough information to generate these values itself.
+		 *
+		 * @since 5.0.3
+		 *
+		 * @param array|null $results Return an array of user data to short-circuit WP's user query or null to allow WP to run its normal queries.
+		 * @param WP_User_Query $this The WP_User_Query instance (passed by reference).
+		 */
+		$this->results = apply_filters_ref_array( 'users_pre_query', array( null, &$this ) );
 
-		if ( is_array( $qv['fields'] ) || 'all' == $qv['fields'] ) {
-			$this->results = $wpdb->get_results( $this->request );
-		} else {
-			$this->results = $wpdb->get_col( $this->request );
-		}
+		if ( null === $this->results ) {
+			$this->request = "SELECT $this->query_fields $this->query_from $this->query_where $this->query_orderby $this->query_limit";
 
-		if ( isset( $qv['count_total'] ) && $qv['count_total'] ) {
-			/**
-			 * Filters SELECT FOUND_ROWS() query for the current WP_User_Query instance.
-			 *
-			 * @since 3.2.0
-			 * @since 5.1.0 Added the `$this` parameter.
-			 *
-			 * @global wpdb $wpdb WordPress database abstraction object.
-			 *
-			 * @param string $sql         The SELECT FOUND_ROWS() query for the current WP_User_Query.
-			 * @param WP_User_Query $this The current WP_User_Query instance.
-			 */
-			$found_users_query = apply_filters( 'found_users_query', 'SELECT FOUND_ROWS()', $this );
+			if ( is_array( $qv['fields'] ) || 'all' == $qv['fields'] ) {
+				$this->results = $wpdb->get_results( $this->request );
+			} else {
+				$this->results = $wpdb->get_col( $this->request );
+			}
 
-			$this->total_users = (int) $wpdb->get_var( $found_users_query );
+			if ( isset( $qv['count_total'] ) && $qv['count_total'] ) {
+				/**
+				 * Filters SELECT FOUND_ROWS() query for the current WP_User_Query instance.
+				 *
+				 * @since 3.2.0
+				 * @since 5.0.3 Added the `$this` parameter.
+				 *
+				 * @global wpdb $wpdb WordPress database abstraction object.
+				 *
+				 * @param string $sql         The SELECT FOUND_ROWS() query for the current WP_User_Query.
+				 * @param WP_User_Query $this The current WP_User_Query instance.
+				 */
+				$found_users_query = apply_filters( 'found_users_query', 'SELECT FOUND_ROWS()', $this );
+
+				$this->total_users = (int) $wpdb->get_var( $found_users_query );
+			}
 		}
 
 		if ( ! $this->results ) {
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 65a596acef..228b0aceef 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.1-alpha-44372';
+$wp_version = '5.1-alpha-44373';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.