2015-08-26 00:20:21 -04:00
< ? php
/**
2015-09-22 08:31:26 -04:00
* User API : WP_User_Query class
2015-08-26 00:20:21 -04:00
*
* @ package WordPress
* @ subpackage Users
2015-09-03 21:26:25 -04:00
* @ since 4.4 . 0
*/
/**
* Core class used for querying users .
*
* @ since 3.1 . 0
2015-08-26 00:20:21 -04:00
*
* @ see WP_User_Query :: prepare_query () for information on accepted arguments .
*/
class WP_User_Query {
/**
* Query vars , after parsing
*
* @ since 3.5 . 0
* @ access public
* @ var array
*/
public $query_vars = array ();
/**
* List of found user ids
*
* @ since 3.1 . 0
* @ access private
* @ var array
*/
private $results ;
/**
* Total number of found users for the current query
*
* @ since 3.1 . 0
* @ access private
* @ var int
*/
private $total_users = 0 ;
/**
* Metadata query container .
*
* @ since 4.2 . 0
* @ access public
2015-10-08 17:28:24 -04:00
* @ var WP_Meta_Query
2015-08-26 00:20:21 -04:00
*/
public $meta_query = false ;
2015-10-08 17:06:23 -04:00
/**
* The SQL query used to fetch matching users .
*
* @ since 4.4 . 0
* @ access public
* @ var string
*/
public $request ;
2015-08-26 00:20:21 -04:00
private $compat_fields = array ( 'results' , 'total_users' );
// SQL clauses
public $query_fields ;
public $query_from ;
public $query_where ;
public $query_orderby ;
public $query_limit ;
/**
* PHP5 constructor .
*
* @ since 3.1 . 0
*
2015-12-13 21:50:27 -05:00
* @ param null | string | array $query Optional . The query variables .
2015-08-26 00:20:21 -04:00
*/
public function __construct ( $query = null ) {
if ( ! empty ( $query ) ) {
$this -> prepare_query ( $query );
$this -> query ();
}
}
2015-10-03 14:45:25 -04:00
/**
* Fills in missing query variables with default values .
*
* @ since 4.4 . 0
* @ access public
*
* @ param array $args Query vars , as passed to `WP_User_Query` .
* @ return array Complete query variables with undefined ones filled in with defaults .
*/
public static function fill_query_vars ( $args ) {
$defaults = array (
2016-08-31 00:55:54 -04:00
'blog_id' => get_current_blog_id (),
2015-10-03 14:45:25 -04:00
'role' => '' ,
2015-10-08 17:28:24 -04:00
'role__in' => array (),
'role__not_in' => array (),
2015-10-03 14:45:25 -04:00
'meta_key' => '' ,
'meta_value' => '' ,
'meta_compare' => '' ,
'include' => array (),
'exclude' => array (),
'search' => '' ,
'search_columns' => array (),
'orderby' => 'login' ,
'order' => 'ASC' ,
'offset' => '' ,
'number' => '' ,
'paged' => 1 ,
'count_total' => true ,
'fields' => 'all' ,
'who' => '' ,
'has_published_posts' => null ,
2016-10-03 22:27:29 -04:00
'nicename' => '' ,
'nicename__in' => array (),
'nicename__not_in' => array (),
'login' => '' ,
'login__in' => array (),
'login__not_in' => array ()
2015-10-03 14:45:25 -04:00
);
return wp_parse_args ( $args , $defaults );
}
2015-08-26 00:20:21 -04:00
/**
* Prepare the query variables .
*
* @ since 3.1 . 0
2015-09-20 20:47:25 -04:00
* @ since 4.1 . 0 Added the ability to order by the `include` value .
2015-08-26 00:20:21 -04:00
* @ since 4.2 . 0 Added 'meta_value_num' support for `$orderby` parameter . Added multi - dimensional array syntax
* for `$orderby` parameter .
* @ since 4.3 . 0 Added 'has_published_posts' parameter .
2015-10-13 11:16:24 -04:00
* @ since 4.4 . 0 Added 'paged' , 'role__in' , and 'role__not_in' parameters . The 'role' parameter was updated to
* permit an array or comma - separated list of values . The 'number' parameter was updated to support
* querying for all users with using - 1.
2016-10-03 22:27:29 -04:00
* @ since 4.7 . 0 Added 'nicename' , 'nicename__in' , 'nicename__not_in' , 'login' , 'login__in' ,
* and 'login__not_in' parameters .
2015-10-13 11:16:24 -04:00
*
2015-08-26 00:20:21 -04:00
* @ access public
*
2016-10-10 02:38:31 -04:00
* @ global wpdb $wpdb WordPress database abstraction object .
2015-08-26 00:20:21 -04:00
* @ global int $blog_id
*
* @ param string | array $query {
* Optional . Array or string of Query parameters .
*
2016-01-27 22:51:26 -05:00
* @ type int $blog_id The site ID . Default is the current site .
2015-10-08 17:28:24 -04:00
* @ type string | array $role 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 . Default empty .
* @ type array $role__in An array of role names . Matched users must have at least one of these
* roles . Default empty array .
* @ type array $role__not_in An array of role names to exclude . Users matching one or more of these
* roles will not be included in results . Default empty array .
2015-08-26 00:20:21 -04:00
* @ type string $meta_key User meta key . Default empty .
* @ type string $meta_value User meta value . Default empty .
* @ type string $meta_compare Comparison operator to test the `$meta_value` . Accepts '=' , '!=' ,
* '>' , '>=' , '<' , '<=' , 'LIKE' , 'NOT LIKE' , 'IN' , 'NOT IN' ,
* 'BETWEEN' , 'NOT BETWEEN' , 'EXISTS' , 'NOT EXISTS' , 'REGEXP' ,
* 'NOT REGEXP' , or 'RLIKE' . Default '=' .
* @ type array $include An array of user IDs to include . Default empty array .
* @ type array $exclude An array of user IDs to exclude . Default empty array .
* @ type string $search 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 . Default empty .
* @ type array $search_columns Array of column names to be searched . Accepts 'ID' , 'login' ,
* 'nicename' , 'email' , 'url' . Default empty array .
* @ type string | array $orderby 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
2015-09-20 20:47:25 -04:00
* 'ID' , 'display_name' ( or 'name' ), 'include' , 'user_login'
2016-10-03 22:27:29 -04:00
* ( 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` , or an array key of
* `$meta_query` . To use 'meta_value' or 'meta_value_num' , `$meta_key`
* must be also be defined . Default 'user_login' .
2015-08-26 00:20:21 -04:00
* @ type string $order Designates ascending or descending order of users . Order values
* passed as part of an `$orderby` array take precedence over this
* parameter . Accepts 'ASC' , 'DESC' . Default 'ASC' .
* @ type int $offset Number of users to offset in retrieved results . Can be used in
* conjunction with pagination . Default 0.
* @ type int $number Number of users to limit the query for . Can be used in
2015-10-13 11:16:24 -04:00
* conjunction with pagination . Value - 1 ( all ) is supported , but
* should be used with caution on larger sites .
2015-08-26 00:20:21 -04:00
* Default empty ( all users ) .
2015-09-25 00:26:29 -04:00
* @ type int $paged When used with number , defines the page of results to return .
* Default 1.
2015-08-26 00:20:21 -04:00
* @ type bool $count_total Whether to count the total number of users found . If pagination
* is not needed , setting this to false can improve performance .
* Default true .
* @ type string | array $fields Which fields to return . Single or all fields ( string ), or array
2015-11-16 14:04:55 -05:00
* of fields . Accepts 'ID' , 'display_name' , 'user_login' ,
* 'user_nicename' , 'user_email' , 'user_url' , 'user_registered' .
* Use 'all' for all fields and 'all_with_meta' to include
* meta fields . Default 'all' .
2015-08-26 00:20:21 -04:00
* @ type string $who Type of users to query . Accepts 'authors' .
* Default empty ( all users ) .
* @ type bool | array $has_published_posts 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 .
2016-10-03 22:27:29 -04:00
* @ type string $nicename The user nicename . Default empty .
* @ type array $nicename__in An array of nicenames to include . Users matching one of these
* nicenames will be included in results . Default empty array .
* @ type array $nicename__not_in An array of nicenames to exclude . Users matching one of these
* nicenames will not be included in results . Default empty array .
* @ type string $login The user login . Default empty .
* @ type array $login__in An array of logins to include . Users matching one of these
* logins will be included in results . Default empty array .
* @ type array $login__not_in An array of logins to exclude . Users matching one of these
* logins will not be included in results . Default empty array .
2015-08-26 00:20:21 -04:00
* }
*/
public function prepare_query ( $query = array () ) {
2016-10-10 02:38:31 -04:00
global $wpdb ;
2015-08-26 00:20:21 -04:00
if ( empty ( $this -> query_vars ) || ! empty ( $query ) ) {
$this -> query_limit = null ;
2015-10-03 14:45:25 -04:00
$this -> query_vars = $this -> fill_query_vars ( $query );
2015-08-26 00:20:21 -04:00
}
/**
* Fires before the WP_User_Query has been parsed .
*
* The passed WP_User_Query object contains the query variables , not
* yet passed into SQL .
*
* @ since 4.0 . 0
*
* @ param WP_User_Query $this The current WP_User_Query instance ,
* passed by reference .
*/
do_action ( 'pre_get_users' , $this );
2015-10-03 14:45:25 -04:00
// Ensure that query vars are filled after 'pre_get_users'.
2015-08-26 00:20:21 -04:00
$qv =& $this -> query_vars ;
2015-10-03 14:45:25 -04:00
$qv = $this -> fill_query_vars ( $qv );
2015-08-26 00:20:21 -04:00
if ( is_array ( $qv [ 'fields' ] ) ) {
$qv [ 'fields' ] = array_unique ( $qv [ 'fields' ] );
$this -> query_fields = array ();
foreach ( $qv [ 'fields' ] as $field ) {
$field = 'ID' === $field ? 'ID' : sanitize_key ( $field );
2016-10-10 02:38:31 -04:00
$this -> query_fields [] = " $wpdb->users . $field " ;
2015-08-26 00:20:21 -04:00
}
$this -> query_fields = implode ( ',' , $this -> query_fields );
} elseif ( 'all' == $qv [ 'fields' ] ) {
2016-10-10 02:38:31 -04:00
$this -> query_fields = " $wpdb->users .* " ;
2015-08-26 00:20:21 -04:00
} else {
2016-10-10 02:38:31 -04:00
$this -> query_fields = " $wpdb->users .ID " ;
2015-08-26 00:20:21 -04:00
}
if ( isset ( $qv [ 'count_total' ] ) && $qv [ 'count_total' ] )
$this -> query_fields = 'SQL_CALC_FOUND_ROWS ' . $this -> query_fields ;
2016-10-10 02:38:31 -04:00
$this -> query_from = " FROM $wpdb->users " ;
2015-08-26 00:20:21 -04:00
$this -> query_where = " WHERE 1=1 " ;
// Parse and sanitize 'include', for use by 'orderby' as well as 'include' below.
if ( ! empty ( $qv [ 'include' ] ) ) {
$include = wp_parse_id_list ( $qv [ 'include' ] );
} else {
$include = false ;
}
$blog_id = 0 ;
if ( isset ( $qv [ 'blog_id' ] ) ) {
$blog_id = absint ( $qv [ 'blog_id' ] );
}
if ( $qv [ 'has_published_posts' ] && $blog_id ) {
if ( true === $qv [ 'has_published_posts' ] ) {
$post_types = get_post_types ( array ( 'public' => true ) );
} else {
$post_types = ( array ) $qv [ 'has_published_posts' ];
}
foreach ( $post_types as & $post_type ) {
2016-10-10 02:38:31 -04:00
$post_type = $wpdb -> prepare ( '%s' , $post_type );
2015-08-26 00:20:21 -04:00
}
2016-10-10 02:38:31 -04:00
$posts_table = $wpdb -> get_blog_prefix ( $blog_id ) . 'posts' ;
$this -> query_where .= " AND $wpdb->users .ID IN ( SELECT DISTINCT $posts_table .post_author FROM $posts_table WHERE $posts_table .post_status = 'publish' AND $posts_table .post_type IN ( " . join ( " , " , $post_types ) . " ) ) " ;
2015-08-26 00:20:21 -04:00
}
2016-10-03 22:27:29 -04:00
// nicename
if ( '' !== $qv [ 'nicename' ]) {
2016-10-10 02:38:31 -04:00
$this -> query_where .= $wpdb -> prepare ( ' AND user_nicename = %s' , $qv [ 'nicename' ] );
2016-10-03 22:27:29 -04:00
}
if ( ! empty ( $qv [ 'nicename__in' ] ) ) {
$sanitized_nicename__in = array_map ( 'esc_sql' , $qv [ 'nicename__in' ] );
$nicename__in = implode ( " ',' " , $sanitized_nicename__in );
$this -> query_where .= " AND user_nicename IN ( ' $nicename__in ' ) " ;
}
if ( ! empty ( $qv [ 'nicename__not_in' ] ) ) {
$sanitized_nicename__not_in = array_map ( 'esc_sql' , $qv [ 'nicename__not_in' ] );
$nicename__not_in = implode ( " ',' " , $sanitized_nicename__not_in );
$this -> query_where .= " AND user_nicename NOT IN ( ' $nicename__not_in ' ) " ;
}
// login
if ( '' !== $qv [ 'login' ]) {
2016-10-10 02:38:31 -04:00
$this -> query_where .= $wpdb -> prepare ( ' AND user_login = %s' , $qv [ 'login' ] );
2016-10-03 22:27:29 -04:00
}
if ( ! empty ( $qv [ 'login__in' ] ) ) {
$sanitized_login__in = array_map ( 'esc_sql' , $qv [ 'login__in' ] );
$login__in = implode ( " ',' " , $sanitized_login__in );
$this -> query_where .= " AND user_login IN ( ' $login__in ' ) " ;
}
if ( ! empty ( $qv [ 'login__not_in' ] ) ) {
$sanitized_login__not_in = array_map ( 'esc_sql' , $qv [ 'login__not_in' ] );
$login__not_in = implode ( " ',' " , $sanitized_login__not_in );
$this -> query_where .= " AND user_login NOT IN ( ' $login__not_in ' ) " ;
}
2015-08-26 00:20:21 -04:00
// Meta query.
$this -> meta_query = new WP_Meta_Query ();
$this -> meta_query -> parse_query_vars ( $qv );
2016-05-04 14:57:28 -04:00
if ( isset ( $qv [ 'who' ] ) && 'authors' == $qv [ 'who' ] && $blog_id ) {
$who_query = array (
2016-10-10 02:38:31 -04:00
'key' => $wpdb -> get_blog_prefix ( $blog_id ) . 'user_level' ,
2016-05-04 14:57:28 -04:00
'value' => 0 ,
'compare' => '!=' ,
);
// Prevent extra meta query.
$qv [ 'blog_id' ] = $blog_id = 0 ;
if ( empty ( $this -> meta_query -> queries ) ) {
$this -> meta_query -> queries = array ( $who_query );
} else {
// Append the cap query to the original queries and reparse the query.
$this -> meta_query -> queries = array (
'relation' => 'AND' ,
array ( $this -> meta_query -> queries , $who_query ),
);
}
$this -> meta_query -> parse_query_vars ( $this -> meta_query -> queries );
}
2015-10-08 17:28:24 -04:00
$roles = array ();
2015-08-26 00:20:21 -04:00
if ( isset ( $qv [ 'role' ] ) ) {
2015-10-08 17:28:24 -04:00
if ( is_array ( $qv [ 'role' ] ) ) {
$roles = $qv [ 'role' ];
} elseif ( is_string ( $qv [ 'role' ] ) && ! empty ( $qv [ 'role' ] ) ) {
$roles = array_map ( 'trim' , explode ( ',' , $qv [ 'role' ] ) );
}
}
$role__in = array ();
if ( isset ( $qv [ 'role__in' ] ) ) {
$role__in = ( array ) $qv [ 'role__in' ];
}
$role__not_in = array ();
if ( isset ( $qv [ 'role__not_in' ] ) ) {
$role__not_in = ( array ) $qv [ 'role__not_in' ];
2015-08-26 00:20:21 -04:00
}
2015-10-08 17:28:24 -04:00
if ( $blog_id && ( ! empty ( $roles ) || ! empty ( $role__in ) || ! empty ( $role__not_in ) || is_multisite () ) ) {
$role_queries = array ();
$roles_clauses = array ( 'relation' => 'AND' );
if ( ! empty ( $roles ) ) {
foreach ( $roles as $role ) {
$roles_clauses [] = array (
2016-10-10 02:38:31 -04:00
'key' => $wpdb -> get_blog_prefix ( $blog_id ) . 'capabilities' ,
2015-10-12 21:32:25 -04:00
'value' => '"' . $role . '"' ,
2015-10-08 17:28:24 -04:00
'compare' => 'LIKE' ,
);
}
$role_queries [] = $roles_clauses ;
}
2015-08-26 00:20:21 -04:00
2015-10-08 17:28:24 -04:00
$role__in_clauses = array ( 'relation' => 'OR' );
if ( ! empty ( $role__in ) ) {
foreach ( $role__in as $role ) {
$role__in_clauses [] = array (
2016-10-10 02:38:31 -04:00
'key' => $wpdb -> get_blog_prefix ( $blog_id ) . 'capabilities' ,
2015-10-12 21:32:25 -04:00
'value' => '"' . $role . '"' ,
2015-10-08 17:28:24 -04:00
'compare' => 'LIKE' ,
);
}
$role_queries [] = $role__in_clauses ;
2015-08-26 00:20:21 -04:00
}
2015-10-08 17:28:24 -04:00
$role__not_in_clauses = array ( 'relation' => 'AND' );
if ( ! empty ( $role__not_in ) ) {
foreach ( $role__not_in as $role ) {
$role__not_in_clauses [] = array (
2016-10-10 02:38:31 -04:00
'key' => $wpdb -> get_blog_prefix ( $blog_id ) . 'capabilities' ,
2015-10-12 21:32:25 -04:00
'value' => '"' . $role . '"' ,
2015-10-08 17:28:24 -04:00
'compare' => 'NOT LIKE' ,
);
}
$role_queries [] = $role__not_in_clauses ;
}
// If there are no specific roles named, make sure the user is a member of the site.
if ( empty ( $role_queries ) ) {
$role_queries [] = array (
2016-10-10 02:38:31 -04:00
'key' => $wpdb -> get_blog_prefix ( $blog_id ) . 'capabilities' ,
2015-10-08 17:28:24 -04:00
'compare' => 'EXISTS' ,
);
}
// Specify that role queries should be joined with AND.
$role_queries [ 'relation' ] = 'AND' ;
2015-08-26 00:20:21 -04:00
if ( empty ( $this -> meta_query -> queries ) ) {
2015-10-08 17:28:24 -04:00
$this -> meta_query -> queries = $role_queries ;
} else {
2015-08-26 00:20:21 -04:00
// Append the cap query to the original queries and reparse the query.
$this -> meta_query -> queries = array (
'relation' => 'AND' ,
2015-10-08 17:28:24 -04:00
array ( $this -> meta_query -> queries , $role_queries ),
2015-08-26 00:20:21 -04:00
);
}
$this -> meta_query -> parse_query_vars ( $this -> meta_query -> queries );
}
if ( ! empty ( $this -> meta_query -> queries ) ) {
2016-10-10 02:38:31 -04:00
$clauses = $this -> meta_query -> get_sql ( 'user' , $wpdb -> users , 'ID' , $this );
2015-08-26 00:20:21 -04:00
$this -> query_from .= $clauses [ 'join' ];
$this -> query_where .= $clauses [ 'where' ];
if ( $this -> meta_query -> has_or_relation () ) {
$this -> query_fields = 'DISTINCT ' . $this -> query_fields ;
}
}
// sorting
$qv [ 'order' ] = isset ( $qv [ 'order' ] ) ? strtoupper ( $qv [ 'order' ] ) : '' ;
$order = $this -> parse_order ( $qv [ 'order' ] );
if ( empty ( $qv [ 'orderby' ] ) ) {
// Default order is by 'user_login'.
$ordersby = array ( 'user_login' => $order );
} elseif ( is_array ( $qv [ 'orderby' ] ) ) {
$ordersby = $qv [ 'orderby' ];
} else {
// 'orderby' values may be a comma- or space-separated list.
$ordersby = preg_split ( '/[,\s]+/' , $qv [ 'orderby' ] );
}
$orderby_array = array ();
foreach ( $ordersby as $_key => $_value ) {
if ( ! $_value ) {
continue ;
}
if ( is_int ( $_key ) ) {
// Integer key means this is a flat array of 'orderby' fields.
$_orderby = $_value ;
$_order = $order ;
} else {
// Non-integer key means this the key is the field and the value is ASC/DESC.
$_orderby = $_key ;
$_order = $_value ;
}
$parsed = $this -> parse_orderby ( $_orderby );
if ( ! $parsed ) {
continue ;
}
2016-10-03 22:27:29 -04:00
if ( 'nicename__in' === $_orderby || 'login__in' === $_orderby ) {
$orderby_array [] = $parsed ;
} else {
$orderby_array [] = $parsed . ' ' . $this -> parse_order ( $_order );
}
2015-08-26 00:20:21 -04:00
}
// If no valid clauses were found, order by user_login.
if ( empty ( $orderby_array ) ) {
$orderby_array [] = " user_login $order " ;
}
$this -> query_orderby = 'ORDER BY ' . implode ( ', ' , $orderby_array );
// limit
2015-10-13 11:45:25 -04:00
if ( isset ( $qv [ 'number' ] ) && $qv [ 'number' ] > 0 ) {
2015-09-25 00:26:29 -04:00
if ( $qv [ 'offset' ] ) {
2016-10-10 02:38:31 -04:00
$this -> query_limit = $wpdb -> prepare ( " LIMIT %d, %d " , $qv [ 'offset' ], $qv [ 'number' ]);
2015-09-25 00:26:29 -04:00
} else {
2016-10-10 02:38:31 -04:00
$this -> query_limit = $wpdb -> prepare ( " LIMIT %d, %d " , $qv [ 'number' ] * ( $qv [ 'paged' ] - 1 ), $qv [ 'number' ] );
2015-09-25 00:26:29 -04:00
}
2015-08-26 00:20:21 -04:00
}
$search = '' ;
if ( isset ( $qv [ 'search' ] ) )
$search = trim ( $qv [ 'search' ] );
if ( $search ) {
$leading_wild = ( ltrim ( $search , '*' ) != $search );
$trailing_wild = ( rtrim ( $search , '*' ) != $search );
if ( $leading_wild && $trailing_wild )
$wild = 'both' ;
elseif ( $leading_wild )
$wild = 'leading' ;
elseif ( $trailing_wild )
$wild = 'trailing' ;
else
$wild = false ;
if ( $wild )
$search = trim ( $search , '*' );
$search_columns = array ();
2017-07-01 10:22:41 -04:00
if ( $qv [ 'search_columns' ] ) {
$search_columns = array_intersect ( $qv [ 'search_columns' ], array ( 'ID' , 'user_login' , 'user_email' , 'user_url' , 'user_nicename' , 'display_name' ) );
}
2015-08-26 00:20:21 -04:00
if ( ! $search_columns ) {
if ( false !== strpos ( $search , '@' ) )
$search_columns = array ( 'user_email' );
elseif ( is_numeric ( $search ) )
$search_columns = array ( 'user_login' , 'ID' );
elseif ( preg_match ( '|^https?://|' , $search ) && ! ( is_multisite () && wp_is_large_network ( 'users' ) ) )
$search_columns = array ( 'user_url' );
else
$search_columns = array ( 'user_login' , 'user_url' , 'user_email' , 'user_nicename' , 'display_name' );
}
/**
2016-05-22 14:15:28 -04:00
* Filters the columns to search in a WP_User_Query search .
2015-08-26 00:20:21 -04:00
*
* The default columns depend on the search term , and include 'user_email' ,
* 'user_login' , 'ID' , 'user_url' , 'display_name' , and 'user_nicename' .
*
* @ since 3.6 . 0
*
* @ param array $search_columns Array of column names to be searched .
* @ param string $search Text being searched .
* @ param WP_User_Query $this The current WP_User_Query instance .
*/
$search_columns = apply_filters ( 'user_search_columns' , $search_columns , $search , $this );
$this -> query_where .= $this -> get_search_sql ( $search , $search_columns , $wild );
}
if ( ! empty ( $include ) ) {
// Sanitized earlier.
$ids = implode ( ',' , $include );
2016-10-10 02:38:31 -04:00
$this -> query_where .= " AND $wpdb->users .ID IN ( $ids ) " ;
2015-08-26 00:20:21 -04:00
} elseif ( ! empty ( $qv [ 'exclude' ] ) ) {
$ids = implode ( ',' , wp_parse_id_list ( $qv [ 'exclude' ] ) );
2016-10-10 02:38:31 -04:00
$this -> query_where .= " AND $wpdb->users .ID NOT IN ( $ids ) " ;
2015-08-26 00:20:21 -04:00
}
// Date queries are allowed for the user_registered field.
if ( ! empty ( $qv [ 'date_query' ] ) && is_array ( $qv [ 'date_query' ] ) ) {
$date_query = new WP_Date_Query ( $qv [ 'date_query' ], 'user_registered' );
$this -> query_where .= $date_query -> get_sql ();
}
/**
* Fires after the WP_User_Query has been parsed , and before
* the query is executed .
*
* The passed WP_User_Query object contains SQL parts formed
* from parsing the given query .
*
* @ since 3.1 . 0
*
* @ param WP_User_Query $this The current WP_User_Query instance ,
* passed by reference .
*/
do_action_ref_array ( 'pre_user_query' , array ( & $this ) );
}
/**
* Execute the query , with the current variables .
*
* @ since 3.1 . 0
2016-10-10 02:38:31 -04:00
*
* @ global wpdb $wpdb WordPress database abstraction object .
2015-08-26 00:20:21 -04:00
*/
public function query () {
2016-10-10 02:38:31 -04:00
global $wpdb ;
2015-08-26 00:20:21 -04:00
$qv =& $this -> query_vars ;
2015-10-08 17:06:23 -04:00
$this -> request = " SELECT $this->query_fields $this->query_from $this->query_where $this->query_orderby $this->query_limit " ;
2015-08-26 00:20:21 -04:00
if ( is_array ( $qv [ 'fields' ] ) || 'all' == $qv [ 'fields' ] ) {
2016-10-10 02:38:31 -04:00
$this -> results = $wpdb -> get_results ( $this -> request );
2015-08-26 00:20:21 -04:00
} else {
2016-10-10 02:38:31 -04:00
$this -> results = $wpdb -> get_col ( $this -> request );
2015-08-26 00:20:21 -04:00
}
/**
2016-05-22 14:15:28 -04:00
* Filters SELECT FOUND_ROWS () query for the current WP_User_Query instance .
2015-08-26 00:20:21 -04:00
*
* @ since 3.2 . 0
*
2016-10-10 02:38:31 -04:00
* @ global wpdb $wpdb WordPress database abstraction object .
*
2015-08-26 00:20:21 -04:00
* @ param string $sql The SELECT FOUND_ROWS () query for the current WP_User_Query .
*/
2016-10-10 02:38:31 -04:00
if ( isset ( $qv [ 'count_total' ] ) && $qv [ 'count_total' ] )
2017-01-16 18:24:45 -05:00
$this -> total_users = ( int ) $wpdb -> get_var ( apply_filters ( 'found_users_query' , 'SELECT FOUND_ROWS()' ) );
2015-08-26 00:20:21 -04:00
2016-10-10 02:38:31 -04:00
if ( ! $this -> results )
2015-08-26 00:20:21 -04:00
return ;
if ( 'all_with_meta' == $qv [ 'fields' ] ) {
cache_users ( $this -> results );
$r = array ();
foreach ( $this -> results as $userid )
$r [ $userid ] = new WP_User ( $userid , '' , $qv [ 'blog_id' ] );
$this -> results = $r ;
} elseif ( 'all' == $qv [ 'fields' ] ) {
foreach ( $this -> results as $key => $user ) {
$this -> results [ $key ] = new WP_User ( $user , '' , $qv [ 'blog_id' ] );
}
}
}
/**
* Retrieve query variable .
*
* @ since 3.5 . 0
* @ access public
*
* @ param string $query_var Query variable key .
* @ return mixed
*/
public function get ( $query_var ) {
if ( isset ( $this -> query_vars [ $query_var ] ) )
return $this -> query_vars [ $query_var ];
return null ;
}
/**
* Set query variable .
*
* @ since 3.5 . 0
* @ access public
*
* @ param string $query_var Query variable key .
* @ param mixed $value Query variable value .
*/
public function set ( $query_var , $value ) {
$this -> query_vars [ $query_var ] = $value ;
}
/**
* Used internally to generate an SQL string for searching across multiple columns
*
* @ access protected
* @ since 3.1 . 0
*
2016-10-10 02:38:31 -04:00
* @ global wpdb $wpdb WordPress database abstraction object .
*
2015-08-26 00:20:21 -04:00
* @ param string $string
* @ param array $cols
* @ param bool $wild Whether to allow wildcard searches . Default is false for Network Admin , true for single site .
* Single site allows leading and trailing wildcards , Network Admin only trailing .
* @ return string
*/
protected function get_search_sql ( $string , $cols , $wild = false ) {
2016-10-10 02:38:31 -04:00
global $wpdb ;
2015-08-26 00:20:21 -04:00
$searches = array ();
$leading_wild = ( 'leading' == $wild || 'both' == $wild ) ? '%' : '' ;
$trailing_wild = ( 'trailing' == $wild || 'both' == $wild ) ? '%' : '' ;
2016-10-10 02:38:31 -04:00
$like = $leading_wild . $wpdb -> esc_like ( $string ) . $trailing_wild ;
2015-08-26 00:20:21 -04:00
foreach ( $cols as $col ) {
if ( 'ID' == $col ) {
2016-10-10 02:38:31 -04:00
$searches [] = $wpdb -> prepare ( " $col = %s " , $string );
2015-08-26 00:20:21 -04:00
} else {
2016-10-10 02:38:31 -04:00
$searches [] = $wpdb -> prepare ( " $col LIKE %s " , $like );
2015-08-26 00:20:21 -04:00
}
}
return ' AND (' . implode ( ' OR ' , $searches ) . ')' ;
}
/**
* Return the list of users .
*
* @ since 3.1 . 0
* @ access public
*
* @ return array Array of results .
*/
public function get_results () {
return $this -> results ;
}
/**
* Return the total number of users for the current query .
*
* @ since 3.1 . 0
* @ access public
*
* @ return int Number of total users .
*/
public function get_total () {
return $this -> total_users ;
}
/**
* Parse and sanitize 'orderby' keys passed to the user query .
*
* @ since 4.2 . 0
* @ access protected
*
2016-10-10 02:38:31 -04:00
* @ global wpdb $wpdb WordPress database abstraction object .
*
2015-08-26 00:20:21 -04:00
* @ param string $orderby Alias for the field to order by .
* @ return string Value to used in the ORDER clause , if `$orderby` is valid .
*/
protected function parse_orderby ( $orderby ) {
2016-10-10 02:38:31 -04:00
global $wpdb ;
2015-08-26 00:20:21 -04:00
$meta_query_clauses = $this -> meta_query -> get_clauses ();
$_orderby = '' ;
if ( in_array ( $orderby , array ( 'login' , 'nicename' , 'email' , 'url' , 'registered' ) ) ) {
$_orderby = 'user_' . $orderby ;
} elseif ( in_array ( $orderby , array ( 'user_login' , 'user_nicename' , 'user_email' , 'user_url' , 'user_registered' ) ) ) {
$_orderby = $orderby ;
} elseif ( 'name' == $orderby || 'display_name' == $orderby ) {
$_orderby = 'display_name' ;
} elseif ( 'post_count' == $orderby ) {
// todo: avoid the JOIN
$where = get_posts_by_author_sql ( 'post' );
$this -> query_from .= " LEFT OUTER JOIN (
SELECT post_author , COUNT ( * ) as post_count
2016-10-10 02:38:31 -04:00
FROM $wpdb -> posts
2015-08-26 00:20:21 -04:00
$where
GROUP BY post_author
2016-10-10 02:38:31 -04:00
) p ON ({ $wpdb -> users } . ID = p . post_author )
2015-08-26 00:20:21 -04:00
" ;
$_orderby = 'post_count' ;
} elseif ( 'ID' == $orderby || 'id' == $orderby ) {
$_orderby = 'ID' ;
} elseif ( 'meta_value' == $orderby || $this -> get ( 'meta_key' ) == $orderby ) {
2016-10-10 02:38:31 -04:00
$_orderby = " $wpdb->usermeta .meta_value " ;
2015-08-26 00:20:21 -04:00
} elseif ( 'meta_value_num' == $orderby ) {
2016-10-10 02:38:31 -04:00
$_orderby = " $wpdb->usermeta .meta_value+0 " ;
2015-08-26 00:20:21 -04:00
} elseif ( 'include' === $orderby && ! empty ( $this -> query_vars [ 'include' ] ) ) {
$include = wp_parse_id_list ( $this -> query_vars [ 'include' ] );
$include_sql = implode ( ',' , $include );
2016-10-10 02:38:31 -04:00
$_orderby = " FIELD( $wpdb->users .ID, $include_sql ) " ;
2016-10-03 22:27:29 -04:00
} elseif ( 'nicename__in' === $orderby ) {
$sanitized_nicename__in = array_map ( 'esc_sql' , $this -> query_vars [ 'nicename__in' ] );
$nicename__in = implode ( " ',' " , $sanitized_nicename__in );
$_orderby = " FIELD( user_nicename, ' $nicename__in ' ) " ;
} elseif ( 'login__in' === $orderby ) {
$sanitized_login__in = array_map ( 'esc_sql' , $this -> query_vars [ 'login__in' ] );
$login__in = implode ( " ',' " , $sanitized_login__in );
$_orderby = " FIELD( user_login, ' $login__in ' ) " ;
2015-08-26 00:20:21 -04:00
} elseif ( isset ( $meta_query_clauses [ $orderby ] ) ) {
$meta_clause = $meta_query_clauses [ $orderby ];
$_orderby = sprintf ( " CAST(%s.meta_value AS %s) " , esc_sql ( $meta_clause [ 'alias' ] ), esc_sql ( $meta_clause [ 'cast' ] ) );
}
return $_orderby ;
}
/**
* Parse an 'order' query variable and cast it to ASC or DESC as necessary .
*
* @ since 4.2 . 0
* @ access protected
*
* @ param string $order The 'order' query variable .
* @ return string The sanitized 'order' query variable .
*/
protected function parse_order ( $order ) {
if ( ! is_string ( $order ) || empty ( $order ) ) {
return 'DESC' ;
}
if ( 'ASC' === strtoupper ( $order ) ) {
return 'ASC' ;
} else {
return 'DESC' ;
}
}
/**
2016-05-13 14:41:31 -04:00
* Make private properties readable for backward compatibility .
2015-08-26 00:20:21 -04:00
*
* @ since 4.0 . 0
* @ access public
*
* @ param string $name Property to get .
* @ return mixed Property .
*/
public function __get ( $name ) {
if ( in_array ( $name , $this -> compat_fields ) ) {
return $this -> $name ;
}
}
/**
2016-05-13 14:41:31 -04:00
* Make private properties settable for backward compatibility .
2015-08-26 00:20:21 -04:00
*
* @ since 4.0 . 0
* @ access public
*
* @ param string $name Property to check if set .
* @ param mixed $value Property value .
* @ return mixed Newly - set property .
*/
public function __set ( $name , $value ) {
if ( in_array ( $name , $this -> compat_fields ) ) {
return $this -> $name = $value ;
}
}
/**
2016-05-13 14:41:31 -04:00
* Make private properties checkable for backward compatibility .
2015-08-26 00:20:21 -04:00
*
* @ since 4.0 . 0
* @ access public
*
* @ param string $name Property to check if set .
* @ return bool Whether the property is set .
*/
public function __isset ( $name ) {
if ( in_array ( $name , $this -> compat_fields ) ) {
return isset ( $this -> $name );
}
}
/**
2016-05-13 14:41:31 -04:00
* Make private properties un - settable for backward compatibility .
2015-08-26 00:20:21 -04:00
*
* @ since 4.0 . 0
* @ access public
*
* @ param string $name Property to unset .
*/
public function __unset ( $name ) {
if ( in_array ( $name , $this -> compat_fields ) ) {
unset ( $this -> $name );
}
}
/**
2016-05-13 14:41:31 -04:00
* Make private / protected methods readable for backward compatibility .
2015-08-26 00:20:21 -04:00
*
* @ since 4.0 . 0
* @ access public
*
* @ param callable $name Method to call .
* @ param array $arguments Arguments to pass when calling .
* @ return mixed Return value of the callback , false otherwise .
*/
public function __call ( $name , $arguments ) {
if ( 'get_search_sql' === $name ) {
return call_user_func_array ( array ( $this , $name ), $arguments );
}
return false ;
}
}