WP_User_Query::prepare_query( string|array $query = array() )

Compatibility

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

Parameters

$querystring|arrayoptional

Array or string of query parameters.Default: array()

• $blog_idintdefault: is the current site

  The site ID.

• $rolestring|string[]default: empty

  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.

• $role__instring[]default: empty array

  An array of role names. Matched users must have at least one of these roles.

• $role__not_instring[]default: empty array

  An array of role names to exclude. Users matching one or more of these roles will not be included in results.

• $meta_keystring|string[]

  Meta key or keys to filter by.

• $meta_valuestring|string[]

  Meta value or values to filter by.

• $meta_comparestring

  MySQL operator used for comparing the meta value. See WP_Meta_Query::construct() for accepted values and default value.

• $meta_compare_keystring

  MySQL operator used for comparing the meta key. See WP_Meta_Query::</strong>construct() for accepted values and default value.

• $meta_typestring

  MySQL data type that the meta_value column will be CAST to for comparisons. See WP_Meta_Query::construct() for accepted values and default value.

• $meta_type_keystring

  MySQL data type that the meta_key column will be CAST to for comparisons. See WP_Meta_Query::__construct() for accepted values and default value.

• $meta_queryarray

  An associative array of WP_Meta_Query arguments. See WP_Meta_Query::</strong>construct() for accepted values.

• $capabilitystring|string[]default: empty

  An array or a comma-separated list of capability names that users must match to be included in results. Note that this is an inclusive list: users must match each capability. Does NOT work for capabilities not in the database or filtered via 'map_meta_cap'.

• $capability__instring[]default: empty array

  An array of capability names. Matched users must have at least one of these capabilities. Does NOT work for capabilities not in the database or filtered via 'map_meta_cap'.

• $capability__not_instring[]default: empty array

  An array of capability names to exclude. Users matching one or more of these capabilities will not be included in results. Does NOT work for capabilities not in the database or filtered via 'map_meta_cap'.

• $includeint[]default: empty array

  An array of user IDs to include.

• $excludeint[]default: empty array

  An array of user IDs to exclude.

• $searchstringdefault: empty

  Search keyword. Searches for possible string matches on columns. When $search_columns is left empty, it tries to determine which column to search in based on search string.

• $search_columnsstring[]default: empty array

  Array of column names to be searched. Accepts 'ID', 'user_login', 'user_email', 'user_url', 'user_nicename', 'display_name'.

• $orderbystring|arraydefault: 'user_login'

  Field(s) to sort the retrieved users by. May be a single value, an array of values, or a multi-dimensional array with fields as keys and orders ('ASC' or 'DESC') as values. Accepted values are: - 'ID' - 'display_name' (or 'name') - 'include' - 'user_login' (or 'login') - 'login__in' - 'user_nicename' (or 'nicename') - 'nicename__in' - 'user_email' (or 'email') - 'user_url' (or 'url') - 'user_registered' (or 'registered') - 'post_count' - 'meta_value' - 'meta_value_num' - The value of $meta_key - An array key of $meta_query To use 'meta_value' or 'meta_value_num', $meta_key must be also be defined.

• $orderstringdefault: 'ASC'

  Designates ascending or descending order of users. Order values passed as part of an $orderby array take precedence over this parameter. Accepts 'ASC', 'DESC'.

• $offsetintdefault: 0

  Number of users to offset in retrieved results. Can be used in conjunction with pagination.

• $numberintdefault: -1 (all users)

  Number of users to limit the query for. Can be used in conjunction with pagination. Value -1 (all) is supported, but should be used with caution on larger sites.

• $pagedintdefault: 1

  When used with number, defines the page of results to return.

• $count_totalbooldefault: true

  Whether to count the total number of users found. If pagination is not needed, setting this to false can improve performance.

• $fieldsstring|string[]default: 'all'

  Which fields to return. Single or all fields (string), or array of fields. Accepts:

  • 'ID'
  • 'display_name'
  • 'user_login'
  • 'user_nicename'
  • 'user_email'
  • 'user_url'
  • 'user_registered'
  • 'user_pass'
  • 'user_activation_key'
  • 'user_status'
  • 'spam' (only available on multisite installs)
  • 'deleted' (only available on multisite installs)
  • 'all' for all fields and loads user meta
  • 'all_with_meta' Deprecated. Use 'all'

• $whostringdefault: empty (all users)

  Deprecated, use $capability instead. Type of users to query. Accepts 'authors'.

• $has_published_postsbool|string[]

  Pass an array of post types to filter results to users who have published posts in those post types. true is an alias for all public post types.

• $nicenamestringdefault: empty

  The user nicename.

• $nicename__instring[]default: empty array

  An array of nicenames to include. Users matching one of these nicenames will be included in results.

• $nicename__not_instring[]default: empty array

  An array of nicenames to exclude. Users matching one of these nicenames will not be included in results.

• $loginstringdefault: empty

  The user login.

• $login__instring[]default: empty array

  An array of logins to include. Users matching one of these logins will be included in results.

• $login__not_instring[]default: empty array

  An array of logins to exclude. Users matching one of these logins will not be included in results.

• $cache_resultsbooldefault: true

  Whether to cache user information.

Performance profile

How much work a call to WP_User_Query::prepare_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

Trivial

Touches nothing outside its own arguments.

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

184–269

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

Plugin surface

3 hooks

Third-party callbacks on 'pre_get_users', 'user_search_columns', 'pre_user_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

• hookthird-party callbacksdo_action_ref_array()called directly
• regexregular expression over the whole inputpreg_split()called directly

Further down the call graph this can also reach option, cache, serialize, query 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 · 28 distinct outcomes

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

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 3

3 hooks fire while WP_User_Query::prepare_query() runs, in this order:

1. 1
   do_action( pre_get_users )actionline 283 (+18 into the body)

   Fires before the WP_User_Query has been parsed.

2. 2
   apply_filters( user_search_columns )filterline 741 (+476 into the body)

   Filters the columns to search in a WP_User_Query search.

3. 3
   do_action( pre_user_query )actionline 772 (+507 into the body)

   Fires after the WP_User_Query has been parsed, and before the query is executed.

Uses · 17

• do_action_ref_array()Calls the callback functions that have been added to an action hook, specifying arguments in an array.
• is_multisite()Determines whether Multisite is enabled.
• sanitize_key()Sanitizes a string key.
• wp_parse_id_list()Cleans up an array, comma- or space-separated list of IDs.
• absint()Converts a value to non-negative integer.
• get_post_types()Gets a list of all registered post type objects.
• _deprecated_argument()Marks a function argument as deprecated and inform when it has been used.
• __()Retrieves the translation of $text.
• str_contains()Polyfill for `str_contains()` function added in PHP 8.0.
• wp_is_large_network()Determines whether or not we have a large network.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• WP_User_Query::fill_query_vars()Fills in missing query variables with default values.

Used by · 1

• WP_User_Query::__construct()Constructor.

Source code

View on Trac ↗View on GitHub ↗

265	public function prepare_query( $query = array() ) {266		global $wpdb, $wp_roles;267 268		if ( empty( $this->query_vars ) || ! empty( $query ) ) {269			$this->query_limit = null;270			$this->query_vars  = $this->fill_query_vars( $query );271		}272 273		/**274		 * Fires before the WP_User_Query has been parsed.275		 *276		 * The passed WP_User_Query object contains the query variables,277		 * not yet passed into SQL.278		 *279		 * @since 4.0.0280		 *281		 * @param WP_User_Query $query Current instance of WP_User_Query (passed by reference).282		 */283		do_action_ref_array( 'pre_get_users', array( &$this ) );284 285		// Ensure that query vars are filled after 'pre_get_users'.286		$qv =& $this->query_vars;287		$qv = $this->fill_query_vars( $qv );288 289		$allowed_fields = array(290			'id',291			'user_login',292			'user_pass',293			'user_nicename',294			'user_email',295			'user_url',296			'user_registered',297			'user_activation_key',298			'user_status',299			'display_name',300		);301		if ( is_multisite() ) {302			$allowed_fields[] = 'spam';303			$allowed_fields[] = 'deleted';304		}305 306		if ( is_array( $qv['fields'] ) ) {307			$qv['fields'] = array_map( 'strtolower', $qv['fields'] );308			$qv['fields'] = array_intersect( array_unique( $qv['fields'] ), $allowed_fields );309 310			if ( empty( $qv['fields'] ) ) {311				$qv['fields'] = array( 'id' );312			}313 314			$this->query_fields = array();315			foreach ( $qv['fields'] as $field ) {316				$field                = 'id' === $field ? 'ID' : sanitize_key( $field );317				$this->query_fields[] = "$wpdb->users.$field";318			}319			$this->query_fields = implode( ',', $this->query_fields );320		} elseif ( 'all_with_meta' === $qv['fields'] || 'all' === $qv['fields'] || ! in_array( $qv['fields'], $allowed_fields, true ) ) {321			$this->query_fields = "$wpdb->users.ID";322		} else {323			$field              = 'id' === strtolower( $qv['fields'] ) ? 'ID' : sanitize_key( $qv['fields'] );324			$this->query_fields = "$wpdb->users.$field";325		}326 327		if ( isset( $qv['count_total'] ) && $qv['count_total'] ) {328			$this->query_fields = 'SQL_CALC_FOUND_ROWS ' . $this->query_fields;329		}330 331		$this->query_from  = "FROM $wpdb->users";332		$this->query_where = 'WHERE 1=1';333 334		// Parse and sanitize 'include', for use by 'orderby' as well as 'include' below.335		if ( ! empty( $qv['include'] ) ) {336			$include = wp_parse_id_list( $qv['include'] );337		} else {338			$include = false;339		}340 341		$blog_id = 0;342		if ( isset( $qv['blog_id'] ) ) {343			$blog_id = absint( $qv['blog_id'] );344		}

Changelog

Introduced in 5.3.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.1.0 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.