云策 WordPress 开发者社区

函数文档

get_users()

查看官方原文 ↗
💡 云策文档标注

概述

get_users() 函数用于根据指定条件检索用户列表，基于 WP_User_Query 类实现。返回结果类型取决于 'fields' 参数设置，可以是 WP_User 对象、stdClass 对象或 ID 数组。

关键要点

  • 函数接受一个可选的 $args 数组参数，用于定义查询条件，参数详情参考 WP_User_Query::prepare_query()。
  • 返回值类型由 'fields' 参数控制：默认 'all' 或 'all_with_meta' 返回 WP_User 对象数组；设置为 wp_users 表字段数组时返回 stdClass 对象数组；设置为单个字段时返回 ID 数组。
  • 函数内部使用 WP_User_Query 执行查询，并返回结果数组。
  • 注意：当使用 meta_value 查询且值为空字符串时，查询可能降级为仅按 meta_key 搜索，需谨慎处理以避免安全漏洞。
  • 在大型站点上，默认参数可能导致性能问题，建议合理设置查询限制。

代码示例

// 示例1：按角色查询用户
$blogusers = get_users( array( 'role__in' => array( 'author', 'subscriber' ) ) );
foreach ( $blogusers as $user ) {
    echo '' . esc_html( $user->display_name ) . '';
}

// 示例2：使用搜索字段
$blogusers = get_users( array( 'search' => 'john' ) );
foreach ( $blogusers as $user ) {
    echo '' . esc_html( $user->user_email ) . '';
}

// 示例3：查询特定字段
$blogusers = get_users( array( 'fields' => array( 'display_name' ) ) );
foreach ( $blogusers as $user ) {
    echo '' . esc_html( $user->display_name ) . '';
}

注意事项

  • 确保对用户输入进行适当清理和验证，特别是在使用 meta_value 查询时，避免空字符串导致的查询降级问题。
  • 在大型站点中，避免使用默认参数（如 number 为 -1 表示所有用户），以优化性能。
  • WordPress 6.0 起，WP_User_Query 支持更多 fields 选项，更新时注意兼容性。
📄 原文内容

Retrieves list of users matching criteria.

Description

See also

Parameters

$argsarrayoptional
Arguments to retrieve users. See WP_User_Query::prepare_query() for more information on accepted arguments.

Default:array()

Return

array List of users.

More Information

Return value is an array of IDs, stdClass objects, or WP_User objects, depending on the value of the ‘fields‘ parameter.

  • If ‘fields‘ is set to ‘all’ (default), or ‘all_with_meta’, it will return an array of WP_User objects.
  • If ‘fields‘ is set to an array of wp_users table fields, it will return an array of stdClass objects with only those fields.
  • If ‘fields‘ is set to any individual wp_users table field, an array of IDs will be returned.

Source

function get_users( $args = array() ) {

	$args                = wp_parse_args( $args );
	$args['count_total'] = false;

	$user_search = new WP_User_Query( $args );

	return (array) $user_search->get_results();
}

View all references View on Trac View on GitHub

Uses Description
WP_User_Query::__construct()wp-includes/class-wp-user-query.php

Constructor.
wp_parse_args()wp-includes/functions.php

Merges user defined arguments into defaults array.
Used by Description
wp_list_users()wp-includes/user.php

Lists all the users of the site, with several options available.
_build_block_template_result_from_post()wp-includes/block-template-utils.php

Builds a unified template object based a post Object.
wp_uninitialize_site()wp-includes/ms-site.php

Runs the uninitialization routine for a given site.
populate_network_meta()wp-admin/includes/schema.php

Creates WordPress network meta and sets the default values.
wpmu_delete_blog()wp-admin/includes/ms.php

Deletes a site.
wp_ajax_autocomplete_user()wp-admin/includes/ajax-actions.php

Handles user autocomplete via AJAX.
confirm_delete_users()wp-admin/includes/ms.php
wp_dropdown_users()wp-includes/user.php

Creates dropdown HTML content of users.
wp_list_authors()wp-includes/author-template.php

Lists all the authors of the site, with several options available.
wp_xmlrpc_server::wp_getAuthors()wp-includes/class-wp-xmlrpc-server.php

Retrieves authors list.
wp_xmlrpc_server::wp_getUsers()wp-includes/class-wp-xmlrpc-server.php

Retrieves users.

Show 6 moreShow less

Changelog

Version Description
3.1.0 Introduced.

User Contributed Notes

  1. Skip to note 8 content


    growthwp


    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

    Please note that if you search by `meta_value` and it ends up being `”` (an empty string), the query, which is really a wrap over the `WP_User_Query` class and hence this applies to other functions as well, ends up forfeiting the check for the `meta_value` and simply downgrades to searching by `meta_key` only.

    Please be very careful when you have `meta_values` that are dynamic or that you can’t/don’t check for this exact case, if the list that you retrieve using this query is used for something important, you might end up with security holes.

    “User input should be parsed”. Yes, but, user input should not be immediately `esc_html`’d or the like, escape at output, sanitize before queries and now that we know this, check for validity — but here lies the problem, we, as well as some people who’ve been with WP for 10+ years didn’t know about this behavior. A `preg_match` fixes it all, yes, but only if your assumptions are updated with this knowledge.

    Additionally, this is not a case of “you just forgot to parse”, we parse everything that comes inside and had security audits on our core codebase pieces but just simply weren’t aware of this behavior and assumed we didn’t even need to parse.

    I’ve opened a ticket about it if you’re interested in a PoC and how it affected us specifically: https://core.trac.wordpress.org/ticket/49641

  3. Skip to note 10 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    An example using the ‘search’ field.

     'john' ) );
// Array of WP_User objects.
foreach ( $blogusers as $user ) {
	echo '<span>' . esc_html( $user->user_email ) . '</span>';
}

    This example will find and display all users that have a user name, ID, email of “john”. You can also do wild card search by adding an * before or after your search query. For example, to search for all users that start with “jo”, you would pass something like “jo*”.

    The results will be all users whose user names, IDs, or emails that start with “jo”. The * can be placed before or after your search query. When placed before, the results will be all users that end in your query.