An overview of the WordPress get user functions

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

wordpress get_user functions

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 name or 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.

 

Single user functions

wp_get_current_user()

This function loads the current logged in user as a 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 data, such as name, email and roles.

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

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

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 in the WP_User class reference page.

get_current_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.

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

get_user_by()

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, so they can 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 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:

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

get_userdata()

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

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()

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:

Functions on user lists

These functions load multiple users, not just individual elements.

WP_User_Query class

The WP_User_Query class allows to load 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 WP_User_Query reference.

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

get_users()

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 get_users function guide.

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

wp_dropdown_users()

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 arguments used for user filtering and output preparing as well – you can find the full list in the function reference here.

Let’s see an example for 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:

An this is how the dropdown looks on the front-end:

wp_dropdown_users function

 

count_many_users_posts()

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 instead of 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.

How to load users with Users Insights

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:

How to filter users based on their activity

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:

How to filter users who visited a page

 

Conclusion

Today we looked into many WordPress functions to get users. From simple functions to get individual users, to user lists functions. In addition, we saw how to achieve similar results using Users Insights. In conclusion, we hope you can use this guide as a quick reference and comparison chart of WordPress user functions.

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