wordpress用户角色和权限函数注解

这将是一个分为三篇文章的一个系列，话题覆盖了 WordPress 用户，角色以及权限。这个系列会讨论到 WordPress 的用户结构和用户角色的设计；突出与用户的交互和角色能力管理这两个最重要的功能；在最后的一篇文章当中，我们将会建立一个现实的例子来验证一下。

介绍

在上一篇文章《WordPress 用户角色与权限：基本篇》里面，我们谈到了关于用户，用户角色和权限的相关理论。这一篇文章将会把注意力集中在 WordPress 中用来和这个“角色和权限系统”交互的代码和函数。当然，我并不打算在这篇文章里涉及所有的函数，但是我会尽量去讲一些最重要最有用的东西。

由于 WordPress 经常更新和改动，所以你应该经常去 Codex 里面看看是否有变更。为了给大家提供更多的便利，本文中我会在每个涉及到的函数后面添加一个 Codex 的链接。

用户管理

在 WordPress 里面，用户和访客是不同的概念。用户是在你的网站是注册，有自己的用户名的人群。你可以在设置面板里开启允许新用户注册的功能，在“会员”里把“允许所有用户注册”的勾打上就可以了。

在这一节里面，我们会涉及到 WordPress 里面一些与注册用户交互的重要函数。全新安装的 WordPress 应该至少有一个用户：即安装 WordPress 的那个。在旧版本里面，该用户的名字只能是“管理员”，而现在你可以在安装的时候自定义一个名字了。

1. 创建一个用户，升级和删除用户

WordPress 有一个可视化界面来创建，升级和删除用户。你应该大部分时间都用这种方式。但是也有一些情况是你想要通过代码的方式来解决的：例如，当你把用户从另外一个平台导入的时候，或者是自己设计注册表格的时候。

WordPress 有四个函数了完成这些活动：

• wp_create_user
• wp_insert_user
• wp_update_user
• wp_delete_user

一开始坑有一些困扰。前面三个函数都快用来创建新的用户, 而 “wp_insert_user” 和 “wp_update_user” 可以用来升级已经存在的用户。这样设定是有原因的。

有两种方法来创建一个新的用户：

1. 通过通过传递最小的必备信息来创建一个用户（用户名，密码和 email）。在这种情况下，你应该使用 wp_create_user 函数。

2. 通过传递用户数据的数组。在这种情况下，你应该使用 wp_insert_user 函数。这个可以在你增加一个用户之前就可以设置好。

要升级一个存在的用户，你应该使用 wp_update_user 函数。不过，用 wp_insert_user 也是可行的，但这个函数不验证用户密码，所以可能会失败。所以呢，最好还是用最好的工具来做恰当的事情。

下面我会写一些小片段来示范一下每个函数是怎样使用的。如果你需要更多的信息，你可以去 Codex 上找更详细的介绍。

wp_create_user 的用法

add_action( 'init' , 'wpttuts_createuser' );

function wpttuts_createuser() {
    // User Data
    $user_name = 'new_user' ;
    $user_password = 'new_user_password' ;
    $user_email = '[email protected]' ;

    // Create the user
    $user_id = wp_create_user( $user_name , $user_password , $user_email );

    // Checks if the function returned a WP Error Object
    if ( is_wp_error ( $user_id ) ) {
        $user_id ->get_error_message();
    }
    else {
        // user created successfully
    }
}

wp_insert_user 的用法

add_action( 'init' , 'wpttuts_insertuser' );

function wpttuts_insertuser() {
    // Prepare the user data
    $user_data = array (
        'user_login' => 'new_user' ,
        'user_password' => 'new_user_password'
        'user_email' => '[email protected]' ,
        'role' => 'administrator'
    );

    // Create the user
    $user_id = wp_insert_user( $user_data );

    // Checks if the function returned a WP Error Object
    if ( is_wp_error( $user_id ) ) {
        $user_id ->get_error_message();
    }
    else {
        // user created successfully
    }
}

wp_update_user 的用法

add_action( 'init' , 'wpttuts_updateuser' );

function wpttuts_updateuser() {

    // Prepare the user data
    $user_data = array (
        'user_id' => 3,
        'description' => ' Our newly created user'
    );

    // Updates the user description
    $user_id = wp_update_user( $user_data );

    // Checks if the function returned a WP Error Object
    if ( is_wp_error( $user_id ) ) {
        $user_id ->get_error_message();
    }
    else {
        // user updated successfully
    }
}

wp_delete_user 的用法

add_action( 'init' , 'wpttuts_deleteuser' );

function wpttuts_deleteuser() {
    if ( wp_delete_user( 3, 1 ) ) {
        // User removed successfully
    }
}

2. 如何得到用户列表

WordPress 给用户提供了两个函数来请求用户列表，所以你可以不用去询问数据库。第一个函数是 “get_users_of_blog()” ,这个函数返回一个该博客所有用户的数组（如果你运行的是多站点的话，或者你可以通过传递一个 blog ID来获得）。第二个函数是 “get_users()”,返回的是一个用户列表，这个列表是基于传递到该函数的参数来做到的。这就减少了很多到数据库的SQL请求。

两个函数都会返回用户数据目标的数组。（除了 get_users() 这个函数，用它可以返回一个特定的字段。 ）下一节我们会涉及更多关于用户目标的细节。

“get_users_of_blog()” 函数其实现在已经被弃用了。所以现在已经没有必要去用了，应该用 “get_users()” 来代替，下面给大家举一个例子：

add_action( 'init' , 'wpttuts_getusers' );

function wpttuts_getusers() {
    // Query criteria
    $args = array (
        'orderby' => 'url' ,
        'order' => 'ASC'
    );

    // Get the users array
    $users = get_users( $args );

    // Loop through users, and display their home page
    foreach ( $users as $user ) {
        echo '<a href="' . $user ->user_url . '">' . $user ->user_url . '</a>' ;
    }
}

这个函数元素有更多的选项。你可以在 Codex 页面里面找到一个完整的介绍。Codex page

• blog_id 这个只在多站点才有效。默认值是现在博客的ID。
• role 限制特定角色的返回用户。
• include 一个用户ID的数组，接受请求返回值。
• exclude 一个用户ID的数组，排除请求返回值。

3.WP_User 类别

WP_User 分类允许访问特定用户的内容，权限等。你需要一个用户ID、或者是用户名来创建一个新的类别；如果你是多站点，你同样需要一个 blog ID。

你可以给一个特定的用户初始化类别，然后把类别的内容 dump 给他。这只会显示内容本身，如果你需要得到用户类别里面的东西，这就会很有用。

add_action( 'init' , 'wptuts_wpuserclass' );

function wptuts_wpuserclass() {
    $user = new WP_User( 1 );
    var_dump( $user );
}

下面的将是 WP_User 分类的属性和规则的一个总结：

WP_User 属性

• data （用户数据的目标，例如用户名，密码，URL...）
• ID （完整的用户 ID）
• caps （数组）
• roles （分配给用户的角色数组）
• cap_key （字符串）
• allcaps （包含用户所有属性的数组）
• filter （空值）

WP_User 的规则

• get_role_caps() 设定用户角色和所有用户的属性。
• add_role() 给用户添加一个角色。
• remove_role() 给用户去掉一个角色。
• set_role() 给用户设定一个角色。这会去除前一个设定的角色。
• add_cap() 给用户增加能力。
• remove_cap() 去除用户的能力。
• remove_all_caps() 去除用户的所有能力。
• has_cap() 检查用户是否有某种权限或者角色。

4. 用户的 Meta-Data

我们在前一篇文章就提到过，用户的 meta-data 是储存在 wp_usermeta 表的。是以密钥或者是一对值来储存的。而 Meta 值可以为任何一种形式的数据。这一对值不一定要是唯一的。你可以储存几对同样的值。

添加用户的Meta-Data

函数 add_user_meta() 是用来添加新的用户 metadata。如果成功添加的话，函数就会返回一个True,如果失败的话就会返回false。如之前提到的，是允许添加多个有相同值的meta数据的。如果你想让每个meta值都是唯一的话，那就把一下四个参数设为 true。

add_action( 'init' , 'wptuts_addusermeta' );

function wptuts_addusermeta() {
    // Add multiple meta values with the same meta key
    add_user_meta( 1, 'bookmarks' , 'http://site1.com' , false );
    add_user_meta( 1, 'bookmarks' , 'http://site2.com' , false );
    add_user_meta( 1, 'bookmarks' , 'http://site3.com' , false );
}

检索用户的 Meta-Data

函数 get_user_meta() 会返回一个 meta 值，这个值是基于用户的ID而传递给他的meta key。

add_action( 'init' , 'wptuts_getusermeta' );

function wptuts_getusermeta() {
    // Retrieves the user bookmarks
    $bookmarks = get_user_meta( 1, 'bookmarks' , false );
    echo '<ul>' ;
    foreach ( $bookmarks as $bookmark ) {
        echo '<li><a href="' . $bookmark . '">' . $bookmark . '</a></li>' ;
    }
    echo '</ul>' ;
}

升级用户的 Meta-Data

函数 update_user_meta() 是用来升级单个的 meta 值的，如果同样的 meta key 有多个不同的值，之前也没有分配特定的值，那么新的值就会把久的那个值给覆盖掉。

add_action( 'init' , 'wptuts_updateusermeta' );

function wptuts_updateusermeta() {
    // Updates a user bookmark
    update_user_meta( 1, 'bookmarks' , 'https://site2.com' , 'http://site2.com' );
}

去除用户的 Meta-Data

delete_user_data() 这个函数是用了去除单个或者是多个已经存在的 meta 键值。如果你想要删除单个值的话，你应该在第三个参数上标注出来。

add_action( 'init' , 'wptuts_removeusermeta' );

function wptuts_removeusermeta() {
    // Updates a user bookmark
    delete_user_meta( 1, 'bookmarks' , 'https://site2.com' );
}

管理用户角色和权限

1. 创建和删除用户角色

WordPress 用户角色具有可扩展的特点。你可以添加或者是删除一个角色，添加一个角色很简单，你只需要一个角色的标签名字，一个显示名字，然后再加上用户权限就够了。

add_action( 'init' , 'wptuts_addrole' );

function wptuts_addrole() {
    add_role( 'uploader' , 'Uploader' , array ( 'upload_files' ) );
    add_role( 'link_manager' , 'Link Manager' , array ( 'manage_links' ) );
}

如果你检查用户设置页面，（选择一个用户进入编辑模式），你就会发现你新添加的一个角色已经可用了。它是以你拟定的显示名称出现在屏幕上的。

有一件事必须提醒一下，用户角色的创建只要做一次就好了。也就是说，如果你像上面给出的代码那样，挂钩到 “init” 动作，你其实就在重新创建一个用户角色了。没运行一次，就重建一次。这并不是什么好事情。在实际运用中，你只需要一次性把用户角色创建完就可以了。然后你就可以挂钩到到插件的激活钩子，以确保当禁用插件的时候可以去除该角色。

去除用户角色也是很直接的事情，你只需要用到角色的标签名字。

add_action( 'init' , 'wptuts_removerole' );

function wptuts_removerole() {
    remove_role( 'uploader' );
    remove_role( 'link_manager' );
}

2. 给用户角色添加权限

和用户一样，用户角色也有一个特定的类别：WP_Role。但是，初始化这个类别需要用到角色名称和角色的权限，

WordPress 还提供了另外一个函数 get_role() ，这个函数只需要角色名字和你的初始化类别。

add_action( 'init' , 'wptuts_getrole' );

function wptuts_getrole() {
    $role = get_role( 'editor' );
    var_dump( $role );
}

返回的目标有两个属性和三个规则

WP_Role 属性
• capabilities 一个表示用户权限的数组。
• name 角色名字

  WP_Role 规则

• add_cap() 添加权限到用户角色目标值。
• has_cap() 适合用户是否具有某种权限。
• remove_cap() 去除角色的权限。

3. 检查权限

设定好的用户角色和权限，如果你不用，就只是个摆设而已。你应该强制在你的插件和主题上使用，在执行代码之前先检查一下。你应该总是检查权限，而不是角色。一个角色为“编辑”的用户不能保证一直都是 WordPress 默认的权限，因为这是可以被别的插件或者是博客主修改的。

WordPress 上有三个函数用来检查权限，而这三个函数在某种程度上来说是可以替换的。

• current_user_can()
• user_can()
• author_can()

current_user_can() 这个函数是用来检查目前用户是否有特定的权限的。也允许一个帖子或者是目标检查 meta 权限。

user_can() 差不多是和上面一样用的，但是你可以指定特定的ID。但是这个函数不会检查 meta 权限。所以如果你需要检查一个用户的 meta 权限和现在的用户是不是一样，那就不好用了。为了达到这个目的，你可以使用 author_can() 函数来检查，看看基于某个权限和 post ID 的用户是否可以完成特定的项目。

// checks if the post author of the first post can publish the post
if ( author_can( 1, 'publish_posts' ) ) {
    publish_post_function(); // publish the post
}
else {
    echo "You don't have the right to publish the post" ;
}

结语

在这一篇文章里，我尽量全面的涉及 WordPress 有的函数，而且每个需要用到的函数都解释了一番。现在，你应该可以用到权限系统来创建一个插件或者主题了。在下一篇文章里，我将会展示一下如何在实际环境下用这个系统来开发一个插件。