Just like the post meta system, WordPress has a powerful user meta system that allows developers to store additional “meta” information about the registered users in the database. This meta information can be just about anything you want it to be, and can serve a variety of purposes. At the time of writing this tutorial, I’m using the user meta system in my Pro version of Restrict Content to greatly expand the functionality of the plugin.

Querying users from the WordPress database is not much different than querying posts. WordPress has a nice function called get_users() that will retrieve all the registered users that meet the specified criteria. In this case, we’re only wanting to pull users that have a particular meta key with a certain value. Luckily for us, the get_users() function has a parameter for “meta_key” and “meta_value”, so this is pretty easy.

1
2
3
4
5

$members = get_users(array(
		'meta_key' => 'your_meta_key', 
		'meta_value' => 'your_meta_value', 
	)
);

This will return an array of user objects for each user that is found that has the specified meta key and value. You could then do as you wish with the returned array, or display it in a variety of methods, such as this one:

1
2
3

foreach($members as $member) {
	echo '<li id="user_' . $member->ID . '">' . $member->user_login . '</li>';
}

Creating a Wrapper Function for get_users()

When writing a plugin, such as Restrict Content Pro, I often like to create “wrapper” functions for core functions such as get_users(). The reason is simple: I will use the get_users() function quite a few times throughout the plugin, often with many of the same parameters (though some times they will change), so by making a wrapper function I can decrease the overall amount of code I write by predefining the parameters that I need and then just calling my wrapper function, instead of the one provided by WP core. Let me show you an example.

1
2
3
4
5
6
7
8
9
10
11

function pippin_get_members( $status = 'active', $offset = 0, $number = -1) {	
	$members = get_users(array(
			'meta_key' => 'rcp_status', 
			'meta_value' => $status, 
			'offset' => $offset, 
			'number' => $number, 
			'count_total' => false
		)
	);
	return $members;
}

This function takes four parameters and then passes them to the get_users() function. In Restrict Content Pro, there will be a meta key stored in the meta table for each user that defines what their subscription status is, so I use this function to retrieve all users of a particular status. If I want to get all of the users that have an “active” subscription, I use this:

1

$members = pippin_get_members('active');

or all of the users that are expired:

1

$members = pippin_get_members('expired');

or all of the users that are pending, but only 5 of them:

1

$members = pippin_get_members('active', 0, 5);

Wrapper functions like this work exceptionally well when you have a task that needs to be performed multiple times in your plugin. Rather than writing out all of the parameters every time, just call one function with one parameter, or several depending on your wrapper function.

Counting Members Based on Meta Value

One of that tasks that typically goes along with retrieving users, especially for plugins that are focused around the user system in WordPress, is getting a count of all the users that match your specified criteria. There are definitely many ways that you could do this, but one of the ways is to do a custom meta query using the count() function of SQL.

1
2
3
4
5
6
7
8
9
10
11
12

function pippin_count_members( $status = 'active' ) {	
	global $wpdb;
 
	$count = $wpdb->get_var( $wpdb->prepare(
		"SELECT COUNT(*) FROM $wpdb->users
		LEFT JOIN $wpdb->usermeta ON $wpdb->users.ID = $wpdb->usermeta.user_id
		WHERE meta_key = 'rcp_status'
		AND meta_value = '$status';"
	, $level ));
 
	return $count;
}

Once again, using Restrict Content Pro as an example, this function will return a numerical count of all the users that have a meta_key of “rcp_status” and a value of “active”, or any other status that is passed to the function. You can call this function like so:

1
2
3
4
5

// get all of the active members
$count = pippin_count_members('active');
 
// get all of the expired members
$count = pippin_count_members('expired');

If you want to adapt this function to your own uses, simply change the line that says

WHERE meta_key = 'rcp_status'

to the meta key you wish to use.

Adding / Updating / Getting User Meta Values

The user meta system is extremely easy to work with. It functions in exactly the same way as the post meta system, so if you’ve used that before then you won’t have any problems with it at all. If you’ve never used either, then you’re still in luck because the WordPress Codex has some nice examples.

There are two primary functions you will use when working with user meta:

update_user_meta() and get_user_meta()

These two function will get you a long ways. If you would like to see me write more about these two functions, and to discuss things you can do with them, let me know below in the comments.