WordPress WP_User 和操作用户的常用函数

最后更新于 2022 年 11 月 11 日

WordPress WP_User class用于处理用户信息，是WordPress的核心类。在WordPress插件或主题中获取用户信息时应该使用WP_User class提供的方法，不要直接访问object内容。本文列举了常用的WP_User方法和代码示例。

WordPress WP_User使用方法、代码示例和返回结果

测试环境：WordPress 6.1

创建WP_User的实例

语法：

$users = new WP_User( $id [, $name [, $blog_id ] ] );

例如：

// 创建一个WP_User的实例，用户ID为22
$user = new WP_User( 22 );

// 创建一个WP_User的实例，用户登录名为TEST-Username
$user = new WP_User( '', 'TEST-Username' );

返回结果：

WP_User::get_data_by( string $field, string|int $value )

获取用户的主要信息，不包含权限、角色等。该方法为静态方法，通过class名称直接调用。

$field可以是：id，ID，slug，email和login。

例如：

$userdata = WP_User::get_data_by( 'email', 'test@emaildomain.com');

stdClass Object
(
    [ID] => 22
    [user_login] => TEST-Username
    [user_pass] => $P$BxHrZf4YeOB5wrt2zrUleYaIpoqd7x0
    [user_nicename] => test-username
    [user_email] => test@emaildomain.com
    [user_url] => http://www.youdomain.com
    [user_registered] => 2017-12-06 05:59:56
    [user_activation_key] => 
    [user_status] => 0
    [display_name] => 张 三
)

WP_User::exists()

根据用户ID是否被赋值判断用户是否存在。

例如：

$user = new WP_User( 22 );
if( $user->exists() ){
	echo "ID为22的用户存在";
} else {
	echo "该用户不存在";
}

WP_User::get( string $key )

从users和usermeta表中查询用户数据

例如：

$user = new WP_User( 22 );
$user_email = $user->get( 'user_email' );

有效的参数包括但不限于：

ID – 用户id
user_login – 用户登录名称
user_pass – 用户密码
user_nicename – 可在url中安全使用的user_login，例如出现在文章作者链接中
user_email – 用户电子邮箱
user_url – 用户的站点链接
user_registered – 用户注册时间
display_name – 公开显示的名字
description – 用户介绍

wp_usermeta表中所有的meta_key都可以作为该方法的参数。

WP_User::has_prop( string $key )

查询某个用户字段是否存在

例如：

if ( $user->has_prop( 'my_user_key') ){
	echo 'my_user_key 存在';
} else {
	echo '不存在';
}

WP_User::to_array()

返回一个数组形式的结果

例如：

$user = new WP_User( 22 );
$user_array = $user->to_array();

打印$user_array得到：

Array
(
    [ID] => 22
    [user_login] => TEST-Username
    [user_pass] => $P$BxHrZf4YeOB5wrt2zrUleYaIpoqd7x0
    [user_nicename] => test-username
    [user_email] => test@emaildomain.com
    [user_url] => http://www.youdomain.com
    [user_registered] => 2017-12-06 05:59:56
    [user_activation_key] => 
    [user_status] => 0
    [display_name] => 张 三
)

WP_User::get_role_caps()

获取用户的所有权限

例如：

$user = new WP_User( 22 );
$allcaps = $user->get_role_caps();

得到一个包含用户所有权限的数组

Array
(
    [switch_themes] => 1
    [edit_themes] => 1
    [activate_plugins] => 1
    ...
    ...
    [level_10] => 1
    [level_9] => 1
    ...
    ...
    [delete_themes] => 1
    [export] => 1
    [administrator] => 1
)

WP_User::add_role( string $role )
WP_User::set_role( string $role )
WP_User::remove_role( string $role )

给用户增加、设置唯一角色或删除角色，set_role和add_role的区别是，set_role会执行覆盖操作，把其余角色删除，只保留set的那一个角色。

例如：

// 创建一个自定义角色custom_role,注意这句话只需执行一次，比如在插件启用的时候。可以使用插件代替，例如User Role Editor
add_role( 'custom_role', 
          'Custom Subscriber', 
          array( 'read' => true, 'level_0' => true ) 
);

// 更改用户角色
$user->add_role( 'custom_role' );
$user->set_role( 'custom_role' );
$user->remove_role( 'custom_role' );

WP_User::add_cap( string $cap, bool $grant = true )
WP_User::remove_cap( string $cap )
WP_User::remove_all_caps()

增加一个、删除一个或删除所有用户权限。add_cap()的第二个参数为false，表示给用户增加一个权限，但用户无权使用该权限。

例如：

$user = new WP_User( 22 );
$user->add_cap( 'can_edit_posts' );
$user->remove_cap( 'can_edit_posts' );
$user->remove_all_caps( 'can_edit_posts' );

WP_User::has_cap( string $cap )

判断用户是否有某项权限

例如：

$user = new WP_User( 22 );
$user->add_cap( 'can_edit_posts', false );
if ( $user->has_cap( 'can_edit_posts') ){
	echo "用户有can_edit_posts权限";
} else {
	echo "没有can_edit_posts权限";
}

在增加权限时，add_cap()第二个参数设为false，所以程序运行结果是 “没有can_edit_posts权限”。

WP_User::get_site_id()

查询当前用户权限属于哪个站点，返回这个站点的ID。multisite下用户在每个子站可能有不同的权限。

如何获取多个用户

class WP_User用于操作一个用户，要获取多个用户就要借助 class WP_User_Query，或者在它基础上工作的get_users()。

$args = array(
	'blog_id'      => $GLOBALS['blog_id'],
	'role'         => '',
	'role__in'     => array(),
	'role__not_in' => array(),
	'meta_key'     => '',
	'meta_value'   => '',
	'meta_compare' => '',
	'meta_query'   => array(),
	'date_query'   => array(),        
	'include'      => array(),
	'exclude'      => array(),
	'orderby'      => 'login',
	'order'        => 'ASC',
	'offset'       => '',
	'search'       => '',
	'number'       => '',
	'count_total'  => false,
	'fields'       => 'all',
	'who'          => '',
 ); 
get_users( $args );

具体请参考文档：

https://codex.wordpress.org/Function_Reference/get_users
https://codex.wordpress.org/Class_Reference/WP_User_Query

操作用户的常用函数

获取当前用户或指定用户的信息

获取当前用户信息不需要指定ID，要获取某个用户的信息，需要指定ID或者其他字段，方法如下：

$user = wp_get_current_user(); //获取当前登录用户信息
$user_by_id = get_userdata(1); //获取指定用户ID的用户信息
$user_by_field = get_user_by('email', 'useremail@email.com'); //根据email获取用户信息

这三个函数的返回值都是WP_User的实例，这样就能用WP_User的方法来操作了，例如：

$user = wp_get_current_user(); //获取当前登录用户信息

if( is_a($user,'WP_User') ){
	// 获取用户基本信息
	$user_id          = $user->get('ID');               //用户ID
	$user_email       = $user->get('user_email');       //用户注册使用的电子邮箱
	$user_login       = $user->get('user_login');       //用户的登录名
	$user_pass        = $user->get('user_pass');        //用户的登录密码（加密后的）
	$user_nicename    = $user->get('user_nicename');    //用户的nicename
	$user_displayname = $user->get('display_name');     //用户的显示名称
	$user_url         = $user->get('user_url');         //用户的网站地址
	$user_registered  = $user->get('user_registered');  //用户的注册时间
	$user_description = $user->get('description');      //用户的个人描述

	// 获取用户角色
	if( in_array( 'administrator', $user->roles ) ){
		echo '该用户是管理员';
	}
}

获取当前登录用户的ID

$current_user_id = get_current_user_id();

快速获取用户字段或usermeta信息

如果不需要获取所有的用户信息，而仅仅获取某个字段的信息，可以使用操作metadata的快捷函数。注意update操作只能更改usermeta信息，wp_users表里的字段不能用update_user_option更新。

$user_id = 1;

// 获取wp_users表里的字段，或者wp_usermeta表里的字段
// 不指定第二个参数（用户ID），则默认获取当前登录用户的字段
$user_email = get_user_option('user_email');
$user_meta = get_user_option('user_meta_key', $user_id);

// 更新字段
update_user_option( $user_id,'user_meta_key','meta信息123');
$updated_value = get_user_option('user_meta_key',$user_id);

// 删除字段
delete_user_option( $user_id, 'user_meta_key' );

用户列表——下拉菜单

使用wp_dropdown_users($args)函数可以显示一个用户下拉菜单，默认显示所有用户。例如，显示一个只有contributor用户的列表。

$contributors = get_users(array(
	'role' => 'Contributor',
	'fields' => 'ID'
));

if( is_array($contributors) && sizeof($contributors) ){
	wp_dropdown_users(array(
		'show_option_all' => '选择用户',
		'include' => implode(',', $contributors)
	));
}

判断用户是否存在

有两个函数可以判断用户是否存在。

$exists_by_username = username_exists('username'); //存在则返回用户ID，不存在返回false
$exists_by_email = email_exists('useremail@email.com'); //存在则返回用户ID，不存在返回false

用代码创建新用户

快速创建一个用户，只提供用户名、密码和邮箱，应该使用wp_create_user()。

$new_user_id = wp_create_user( 'username', 'password', 'useremail@emaio.com');

如果想写入更详细的信息，需要使用wp_insert_user()，该函数是wp_create_user()的基础。

$userdata = array(
	'user_login'    => 'username3',
	'user_pass'     => wp_generate_password( 12, true,true),
	'user_nicename' => 'nicename',
	'user_email'    => 'email3@email.com',
	'user_url'      => 'https://url.com',
	'role'          => 'editor'
);
$new_user_id = wp_insert_user($userdata);
if( ! is_wp_error($new_user_id) ){
	echo '用户创建成功，用户ID为:', $new_user_id;
} else {
	echo $new_user_id->get_error_message();
}

将当前用户登出

使用wp_logout()函数。