<?php

/**

 * User API: WP_User_Query class

 *

 * @package WordPress

 * @subpackage Users

 * @since 4.4.0

 */

/**

 * Core class used for querying users.

 *

 * @since 3.1.0

 *

 * @see WP_User_Query::prepare_query() for information on accepted arguments.

 */

#[AllowDynamicProperties]

class WP_User_Query {

	/**

	 * Query vars, after parsing

	 *

	 * @since 3.5.0

	 * @var array

	 */

	public $query_vars = array();

	/**

	 * List of found user IDs.

	 *

	 * @since 3.1.0

	 * @var array

	 */

	private $results;

	/**

	 * Total number of found users for the current query

	 *

	 * @since 3.1.0

	 * @var int

	 */

	private $total_users = 0;

	/**

	 * Metadata query container.

	 *

	 * @since 4.2.0

	 * @var WP_Meta_Query

	 */

	public $meta_query = false;

	/**

	 * The SQL query used to fetch matching users.

	 *

	 * @since 4.4.0

	 * @var string

	 */

	public $request;

	private $compat_fields = array( 'results', 'total_users' );

	// SQL clauses.

	public $query_fields;

	public $query_from;

	public $query_where;

	public $query_orderby;

	public $query_limit;

	/**

	 * Constructor.

	 *

	 * @since 3.1.0

	 *

	 * @param null|string|array $query Optional. The query variables.

	 *                                 See WP_User_Query::prepare_query() for information on accepted arguments.

	 */

	public function __construct( $query = null ) {

		if ( ! empty( $query ) ) {

			$this->prepare_query( $query );

			$this->query();

		}

	}

	/**

	 * Fills in missing query variables with default values.

	 *

	 * @since 4.4.0

	 *

	 * @param string|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(

			'blog_id'             => get_current_blog_id(),

			'role'                => '',

			'role__in'            => array(),

			'role__not_in'        => array(),

			'capability'          => '',

			'capability__in'      => array(),

			'capability__not_in'  => array(),

			'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,

			'nicename'            => '',

			'nicename__in'        => array(),

			'nicename__not_in'    => array(),

			'login'               => '',

			'login__in'           => array(),

			'login__not_in'       => array(),

			'cache_results'       => true,

		);

		return wp_parse_args( $args, $defaults );

	}

	/**

	 * Prepares the query variables.

	 *

	 * @since 3.1.0

	 * @since 4.1.0 Added the ability to order by the `include` value.

	 * @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.

	 * @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.

	 * @since 4.7.0 Added 'nicename', 'nicename__in', 'nicename__not_in', 'login', 'login__in',

	 *              and 'login__not_in' parameters.

	 * @since 5.1.0 Introduced the 'meta_compare_key' parameter.

	 * @since 5.3.0 Introduced the 'meta_type_key' parameter.

	 * @since 5.9.0 Added 'capability', 'capability__in', and 'capability__not_in' parameters.

	 *              Deprecated the 'who' parameter.

	 * @since 6.3.0 Added 'cache_results' parameter.

	 *

	 * @global wpdb     $wpdb     WordPress database abstraction object.

	 * @global WP_Roles $wp_roles WordPress role management object.

	 *

	 * @param string|array $query {

	 *     Optional. Array or string of query parameters.

	 *

	 *     @type int             $blog_id             The site ID. Default is the current site.

	 *     @type string|string[] $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 string[]        $role__in            An array of role names. Matched users must have at least one

	 *                                                of these roles. Default empty array.

	 *     @type string[]        $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.

	 *     @type string|string[] $meta_key            Meta key or keys to filter by.

	 *     @type string|string[] $meta_value          Meta value or values to filter by.

	 *     @type string          $meta_compare        MySQL operator used for comparing the meta value.

	 *                                                See WP_Meta_Query::__construct() for accepted values and default value.

	 *     @type string          $meta_compare_key    MySQL operator used for comparing the meta key.

	 *                                                See WP_Meta_Query::__construct() for accepted values and default value.

	 *     @type string          $meta_type           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.

	 *     @type string          $meta_type_key       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.

	 *     @type array           $meta_query          An associative array of WP_Meta_Query arguments.

	 *                                                See WP_Meta_Query::__construct() for accepted values.

	 *     @type string|string[] $capability          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 {@see 'map_meta_cap'}. Default empty.

	 *     @type string[]        $capability__in      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 {@see 'map_meta_cap'}. Default empty array.

	 *     @type string[]        $capability__not_in  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 {@see 'map_meta_cap'}. Default empty array.

	 *     @type int[]           $include             An array of user IDs to include. Default empty array.

	 *     @type int[]           $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 string[]        $search_columns      Array of column names to be searched. Accepts 'ID', 'user_login',

	 *                                                'user_email', 'user_url', 'user_nicename', 'display_name'.

	 *                                                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:

	 *                                                - 'ID'

	 *                                                - 'display_name' (or 'name')

	 *                                                - 'include'

	 *                                                - 'user_login' (or 'login')

	 *                                                - 'login__in'

	 *                                                - 'user_nicename' (or 'nicename')

	 *                                                - 'nicename__in'

	 *                                                - '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. Default 'user_login'.

	 *     @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

	 *                                                conjunction with pagination. Value -1 (all) is supported, but

	 *                                                should be used with caution on larger sites.

	 *                                                Default -1 (all users).

	 *     @type int             $paged               When used with number, defines the page of results to return.

	 *                                                Default 1.

	 *     @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|string[] $fields              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'.

	 *                                                Default 'all'.

	 *     @type string          $who                 Deprecated, use `$capability` instead.

	 *                                                Type of users to query. Accepts 'authors'.

	 *                                                Default empty (all users).

	 *     @type bool|string[]   $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.

	 *     @type string          $nicename            The user nicename. Default empty.

	 *     @type string[]        $nicename__in        An array of nicenames to include. Users matching one of these

	 *                                                nicenames will be included in results. Default empty array.

	 *     @type string[]        $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 string[]        $login__in           An array of logins to include. Users matching one of these

	 *                                                logins will be included in results. Default empty array.

	 *     @type string[]        $login__not_in       An array of logins to exclude. Users matching one of these

	 *                                                logins will not be included in results. Default empty array.

	 *     @type bool            $cache_results       Whether to cache user information. Default true.

	 * }

	 */

	public function prepare_query( $query = array() ) {

		global $wpdb, $wp_roles;

		if ( empty( $this->query_vars ) || ! empty( $query ) ) {

			$this->query_limit = null;

			$this->query_vars  = $this->fill_query_vars( $query );

		}

		/**

		 * 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 $query Current instance of WP_User_Query (passed by reference).

		 */

		do_action_ref_array( 'pre_get_users', array( &$this ) );

		// Ensure that query vars are filled after 'pre_get_users'.

		$qv =& $this->query_vars;

		$qv = $this->fill_query_vars( $qv );

		$allowed_fields = array(

			'id',

			'user_login',

			'user_pass',

			'user_nicename',

			'user_email',

			'user_url',

			'user_registered',

			'user_activation_key',

			'user_status',

			'display_name',

		);

		if ( is_multisite() ) {

			$allowed_fields[] = 'spam';

			$allowed_fields[] = 'deleted';

		}

		if ( is_array( $qv['fields'] ) ) {

			$qv['fields'] = array_map( 'strtolower', $qv['fields'] );

			$qv['fields'] = array_intersect( array_unique( $qv['fields'] ), $allowed_fields );

			if ( empty( $qv['fields'] ) ) {

				$qv['fields'] = array( 'id' );

			}

			$this->query_fields = array();

			foreach ( $qv['fields'] as $field ) {

				$field                = 'id' === $field ? 'ID' : sanitize_key( $field );

				$this->query_fields[] = "$wpdb->users.$field";

			}

			$this->query_fields = implode( ',', $this->query_fields );

		} elseif ( 'all_with_meta' === $qv['fields'] || 'all' === $qv['fields'] || ! in_array( $qv['fields'], $allowed_fields, true ) ) {

			$this->query_fields = "$wpdb->users.ID";

		} else {

			$field              = 'id' === strtolower( $qv['fields'] ) ? 'ID' : sanitize_key( $qv['fields'] );

			$this->query_fields = "$wpdb->users.$field";

		}

		if ( isset( $qv['count_total'] ) && $qv['count_total'] ) {

			$this->query_fields = 'SQL_CALC_FOUND_ROWS ' . $this->query_fields;

		}

		$this->query_from  = "FROM $wpdb->users";

		$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 ) {

				$post_type = $wpdb->prepare( '%s', $post_type );

			}

			$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 ( " . implode( ', ', $post_types ) . ' ) )';

		}

		// nicename

		if ( '' !== $qv['nicename'] ) {

			$this->query_where .= $wpdb->prepare( ' AND user_nicename = %s', $qv['nicename'] );

		}

		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'] ) {

			$this->query_where .= $wpdb->prepare( ' AND user_login = %s', $qv['login'] );

		}

		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' )";

		}

		// Meta query.

		$this->meta_query = new WP_Meta_Query();

		$this->meta_query->parse_query_vars( $qv );

		if ( isset( $qv['who'] ) && 'authors' === $qv['who'] && $blog_id ) {

			_deprecated_argument(

				'WP_User_Query',

				'5.9.0',

				sprintf(

					/* translators: 1: who, 2: capability */

					__( '%1$s is deprecated. Use %2$s instead.' ),

					'<code>who</code>',

					'<code>capability</code>'

				)

			);

			$who_query = array(

				'key'     => $wpdb->get_blog_prefix( $blog_id ) . 'user_level',

				'value'   => 0,

				'compare' => '!=',

			);

			// Prevent extra meta query.

			$qv['blog_id'] = 0;

			$blog_id       = 0;

			if ( empty( $this->meta_query->queries ) ) {

				$this->meta_query->queries = array( $who_query );

			} else {