Title: WP_User_Search
Published: April 25, 2014
Last modified: May 20, 2026

---

# class WP_User_Search {}

## In this article

 * [Methods](https://developer.wordpress.org/reference/classes/wp_user_search/?output_format=md#methods)
 * [Source](https://developer.wordpress.org/reference/classes/wp_user_search/?output_format=md#source)
 * [Changelog](https://developer.wordpress.org/reference/classes/wp_user_search/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/classes/wp_user_search/?output_format=md#wp--skip-link--target)

This class has been deprecated since 3.1.0. Use WP_User_Query instead.

WordPress User Search class.

## 󠀁[Methods](https://developer.wordpress.org/reference/classes/wp_user_search/?output_format=md#methods)󠁿

| Name | Description | 
| [WP_User_Search::__construct](https://developer.wordpress.org/reference/classes/wp_user_search/__construct/) | PHP5 Constructor – Sets up the object properties. | 
| [WP_User_Search::do_paging](https://developer.wordpress.org/reference/classes/wp_user_search/do_paging/) | Handles paging for the user search query. | 
| [WP_User_Search::get_results](https://developer.wordpress.org/reference/classes/wp_user_search/get_results/) | Retrieves the user search query results. | 
| [WP_User_Search::is_search](https://developer.wordpress.org/reference/classes/wp_user_search/is_search/) | Whether there are search terms. | 
| [WP_User_Search::page_links](https://developer.wordpress.org/reference/classes/wp_user_search/page_links/) | Displaying paging text. | 
| [WP_User_Search::prepare_query](https://developer.wordpress.org/reference/classes/wp_user_search/prepare_query/) | Prepares the user search query (legacy). | 
| [WP_User_Search::prepare_vars_for_template_usage](https://developer.wordpress.org/reference/classes/wp_user_search/prepare_vars_for_template_usage/) | Prepares variables for use in templates. | 
| [WP_User_Search::query](https://developer.wordpress.org/reference/classes/wp_user_search/query/) | Executes the user search query. | 
| [WP_User_Search::results_are_paged](https://developer.wordpress.org/reference/classes/wp_user_search/results_are_paged/) | Whether paging is enabled. | 
| [WP_User_Search::WP_User_Search](https://developer.wordpress.org/reference/classes/wp_user_search/wp_user_search/) | PHP4 Constructor – Sets up the object properties. |

## 󠀁[Source](https://developer.wordpress.org/reference/classes/wp_user_search/?output_format=md#source)󠁿

    ```php
    class WP_User_Search {

    	/**
    	 * 
    	 *
    	 * @since 2.1.0
    	 * @access private
    	 * @var mixed
    	 */
    	var $results;

    	/**
    	 * 
    	 *
    	 * @since 2.1.0
    	 * @access private
    	 * @var string
    	 */
    	var $search_term;

    	/**
    	 * Page number.
    	 *
    	 * @since 2.1.0
    	 * @access private
    	 * @var int
    	 */
    	var $page;

    	/**
    	 * Role name that users have.
    	 *
    	 * @since 2.5.0
    	 * @access private
    	 * @var string
    	 */
    	var $role;

    	/**
    	 * Raw page number.
    	 *
    	 * @since 2.1.0
    	 * @access private
    	 * @var int|bool
    	 */
    	var $raw_page;

    	/**
    	 * Amount of users to display per page.
    	 *
    	 * @since 2.1.0
    	 * @access public
    	 * @var int
    	 */
    	var $users_per_page = 50;

    	/**
    	 * 
    	 *
    	 * @since 2.1.0
    	 * @access private
    	 * @var int
    	 */
    	var $first_user;

    	/**
    	 * 
    	 *
    	 * @since 2.1.0
    	 * @access private
    	 * @var int
    	 */
    	var $last_user;

    	/**
    	 * 
    	 *
    	 * @since 2.1.0
    	 * @access private
    	 * @var string
    	 */
    	var $query_limit;

    	/**
    	 * 
    	 *
    	 * @since 3.0.0
    	 * @access private
    	 * @var string
    	 */
    	var $query_orderby;

    	/**
    	 * 
    	 *
    	 * @since 3.0.0
    	 * @access private
    	 * @var string
    	 */
    	var $query_from;

    	/**
    	 * 
    	 *
    	 * @since 3.0.0
    	 * @access private
    	 * @var string
    	 */
    	var $query_where;

    	/**
    	 * 
    	 *
    	 * @since 2.1.0
    	 * @access private
    	 * @var int
    	 */
    	var $total_users_for_query = 0;

    	/**
    	 * 
    	 *
    	 * @since 2.1.0
    	 * @access private
    	 * @var bool
    	 */
    	var $too_many_total_users = false;

    	/**
    	 * 
    	 *
    	 * @since 2.1.0
    	 * @access private
    	 * @var WP_Error
    	 */
    	var $search_errors;

    	/**
    	 * 
    	 *
    	 * @since 2.7.0
    	 * @access private
    	 * @var string
    	 */
    	var $paging_text;

    	/**
    	 * PHP5 Constructor - Sets up the object properties.
    	 *
    	 * @since 2.1.0
    	 *
    	 * @param string $search_term Search terms string.
    	 * @param int $page Optional. Page ID.
    	 * @param string $role Role name.
    	 * @return WP_User_Search
    	 */
    	function __construct( $search_term = '', $page = '', $role = '' ) {
    		_deprecated_class( 'WP_User_Search', '3.1.0', 'WP_User_Query' );

    		$this->search_term = wp_unslash( $search_term );
    		$this->raw_page = ( '' == $page ) ? false : (int) $page;
    		$this->page = ( '' == $page ) ? 1 : (int) $page;
    		$this->role = $role;

    		$this->prepare_query();
    		$this->query();
    		$this->do_paging();
    	}

    	/**
    	 * PHP4 Constructor - Sets up the object properties.
    	 *
    	 * @since 2.1.0
    	 *
    	 * @param string $search_term Search terms string.
    	 * @param int $page Optional. Page ID.
    	 * @param string $role Role name.
    	 * @return WP_User_Search
    	 */
    	public function WP_User_Search( $search_term = '', $page = '', $role = '' ) {
    		_deprecated_constructor( 'WP_User_Search', '3.1.0', get_class( $this ) );
    		self::__construct( $search_term, $page, $role );
    	}

    	/**
    	 * Prepares the user search query (legacy).
    	 *
    	 * @since 2.1.0
    	 * @access public
    	 *
    	 * @global wpdb $wpdb WordPress database abstraction object.
    	 */
    	public function prepare_query() {
    		global $wpdb;
    		$this->first_user = ($this->page - 1) * $this->users_per_page;

    		$this->query_limit = $wpdb->prepare(" LIMIT %d, %d", $this->first_user, $this->users_per_page);
    		$this->query_orderby = ' ORDER BY user_login';

    		$search_sql = '';
    		if ( $this->search_term ) {
    			$searches = array();
    			$search_sql = 'AND (';
    			foreach ( array('user_login', 'user_nicename', 'user_email', 'user_url', 'display_name') as $col )
    				$searches[] = $wpdb->prepare( $col . ' LIKE %s', '%' . like_escape($this->search_term) . '%' );
    			$search_sql .= implode(' OR ', $searches);
    			$search_sql .= ')';
    		}

    		$this->query_from = " FROM $wpdb->users";
    		$this->query_where = " WHERE 1=1 $search_sql";

    		if ( $this->role ) {
    			$this->query_from .= " INNER JOIN $wpdb->usermeta ON $wpdb->users.ID = $wpdb->usermeta.user_id";
    			$this->query_where .= $wpdb->prepare(" AND $wpdb->usermeta.meta_key = '{$wpdb->prefix}capabilities' AND $wpdb->usermeta.meta_value LIKE %s", '%' . $this->role . '%');
    		} elseif ( is_multisite() ) {
    			$level_key = $wpdb->prefix . 'capabilities'; // WPMU site admins don't have user_levels.
    			$this->query_from .= ", $wpdb->usermeta";
    			$this->query_where .= " AND $wpdb->users.ID = $wpdb->usermeta.user_id AND meta_key = '{$level_key}'";
    		}

    		do_action_ref_array( 'pre_user_search', array( &$this ) );
    	}

    	/**
    	 * Executes the user search query.
    	 *
    	 * @since 2.1.0
    	 * @access public
    	 *
    	 * @global wpdb $wpdb WordPress database abstraction object.
    	 */
    	public function query() {
    		global $wpdb;

    		$this->results = $wpdb->get_col("SELECT DISTINCT($wpdb->users.ID)" . $this->query_from . $this->query_where . $this->query_orderby . $this->query_limit);

    		if ( $this->results )
    			$this->total_users_for_query = $wpdb->get_var("SELECT COUNT(DISTINCT($wpdb->users.ID))" . $this->query_from . $this->query_where); // No limit.
    		else
    			$this->search_errors = new WP_Error('no_matching_users_found', __('No users found.'));
    	}

    	/**
    	 * Prepares variables for use in templates.
    	 *
    	 * @since 2.1.0
    	 * @access public
    	 */
    	function prepare_vars_for_template_usage() {}

    	/**
    	 * Handles paging for the user search query.
    	 *
    	 * @since 2.1.0
    	 * @access public
    	 */
    	public function do_paging() {
    		if ( $this->total_users_for_query > $this->users_per_page ) { // Have to page the results.
    			$args = array();
    			if ( ! empty($this->search_term) )
    				$args['usersearch'] = urlencode($this->search_term);
    			if ( ! empty($this->role) )
    				$args['role'] = urlencode($this->role);

    			$this->paging_text = paginate_links( array(
    				'total' => ceil($this->total_users_for_query / $this->users_per_page),
    				'current' => $this->page,
    				'base' => 'users.php?%_%',
    				'format' => 'userspage=%#%',
    				'add_args' => $args
    			) );
    			if ( $this->paging_text ) {
    				$this->paging_text = sprintf(
    					/* translators: 1: Starting number of users on the current page, 2: Ending number of users, 3: Total number of users. */
    					'<span class="displaying-num">' . __( 'Displaying %1$s&#8211;%2$s of %3$s' ) . '</span>%s',
    					number_format_i18n( ( $this->page - 1 ) * $this->users_per_page + 1 ),
    					number_format_i18n( min( $this->page * $this->users_per_page, $this->total_users_for_query ) ),
    					number_format_i18n( $this->total_users_for_query ),
    					$this->paging_text
    				);
    			}
    		}
    	}

    	/**
    	 * Retrieves the user search query results.
    	 *
    	 * @since 2.1.0
    	 * @access public
    	 *
    	 * @return array
    	 */
    	public function get_results() {
    		return (array) $this->results;
    	}

    	/**
    	 * Displaying paging text.
    	 *
    	 * @see do_paging() Builds paging text.
    	 *
    	 * @since 2.1.0
    	 * @access public
    	 */
    	function page_links() {
    		echo $this->paging_text;
    	}

    	/**
    	 * Whether paging is enabled.
    	 *
    	 * @see do_paging() Builds paging text.
    	 *
    	 * @since 2.1.0
    	 * @access public
    	 *
    	 * @return bool
    	 */
    	function results_are_paged() {
    		if ( $this->paging_text )
    			return true;
    		return false;
    	}

    	/**
    	 * Whether there are search terms.
    	 *
    	 * @since 2.1.0
    	 * @access public
    	 *
    	 * @return bool
    	 */
    	function is_search() {
    		if ( $this->search_term )
    			return true;
    		return false;
    	}
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-admin/includes/deprecated.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.0/src/wp-admin/includes/deprecated.php#L339)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.0/src/wp-admin/includes/deprecated.php#L339-L677)

## 󠀁[Changelog](https://developer.wordpress.org/reference/classes/wp_user_search/?output_format=md#changelog)󠁿

| Version | Description | 
| [3.1.0](https://developer.wordpress.org/reference/since/3.1.0/) | Deprecated. Use [WP_User_Query](https://developer.wordpress.org/reference/classes/wp_user_query/) | 
| [2.1.0](https://developer.wordpress.org/reference/since/2.1.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fclasses%2Fwp_user_search%2F)
before being able to contribute a note or feedback.