Thanks to Curtis for giving a heads up to WP_User_Query - it's a nicer alternative to the original post.

One of my favorite things about the WordPress API is the ability to store custom meta data with objects such as pages and users. I’ve been working on an application where this scenario has presented itself:

  • The end user is able to create a company
  • Each company can have an administrator based on users in the system

To do this, I’m creating a relationship between the company and user by associating the company’s ID as part of the user’s meta data.

Later in the application, I need to retrieve each administrator for each company which has required the use of a helper function to get a user by meta data.

The details of how I’m doing this are aren’t exactly interesting for this post, but I figured that this was a common enough issue and easy enough to generalize that I’d share how to programmatically get a user by meta data in WordPress:

Get User By Meta Data

In my case, the meta key value is fixed, so I’ve generalized it for the purposes of this particular post where you can pass in a specific key and value, though depending on the requirements of your application – such as in my case – the key could be hard coded and the meta value could be the variable:

function get_user_by_meta_data( $meta_key, $meta_value ) {

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

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

	return $users[0];

} // end get_user_by_meta_data

It’s simple, right?

Basically, you specify the key and value for the set of users that you want to retrieve and then return the first one in the array.

At this point, you have access to all of the fields associated with a user such as its ID, display_name, and so on. You can also get the rest of its information, such as the first_name and last_name by using the ID and a call to get_user_meta:

  • $first_name = get_user_meta( get_user_by_meta_data( 'my_meta_key', 'my_meta_value' )->ID, 'first_name', true );
  • $last_name = get_user_meta( get_user_by_meta_data( 'my_meta_key', 'my_meta_value' )->ID, 'last_name', true );

But wait, what about all users?

But there’s a catch here: this will only return the first user. Depending on the requirements of your project, you may have multiple users with the name meta value.

In that case, it may be of more interest to return the collection of users than a single user. To do that, you can generalize the above function to the following:

function get_users_by_meta_data( $meta_key, $meta_value ) {

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

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

	return $users;

} // end get_users_by_meta_data

From here, you can then iterate through the list of users to find what you need:

foreach( get_users_by_meta_data( 'my_key', 'my_value') as $user ) {
	// Do something with each $user
} // end foreach

And what about get_user_meta?

In order to use get_user_meta, you have to have a user. If you’ve already got the user ID and the meta key, then you know exactly what you need. The thing is, you may not always know exactly what user – or users – have certain data stored so it helps to have a utility function for doing just that.

Perhaps this is a niche case, but I’ve used it in two applications at this point, so it’s not niche enough to share with you guys!