WP_User_Query::query()

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Performance profile

How much work a call to WP_User_Query::query() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via WP_User_Query::query().

Scaling

Scales with input

The body loops, so the work grows with how much data it finds.

Instructions

25–153

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 200.

Plugin surface

2 hooks

Third-party callbacks on 'users_pre_query', 'found_users_query' run inside this call, and their cost is not bounded by anything here.

Called by

1

1 place in core call this, so the cost is paid more often than your own code shows.

What it touches

• sqldatabase queryWP_User_Query::query()this function does it
• hookthird-party callbacksapply_filters_ref_array()called directly
• cacheobject cachewp_cache_get_salted()called directly

Further down the call graph this can also reach query, option, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 114 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost WP_User_Query::query() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 2

2 hooks fire while WP_User_Query::query() runs, in this order:

1. 1
   apply_filters( users_pre_query )filterline 820 (+38 into the body)

   Filters the users array before the query takes place.

2. 2
   apply_filters( found_users_query )filterline 861 (+79 into the body)

   Filters SELECT FOUND_ROWS() query for the current WP_User_Query instance.

Uses · 11

• did_action()Retrieves the number of times an action has been fired during the current request.
• _doing_it_wrong()Marks something as being incorrectly called.
• __()Retrieves the translation of $text.
• apply_filters_ref_array()Calls the callback functions that have been added to a filter hook, specifying arguments in an array.
• wp_cache_get_salted()Retrieves cached data if valid and unchanged.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• wp_cache_set_salted()Stores salted data in the cache.
• cache_users()Retrieves info for user lists to prevent multiple queries by get_userdata().
• WP_User_Query::generate_cache_key()Generate cache key.
• WP_User_Query::get_cache_last_changed()Retrieves the last changed cache timestamp for users and optionally posts.
• WP_User::__construct()Constructor.

Used by · 1

• WP_User_Query::__construct()Constructor.

Source code

View on Trac ↗View on GitHub ↗

782	public function query() {783		global $wpdb;784 785		if ( ! did_action( 'plugins_loaded' ) ) {786			_doing_it_wrong(787				'WP_User_Query::query',788				sprintf(789				/* translators: %s: plugins_loaded */790					__( 'User queries should not be run before the %s hook.' ),791					'<code>plugins_loaded</code>'792				),793				'6.1.1'794			);795		}796 797		$qv =& $this->query_vars;798 799		// Do not cache results if more than 3 fields are requested.800		if ( is_array( $qv['fields'] ) && count( $qv['fields'] ) > 3 ) {801			$qv['cache_results'] = false;802		}803 804		/**805		 * Filters the users array before the query takes place.806		 *807		 * Return a non-null value to bypass WordPress' default user queries.808		 *809		 * Filtering functions that require pagination information are encouraged to set810		 * the `total_users` property of the WP_User_Query object, passed to the filter811		 * by reference. If WP_User_Query does not perform a database query, it will not812		 * have enough information to generate these values itself.813		 *814		 * @since 5.1.0815		 *816		 * @param array|null    $results Return an array of user data to short-circuit WP's user query817		 *                               or null to allow WP to run its normal queries.818		 * @param WP_User_Query $query   The WP_User_Query instance (passed by reference).819		 */820		$this->results = apply_filters_ref_array( 'users_pre_query', array( null, &$this ) );821 822		if ( null === $this->results ) {823			// Beginning of the string is on a new line to prevent leading whitespace. See https://core.trac.wordpress.org/ticket/56841.824			$this->request =825				"SELECT {$this->query_fields}826				 {$this->query_from}827				 {$this->query_where}828				 {$this->query_orderby}829				 {$this->query_limit}";830			$cache_value   = false;831			$cache_key     = $this->generate_cache_key( $qv, $this->request );832			$cache_group   = 'user-queries';833			$last_changed  = $this->get_cache_last_changed( $qv );834 835			if ( $qv['cache_results'] ) {836				$cache_value = wp_cache_get_salted( $cache_key, $cache_group, $last_changed );837			}838			if ( false !== $cache_value ) {839				$this->results     = $cache_value['user_data'];840				$this->total_users = $cache_value['total_users'];841			} else {842 843				if ( is_array( $qv['fields'] ) ) {844					$this->results = $wpdb->get_results( $this->request );845				} else {846					$this->results = $wpdb->get_col( $this->request );847				}848 849				if ( isset( $qv['count_total'] ) && $qv['count_total'] ) {850					/**851					 * Filters SELECT FOUND_ROWS() query for the current WP_User_Query instance.852					 *853					 * @since 3.2.0854					 * @since 5.1.0 Added the `$query` parameter.855					 *856					 * @global wpdb $wpdb WordPress database abstraction object.857					 *858					 * @param string        $sql   The SELECT FOUND_ROWS() query for the current WP_User_Query.859					 * @param WP_User_Query $query The current WP_User_Query instance.860					 */861					$found_users_query = apply_filters( 'found_users_query', 'SELECT FOUND_ROWS()', $this );

Changelog

Introduced in 3.1.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.0.4 tag, from src/wp-includes/class-wp-user-query.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.