Managing user data and retrieving users with specific criteria is an essential capability for any website or application. With the get_users function in WordPress, you have a powerful tool to effortlessly retrieve a list of users that match your specified parameters. Whether you want to filter users based on their roles, display only authors’ profiles, or search for a specific user using their ID or username, the get_users function has got you covered.
By utilizing query parameters and default values, this function enables precise searches and returns a comprehensive list of users that meet your criteria. No more manual searching or digging through database tables – with the get_users function, you can efficiently fetch all the user data you need in just a few simple lines of code.
Syntax
| function get_users( $args = array() ) |
Parameters
- $args (optional): An array of arguments to retrieve users. See WP_User_Query::prepare_query() for more information on accepted arguments.
Return Value
An array containing the list of users that match the specified criteria.
How it Works
| <?php | |
| /** | |
| * Retrieves list of users matching criteria. | |
| * | |
| * @since 3.1.0 | |
| * | |
| * @see WP_User_Query | |
| * | |
| * @param array $args Optional. Arguments to retrieve users. See WP_User_Query::prepare_query() | |
| * for more information on accepted arguments. | |
| * @return array List of users. | |
| */ | |
| function get_users($args = []) | |
| { | |
| $args = wp_parse_args($args); | |
| $args["count_total"] = false; | |
| $user_search = new WP_User_Query($args); | |
| return (array) $user_search->get_results(); | |
| } |
- The function takes an optional argument $args, which is an array of parameters used to retrieve the users.
- The function first parses and merges any user-defined arguments with the default values.
- The ‘count_total’ parameter in $args is set to false to disable counting total number of users.
- A new instance of the WP_User_Query class is created with the modified $args.
- The get_results() method is called on the $user_search object returned by WP_User_Query, which retrieves the list of users matching the specified criteria.
- The return value, which is an object, is casted to an array and returned as a list of users.
This function can be used in WordPress applications to search and filter users based on various criteria such as user IDs, specific roles, meta keys, etc. By providing different sets of parameters in $args, you can retrieve a customized list of users according to your needs.
For more information about querying WordPress users and available options, refer to the official documentation.
Usage Examples
Example: Get All Users in WordPress Plugin
To get all users in a custom WordPress plugin, you can use the get_users() function. This can be useful in scenarios such as creating a user directory or generating a report that includes all users on your website.
| <?php | |
| /** | |
| * Retrieves and lists all users in the WordPress database. | |
| * | |
| * @since 1.0.0 | |
| */ | |
| function my_plugin_get_all_users() | |
| { | |
| $args = []; | |
| $users = get_users($args); | |
| foreach ($users as $user) { | |
| // Output or process each user's information | |
| echo $user->display_name . ' '; | |
| } | |
| } |
Explanation:
- The code snippet defines a function my_plugin_get_all_users() to retrieve and list all users.
- It initializes an empty array called $args to provide optional arguments for the get_users() function (none specified in this case).
- Passing the $args array into the get_users() function without any specific arguments retrieves all users.
- The resulting list of users is then looped through using a foreach loop, and each user’s display name is echoed or processed as needed.
Hook to Invoke Plugin Function:
To execute my_plugin_get_all_users(), you can hook it to an appropriate action within your plugin file. For example:
| <?php | |
| add_action( 'init', 'my_plugin_get_all_users' ); |
This will execute the function when WordPress initializes and loads page content.
Example: Get Users by Role
When developing a WordPress theme, you may want to gather and display only users with specific roles. You can accomplish this using the get_users() function with role-based arguments.
| <?php | |
| /** | |
| * Displays logged-in subscribers on the front end of a WordPress theme. | |
| * | |
| * @since 1.0.0 | |
| */ | |
| function my_theme_display_subscribers() | |
| { | |
| $args = [ | |
| "role" => "subscriber", | |
| ]; | |
| $users = get_users($args); | |
| foreach ($users as $user) { | |
| // Echo or process each logged-in subscriber's information | |
| echo $user->user_login . ' '; | |
| } | |
| } |
Explanation:
- The code snippet defines my_theme_display_subscribers(), which displays a list of users with the specific role of “subscriber”.
- An array named $args is declared, assigning ‘subscriber’ as the role value.
- When invoking get_users() and passing in the $args array, it retrieves only users with the specified role.
- The resulting list of users is looped through, and for each user of interest, their login name is echoed or processed.
Hook to Invoke Theme Function:
To display subscribers using my_theme_display_subscribers(), you can hook this function to suitable action within your theme files. For example:
| <?php | |
| add_action( 'wp_footer', 'my_theme_display_subscribers' ); |
By adding this to your theme’s footer, it will call the function and output logged-in subscriber information at the bottom of every page on your website.
Example: Retrieve a list of all user data through the WordPress REST API
The get_users() function can be used to retrieve a list of all users in the WordPress database using the WordPress REST API. This can be useful if you want to create custom endpoints or functionality related to user data.
| <?php | |
| /** | |
| * Plugin Name: User List API | |
| * Description: Creates a custom endpoint to fetch all users. | |
| * Version: 1.0.0 | |
| */ | |
| // Register custom endpoint for getting all users | |
| add_action("rest_api_init", "register_users_endpoint"); | |
| function register_users_endpoint() | |
| { | |
| register_rest_route("myplugin/v1", "/users", [ | |
| "methods" => "GET", | |
| "callback" => "get_all_users_callback", | |
| ]); | |
| } | |
| // Callback function for the custom endpoint | |
| function get_all_users_callback() | |
| { | |
| $args = []; | |
| $users = get_users($args); | |
| return $users; | |
| } |
Explanation:
- We are creating a plugin called “User List API” that provides a custom REST endpoint to fetch all users.
- The register_rest_route() function is used to create the /myplugin/v1/users endpoint, which will use the HTTP GET method.
- Inside the callback function get_all_users_callback(), we call the get_users() function with no arguments, which retrieves all users.
- The obtained list of users is then returned by the callback function as the response.
Once the plugin is activated, you can make an HTTP GET request to /wp-json/myplugin/v1/users to retrieve a JSON response containing all users.
