Earlier this week, I published a post on how to find users in WordPress by using meta data. In short, I have a collection of users each of which have unique meta data and I needed to locate a user based on said meta data.

In the comments, Curtis of @WPThemeTut recommended I check out WP_User_Query as opposed to way that I was doing it (which I’ll cover momentarily).

Because the WordPress API has a tendency to introduce new functions for querying specific data in later releases, and because I try to be a proponent of using the newer methods, I wanted to cover WP_User_Query in a bit more detail.

The Old Way

If you read my post from earlier this week, then you’ll currently see my function using WP_User_Query.

Originally, however, this is what I was doing:

function get_user_by_meta_data( $meta_key, $meta_value ) {

	// Set the critera for loading users
	$args = array(
		'meta_key'		=>	$meta_key,
		'meta_value'	=>	$meta_value

	// Get the users and store the user returned by the query
	$users = get_users( $args );
	$user = empty ( $users[0] ) ? null : $users[0];

	return $user;

} // end get_user_by_meta_data

Simple enough – it’s nothing more than a call to get_users and then passing in an array of parameters on which to search, but rather than returning the array of users, it returns the first one.

Of course, you could generalize it and have it return $users. Either way, that’s beside the point.

The New Way

After Curtis’s suggestion, I ended up implementing the above function like this:

function get_user_by_meta_data( $meta_key, $meta_value ) {

	// Query for users based on the meta data
	$user_query = new WP_User_Query(
			'meta_key'	  =>	$meta_key,
			'meta_value'	=>	$meta_value

	// Get the results from the query, returning the first user
	$users = $user_query->get_results();

	return $user = empty ( $users[0] ) ? null : $users[0];

} // end get_user_by_meta_data

Subtle differences, right? Again, you could just as easily return $user_query->get_results() rather than the first user that matches the search, but that’s neither here nor there.

But Why?

The first way worked fine, so why swap to the new method? Simply put, WordPress has been introducing new features to its API with each new release. Recall that The Right Way™ was once to use query_posts in order to retrieve post data.

However, as of recent releases, WP_Query has become The Right Way™ to do it. It’s a cleaner interface, more powerful, and is the way that’s backed by Automattic and the developer community at large for properly querying the database for a variety of data.

All of that to say that this is strikingly similar – just as we’ve got from query_posts to WP_Query, we’re going from get_users to WP_User_Query.

It’s all about forward thinking.

The Details on WP_User_Query

The Codex article will provide much more information that I have below; however, I want to make sure that I highlight exactly what WP_User_Query offers if for no other reason to remind myself of what it can do.

Straight from the documentation:

The WordPress User Query class allows querying the user database and deprecates the WP_User_Search class since Version 3.1.


  • An array of arguments from which it will use to query the database for results
  • Returns either an array of row objects or an array of user objects

To use the class – as with many in the WordPress API – you define the array of arguments and then pass them to the constructor of the WP_User_Query while instantiating the class. Assuming that your arguments are stored in an array referenced by $args, it would look like this:

  • $user_query = new WP_User_Query( $args );

Then, to get your array of results, you’d call:

  • $user_query->get_results()

Easy, isn’t it?

Overall, I’m a fan of this graduate shift to class-based queries rather than using global-level functions, but that’s because I’m more of a fan of object-oriented programming.

Regardless, this is the new way to query for users so consider this a heads up and start using it in new projects :).