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

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 <em>each</em> 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::<strong>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::<strong>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 <em>each</em> 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.

Hooks 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

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		}

History

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 6.9.7 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.