get_user_by()

💡 云策文档标注

概述

get_user_by() 是 WordPress 核心函数，用于根据指定字段（如 ID、邮箱、登录名等）检索用户信息。它返回一个 WP_User 对象或 false，适用于开发者快速获取用户数据。

关键要点

参数 $field 接受 'id'、'ID'、'slug'、'email'、'login' 作为字段类型，区分大小写。
参数 $value 是对应字段的值，如用户 ID、邮箱地址或登录名。
返回值：成功时返回 WP_User 对象，失败时返回 false，建议使用前检查返回值。
函数内部调用 WP_User::get_data_by() 获取数据，然后初始化 WP_User 对象。
从 4.4.0 版本起，'ID' 成为 'id' 的别名，增强了兼容性。

代码示例

// 通过 ID 获取用户
$author_obj = get_user_by('id', 1);

// 通过邮箱获取用户并输出姓名
$user = get_user_by('email', 'user@example.com');
if (!empty($user)) {
    echo 'User is ' . $user->first_name . ' ' . $user->last_name;
}

// 通过登录名获取用户 ID
$user = get_user_by('login', 'loginname');
if ($user) {
    echo $user->ID;
}

注意事项

使用 'login' 字段时，注意其大小写敏感性可能因版本而异，建议测试确认。
访问用户属性时，邮箱应使用 $user->user_email，而非 'email'。
函数广泛用于用户认证、通知和 REST API 等场景，如 wp_authenticate_application_password() 和 WP_REST_Users_Controller。

📄 原文内容

Retrieves user info by a given field.

Parameters

$fieldstringrequired: The field to retrieve the user with. id | ID | slug | email | login.
$valueint|stringrequired: A value for $field. A user ID, slug, email address, or login name.

Return

WP_User|false WP_User object on success, false on failure.

Source

function get_user_by( $field, $value ) {
	$userdata = WP_User::get_data_by( $field, $value );

	if ( ! $userdata ) {
		return false;
	}

	$user = new WP_User();
	$user->init( $userdata );

	return $user;
}

View all references View on Trac View on GitHub

Uses	Description
WP_User::get_data_by()`wp-includes/class-wp-user.php`	Returns only the main user fields.
WP_User::__construct()`wp-includes/class-wp-user.php`	Constructor.

Used by	Description
get_user()`wp-includes/user.php`	Retrieves user info by user ID.
WP_REST_Templates_Controller::get_wp_templates_author_text_field()`wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php`	Returns a human readable text for the author of the template.
wpmu_new_site_admin_notification()`wp-includes/ms-functions.php`	Notifies the Multisite network administrator that a new site was created.
wp_authenticate_application_password()`wp-includes/user.php`	Authenticates the user using an application password.
WP_Automatic_Updater::send_plugin_theme_email()`wp-admin/includes/class-wp-automatic-updater.php`	Sends an email upon the completion or failure of a plugin or theme background update.
populate_network_meta()`wp-admin/includes/schema.php`	Creates WordPress network meta and sets the default values.
get_object_subtype()`wp-includes/meta.php`	Returns the object subtype for a given object ID of a specific type.
wp_create_user_request()`wp-includes/user.php`	Creates and logs a user request to perform a specific action.
wp_user_personal_data_exporter()`wp-includes/user.php`	Finds and exports personal data associated with an email address from the user and user_meta table.
wp_media_personal_data_exporter()`wp-includes/media.php`	Finds and exports attachments associated with an email address.
_wp_personal_data_handle_actions()`wp-admin/includes/privacy-tools.php`	Handle list table actions.
get_user_locale()`wp-includes/l10n.php`	Retrieves the locale of a user.
WP_REST_Users_Controller::create_item()`wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php`	Creates a single user.
WP_REST_Users_Controller::update_item()`wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php`	Updates a single user.
wp_authenticate_email_password()`wp-includes/user.php`	Authenticates a user using the email and password.
get_avatar_data()`wp-includes/link-template.php`	Retrieves default data about the avatar.
retrieve_password()`wp-includes/user.php`	Handles sending a password retrieval email to a user.
WP_Automatic_Updater::send_email()`wp-admin/includes/class-wp-automatic-updater.php`	Sends an email upon the completion or failure of a background core update.
WP_Automatic_Updater::send_debug_email()`wp-admin/includes/class-wp-automatic-updater.php`	Prepares and sends an email of a full log of background update results, useful for debugging and geekery.
wp_password_change_notification()`wp-includes/pluggable.php`	Notifies the blog admin of a user changing password, normally via email.
wp_new_user_notification()`wp-includes/pluggable.php`	Emails login credentials to a newly-registered user.
wp_notify_postauthor()`wp-includes/pluggable.php`	Notifies an author (and/or others) of a comment/trackback/pingback on a post.
wp_notify_moderator()`wp-includes/pluggable.php`	Notifies the moderator of the site about a new comment that is awaiting approval.
wp_validate_auth_cookie()`wp-includes/pluggable.php`	Validates authentication cookie.
get_userdata()`wp-includes/pluggable.php`	Retrieves user info by user ID.
get_profile()`wp-includes/deprecated.php`	Retrieve user data based on field.
WP_Query::get_queried_object()`wp-includes/class-wp-query.php`	Retrieves the currently queried object.
WP_Query::get_posts()`wp-includes/class-wp-query.php`	Retrieves an array of posts based on query variables.
check_password_reset_key()`wp-includes/user.php`	Retrieves a user row based on password reset key and login.
username_exists()`wp-includes/user.php`	Determines whether the given username exists.
email_exists()`wp-includes/user.php`	Determines whether the given email exists.
wp_authenticate_username_password()`wp-includes/user.php`	Authenticates a user, confirming the username and password are valid.
get_userdatabylogin()`wp-includes/pluggable-deprecated.php`	Retrieve user info by login name.
get_user_by_email()`wp-includes/pluggable-deprecated.php`	Retrieve user info by email.
wp_setcookie()`wp-includes/pluggable-deprecated.php`	Sets a cookie for a user who just logged in. This function is deprecated.
get_pages()`wp-includes/post.php`	Retrieves an array of pages (or hierarchical post type items).
is_user_spammy()`wp-includes/ms-functions.php`	Determines whether a user is marked as a spammer, based on user login.
wpmu_signup_blog_notification()`wp-includes/ms-functions.php`	Sends a confirmation request email to a user when they sign up for a new site. The new site will not become active until the confirmation link is clicked.
wpmu_signup_user_notification()`wp-includes/ms-functions.php`	Sends a confirmation request email to a user when they sign up for a new user account (without signing up for a site at the same time). The user account will not become active until the confirmation link is clicked.
is_site_admin()`wp-includes/ms-deprecated.php`	Determine if user is a site admin.
get_user_details()`wp-includes/ms-deprecated.php`	Deprecated functionality to retrieve user information.
get_user_id_from_string()`wp-includes/ms-deprecated.php`	Get a numeric user ID from either an email address or a login.
check_comment()`wp-includes/comment.php`	Checks whether a comment passes internal checks to be allowed to add.

Show 38 more Show less

Changelog

Version	Description
4.4.0	Added `'ID'` as an alias of `'id'` for the `$field` parameter.
2.8.0	Introduced.

User Contributed Notes

Skip to note 8 content

Codex

11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 20You must log in to vote on the helpfulness of this note
Sample response of
```
$author_obj = get_user_by('id', 1);
```
 object(WP_User)#96 (7) { ["data"]=> object(stdClass)#95 (10) { ["ID"]=> string(1) "1" ["user_login"]=> string(10) "superadmin" ["user_pass"]=> string(34) "$P$Bx0Jgq6/Qw/o3A5fXcVKg4jxQr2PAB1" ["user_nicename"]=> string(10) "superadmin" ["user_email"]=> string(16) "user@example.com" ["user_url"]=> string(0) "" ["user_registered"]=> string(19) "2014-02-21 21:31:40" ["user_activation_key"]=> string(0) "" ["user_status"]=> string(1) "0" ["display_name"]=> string(10) "superadmin" } ["ID"]=> int(1) ["caps"]=> array(1) { ["administrator"]=> bool(true) } ["cap_key"]=> string(25) "wp_capabilities" ["roles"]=> array(1) { [0]=> string(13) "administrator" } ["allcaps"]=> array(63) { ["switch_themes"]=> bool(true) ["edit_themes"]=> bool(true) ["activate_plugins"]=> bool(true) ["edit_plugins"]=> bool(true) ["edit_users"]=> bool(true) ["edit_files"]=> bool(true) ["manage_options"]=> bool(true) ["moderate_comments"]=> bool(true) ["manage_categories"]=> bool(true) ["manage_links"]=> bool(true) ["upload_files"]=> bool(true) ["import"]=> bool(true) ["unfiltered_html"]=> bool(true) ["edit_posts"]=> bool(true) ["edit_others_posts"]=> bool(true) ["edit_published_posts"]=> bool(true) ["publish_posts"]=> bool(true) ["edit_pages"]=> bool(true) ["read"]=> bool(true) ["level_10"]=> bool(true) ["level_9"]=> bool(true) ["level_8"]=> bool(true) ["level_7"]=> bool(true) ["level_6"]=> bool(true) ["level_5"]=> bool(true) ["level_4"]=> bool(true) ["level_3"]=> bool(true) ["level_2"]=> bool(true) ["level_1"]=> bool(true) ["level_0"]=> bool(true) ["edit_others_pages"]=> bool(true) ["edit_published_pages"]=> bool(true) ["publish_pages"]=> bool(true) ["delete_pages"]=> bool(true) ["delete_others_pages"]=> bool(true) ["delete_published_pages"]=> bool(true) ["delete_posts"]=> bool(true) ["delete_others_posts"]=> bool(true) ["delete_published_posts"]=> bool(true) ["delete_private_posts"]=> bool(true) ["edit_private_posts"]=> bool(true) ["read_private_posts"]=> bool(true) ["delete_private_pages"]=> bool(true) ["edit_private_pages"]=> bool(true) ["read_private_pages"]=> bool(true) ["delete_users"]=> bool(true) ["create_users"]=> bool(true) ["unfiltered_upload"]=> bool(true) ["edit_dashboard"]=> bool(true) ["update_plugins"]=> bool(true) ["delete_plugins"]=> bool(true) ["install_plugins"]=> bool(true) ["update_themes"]=> bool(true) ["install_themes"]=> bool(true) ["update_core"]=> bool(true) ["list_users"]=> bool(true) ["remove_users"]=> bool(true) ["add_users"]=> bool(true) ["promote_users"]=> bool(true) ["edit_theme_options"]=> bool(true) ["delete_themes"]=> bool(true) ["export"]=> bool(true) ["administrator"]=> bool(true) } ["filter"]=> NULL } 
Log in to add feedback
Skip to note 9 content

Codex

11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 18You must log in to vote on the helpfulness of this note
Default usage
```
$user = get_user_by( 'email', 'user@example.com' );
echo 'User is ' . $user->first_name . ' ' . $user->last_name;
```
Log in to add feedback
Skip to note 10 content

Joseph G.

10 years ago

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

I always prefer to check if the variable ($user) is empty or not before echoing any properties of the $user object:

$user = get_user_by( ’email’, ‘user@example.com’ );

if ( ! empty( $user ) ) {
echo ‘User is ‘ . $user->first_name . ‘ ‘ . $user->last_name;
}

This is to keep things clean and prevent error messages and warnings.

Log in to add feedback
Skip to note 11 content

Jino MB

8 years ago

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
If you want to get the user id from user loginname.
```
$user = get_user_by('login','loginname');
if($user)
{
   echo $user->ID;
}
```
Log in to add feedback
Skip to note 12 content

destabilizator

7 years ago

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

To obtain user’s email via this, you have to use “user_email” property, not just “email”.

$user = get_user_by('login', $username); if ($user) { $details['name'] = $user->first_name . ' ' . $user->last_name; $details['email'] = $user->user_email; };

Log in to add feedback
Skip to note 13 content

zackcarlson

8 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
```
get_user_by('login', $user_login)
```
is case sensitive. Which means
```
get_user_by('login', "UserName")
```
would not match any users with like
```
"username"
```
- It looks like this is no longer case sensitive on at least the login or email search options.
  
  Wade 4 years ago
Log in to add feedback

Skip to note 14 content

Ahmad Ali

4 years ago

Find user by id / email / username

 
$new_member_id = $_POST['new_member_id'];
$u = null;
    
if (intval($new_member_id)) $u = get_user_by('id', $new_member_id);
else if (strpos($new_member_id, '@') != false) $u = get_user_by('email', $new_member_id);
else $u = get_user_by('login', $new_member_id);

云策 WordPress 开发者社区

函数文档

get_user_by()

概述

关键要点

代码示例

注意事项

Parameters

Return

Source

Changelog

User Contributed Notes

函数文档

概述

关键要点

代码示例

注意事项

Parameters

Return

Source

Related

Changelog

User Contributed Notes