WordPress get user functions explained

There are quite a few different functions to load users in WordPress. Our goal for this guide is to explore the main WordPress functions that load user data. We’ll look into their structure, advantages, and main use cases. After this, we’ll explore a plugin option to load users with no custom code.

This detailed guide should help you find the best functions for your needs. We’ll organize the functions in the following two groups:

• Single user functions – functions that can be used to load a single user’s data
• Functions on user lists – functions that can be used to load a list of users

The following table includes a list of all the main WordPress user loading functions. You can use this table as a quick reference of which functions are designed to work with single users and user lists. In this table we have three reference columns:

• Single user/User list – shows you whether the function loads a single user or a list of users
• Search by ID – specifies whether the function can be used to search users by ID
• Search by other properties – specifies whether the function can be used to search users by other properties, such as user name or user role
• WP_User – specifies whether the returned user data is a WP_User object

Function name	Single user/User list	Search by ID	Search by other properties	WP_User
wp_get_current_user	Single user			✓
get_current_user_id	Single user
get_user_by	Single user	✓	✓	✓
get_userdata	Single user	✓		✓
count_user_posts	Single user	✓
WP_User_Query class	User list	✓	✓	✓
get_users	User list	✓	✓	✓
wp_dropdown_users	User list	✓	✓
count_many_users_posts	User list	✓

Now let’s go through each of these functions.

 

Get single user data functions

These are WordPress functions that allow you to get user data for a specific user. The different functions require you to have different information for the user in order to retrieve the desired data. Let’s look into the different get WordPress user functions for a single user.

wp_get_current_user() – Get current WordPress user

This function loads the current logged in user as an WP_User object. As it loads the current user, there are no arguments for it, but its return object is quite extensive. This object gives you access to all the main user information, such as name, email, and roles.

Here is a simple example, let’s display a welcome message for our users:

$user = wp_get_current_user();
echo "Welcome, ".$user->display_name."! It's great to see you here.";

In case you are wondering the main elements of the WordPress user object you get with this function is something like this:

WP_User Object(
  ['data'] => stdClass Object(
    ['ID'] => 1,
    ['user_login'] => 'admin',
    ['user_pass'] => $hash,
    ['user_nicename'] => 'admin',
    ['user_email'] => 'email@domain.com',
    ['user_registered'] => '2017-03-08 13:10:44',
    ['display_name'] => 'John Doe'
  ),
  ['ID'] => 1,
  ['caps'] => Array( //shorthand version of capabilities
    ['administrator'] => 1
  ),
    ['roles'] => Array( //all user roles listed
    ['0'] => rolename
  ),
  ['allcaps'] => Array( //all user capabilities
    ['capname'] => 1
  )
)

Once you have the object, you can read and update different properties of the user. You can read more about the available user object methods and properties on the WP_User class reference page.

get_current_user_id() – Get current WordPress user id

This function is a quick way to load just the ID of the currently logged in user. Although it is similar to the previous function it is much quicker and has its use cases where you don’t need the full WordPress User Object. For instance, you may want to add a custom user meta field to users who visit a specific page. This can be used so you know later that they have seen it, and when this happened. You don’t need anything else beyond the user ID and the current timestamp for that.

$user_id = get_current_user_id();
//updates the visit custom field with the latest timestamp
update_user_meta( $user_id, 'visit', time() );

This function simply returns the user ID or false in case the user is a guest visitor.

return ( false | (int) $userID )

get_user_by() – Get user by property

This function allows you to find a user based on different user properties. Unlike the above-mentioned functions, this one allows you to access any user – not only the currently logged in user. This is particularly useful for admins as it allows them to search and modify users using this function.

The get_user_by function accepts many arguments for the fields (what you want to search for) and any string for values. Here are the accepted arguments for the fields:

• id – look for specific WordPress user ID
• ID – just an alias for above
• slug – return users based on their user_nicename (which is a URL sanitized version of the username)
• email – search users based on email
• login – filter users based on their username

Here is an example, if you want to filter users based on their email:

$user = get_user_by('email', 'john@john.com');

This function returns an WP_User object when a user with the search condition is found. Otherwise, it would return false.

get_userdata() – WordPress get user by ID

This function is a quick shorthand to find a user by ID (unique identifier). Here is a quick example, in case you want to debug a user:

$user = get_userdata( 1 );

Similarly, this function returns a WP_User object when a user with the specified ID is found. If there is no user with this ID, the function would return false.

count_user_posts() – Number of posts by user

This function returns the total posts a user has created. It can be used with just specific custom post types. Additionally, you can ignore private posts. This comes in handy for system-type content, or custom post types used just for metadata.

Here is an example of how to use this function for a quick overview of your authors:

$post_count = count_user_posts( get_current_user_id() );
echo "You have created $post_count posts";

WordPress functions to get user lists

These functions load a list of multiple WordPress users, not just individual user and single user elements.

WP_User_Query class – To get a list of WordPress users based on different criteria

The WP_User_Query class allows loading a list of users based on different criteria. Although it is not a function, it’s worth mentioning it here, as it is a very common way of loading users. It provides many different search options, including custom ordering and pagination options. When loading users with WP_User_Query, all the query parameters are passed as an array to the class constructor. Then, to load the user list, we need to call the get_results() method. All of the available parameters and methods are described in the <a href="https://codex.wordpress.org/Class_Reference/WP_User_Query">WP_User_Query</a> reference.

Here is an example of loading the last 10 registered subscribers:

$query = new WP_User_Query(array(
    'role' => 'Subscriber',
    'number' => 10,
    'orderby' => 'user_registered',
    'order' => 'DESC'
));
$users = $query->get_results();

get_users() – Simple way to get WordPress users list:

This is a simpler way to load a list of users. The get_users function actually uses WP_User_Query under the hood. It can be used for multiple arguments and you can combine a lot of them at once. This is surely the most complete function and replaces some of the deprecated functions as well. You can find the full list of accepted arguments on the <a href="https://codex.wordpress.org/Function_Reference/get_users">get_users</a> function guide.

Here is the same example of loading the last 10 registered subscribers, this time by using the get_users function:

$users = get_users(array(
    'role' => 'Subscriber',
    'number' => 10,
    'orderby' => 'user_registered',
    'order' => 'DESC'
));

wp_dropdown_users() – Get WordPress users in dropdown:

This is an interesting function to load WordPress users and create a dropdown for user selection. This may be useful for plugins that change user settings or assign users to data. It has some parameters used for user filtering and output preparation as well – you can find the full list in the function reference here.

Let’s see an example of this function. It could be used for an interactive author archive or team page. Then you list them as a dropdown and as your users change options your page reacts to reload your content. Here is how to display the authors:

wp_dropdown_users( array('who' => 'authors' ) );

This is how the dropdown looks on the front-end:

 

count_many_users_posts() – Get number of posts for a list of users:

This function gets many post counts for a list of user IDs. When you need to load the number of posts for a list of users, you should use this function. This is a better option from calling the count_user_posts() function for each user. That’s because count_many_users_posts() will make a single database query for the full list of users, while count_user_posts() will make a separate query for each user. In this way, you may end up doing hundreds of database queries at once.

$users = count_many_users_posts( array(1, 2, 3, 4) );

echo "<h2>Posts made by our authors</h2>";
foreach ($users as $user => $count) {
  echo "ID: ".$user." - Count: ".$count."<br />";
}

How to load different user lists with the Users Insights plugin

Of course, getting our hands dirty and creating code solutions is quite fun. But we can use Users Insights for similar filters, getting this information much faster.

For example, you can quickly see how many posts, comments or other content types your users have. And it’s possible to filter users based on them:

Or, if you wanted to filter all users who visited a page, you can do that instead of using the meta field update that we illustrated above:

 

Conclusion

Today we looked into many WordPress functions to get users. These ranged from simple functions for getting individual users to user list functions. Additionally, we saw how to achieve similar results using the Users Insights WordPress plugin. In conclusion, we hope you can use this guide as a quick reference and comparison chart of WordPress user functions.

We hope you enjoyed it, and see you again next time!