WP_User_Query::query() │ public │ WP 3.1.0

Executes the query, with the current variables.

Method of the class: WP_User_Query{}

Return

null. Nothing (null).

Usage

$WP_User_Query = new WP_User_Query();
$WP_User_Query->query();

Notes

• Global. wpdb. $wpdb WordPress database abstraction object.

Changelog

WP_User_Query::query() WP User Query::query code ^{WP 6.7.2}

public function query() {
	global $wpdb;

	if ( ! did_action( 'plugins_loaded' ) ) {
		_doing_it_wrong(
			'WP_User_Query::query',
			sprintf(
			/* translators: %s: plugins_loaded */
				__( 'User queries should not be run before the %s hook.' ),
				'<code>plugins_loaded</code>'
			),
			'6.1.1'
		);
	}

	$qv =& $this->query_vars;

	// Do not cache results if more than 3 fields are requested.
	if ( is_array( $qv['fields'] ) && count( $qv['fields'] ) > 3 ) {
		$qv['cache_results'] = false;
	}

	/**
	 * Filters the users array before the query takes place.
	 *
	 * Return a non-null value to bypass WordPress' 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.1.0
	 *
	 * @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 $query   The WP_User_Query instance (passed by reference).
	 */
	$this->results = apply_filters_ref_array( 'users_pre_query', array( null, &$this ) );

	if ( null === $this->results ) {
		// Beginning of the string is on a new line to prevent leading whitespace. See https://core.trac.wordpress.org/ticket/56841.
		$this->request =
			"SELECT {$this->query_fields}
			 {$this->query_from}
			 {$this->query_where}
			 {$this->query_orderby}
			 {$this->query_limit}";
		$cache_value   = false;
		$cache_key     = $this->generate_cache_key( $qv, $this->request );
		$cache_group   = 'user-queries';
		if ( $qv['cache_results'] ) {
			$cache_value = wp_cache_get( $cache_key, $cache_group );
		}
		if ( false !== $cache_value ) {
			$this->results     = $cache_value['user_data'];
			$this->total_users = $cache_value['total_users'];
		} else {

			if ( is_array( $qv['fields'] ) ) {
				$this->results = $wpdb->get_results( $this->request );
			} else {
				$this->results = $wpdb->get_col( $this->request );
			}

			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 $query 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 ( $qv['cache_results'] ) {
				$cache_value = array(
					'user_data'   => $this->results,
					'total_users' => $this->total_users,
				);
				wp_cache_add( $cache_key, $cache_value, $cache_group );
			}
		}
	}

	if ( ! $this->results ) {
		return;
	}
	if (
		is_array( $qv['fields'] ) &&
		isset( $this->results[0]->ID )
	) {
		foreach ( $this->results as $result ) {
			$result->id = $result->ID;
		}
	} elseif ( 'all_with_meta' === $qv['fields'] || 'all' === $qv['fields'] ) {
		if ( function_exists( 'cache_users' ) ) {
			cache_users( $this->results );
		}

		$r = array();
		foreach ( $this->results as $userid ) {
			if ( 'all_with_meta' === $qv['fields'] ) {
				$r[ $userid ] = new WP_User( $userid, '', $qv['blog_id'] );
			} else {
				$r[] = new WP_User( $userid, '', $qv['blog_id'] );
			}
		}

		$this->results = $r;
	}
}