深入理解 `add_cap()` 和 `remove_cap()` 函数的源码，它们如何动态地修改用户角色的权限。

各位观众老爷，晚上好！今天咱们不聊风花雪月，来点硬核的，聊聊WordPress里那些“偷偷摸摸”修改用户权限的小秘密——add_cap() 和 remove_cap()。保证让你听完之后，感觉自己也能在WordPress的权限系统里呼风唤雨！

一、权限管理：谁说了算？

在WordPress的世界里，权限就像一把把钥匙，决定着你能打开哪些门，做哪些事情。比如说，你是“管理员”，就能管理整个网站；你是“编辑”，就能写文章、改文章；你是“作者”，只能写自己的文章。这些都是通过权限来控制的。

WordPress的权限系统核心就是Capability（能力）。每个Capability代表着一种特定的操作，比如edit_posts（编辑文章）、manage_options（管理选项）等等。用户角色（Role）则是一组Capability的集合。

我们可以把用户角色想象成一个角色扮演游戏里的职业，比如“战士”、“法师”、“盗贼”。每个职业都有自己擅长的技能（Capability），也就是他们可以做的事情。

二、add_cap() 和 remove_cap()：权限修改的利器

add_cap() 和 remove_cap() 这两个函数，就像是权限系统的“手术刀”，它们可以精确地为某个角色添加或删除特定的Capability。

• add_cap( string $role, string $cap, bool $grant = true )：给角色 $role 添加能力 $cap。$grant 默认为 true，表示授予权限；如果设置为 false，实际上不会授予权限，但会影响一些权限检查的逻辑（后面会讲到）。
• remove_cap( string $role, string $cap )：从角色 $role 移除能力 $cap。

这两个函数在实际开发中非常有用。比如说，你想给“编辑”角色添加一个可以管理分类目录的权限，就可以使用add_cap()；如果你想阻止“作者”删除文章，就可以使用remove_cap()。

三、源码剖析：深入了解工作原理

要真正理解add_cap() 和 remove_cap()，光知道怎么用还不够，得深入源码，看看它们到底是怎么“动手术”的。

// add_cap() 函数的简化版
function add_cap( $role, $cap, $grant = true ) {
    global $wp_roles;

    if ( ! isset( $wp_roles ) ) {
        $wp_roles = new WP_Roles();
    }

    $wp_roles->add_cap( $role, $cap, $grant );
}

// remove_cap() 函数的简化版
function remove_cap( $role, $cap ) {
    global $wp_roles;

    if ( ! isset( $wp_roles ) ) {
        $wp_roles = new WP_Roles();
    }

    $wp_roles->remove_cap( $role, $cap );
}

可以看到，这两个函数实际上只是调用了WP_Roles类中的add_cap() 和 remove_cap() 方法。WP_Roles 类才是真正负责管理角色和权限的核心。

下面我们再来看看 WP_Roles 类中的这两个方法：

// WP_Roles::add_cap() 方法
public function add_cap( $role, $cap, $grant = true ) {
    if ( isset( $this->roles[ $role ] ) ) {
        $this->roles[ $role ]['capabilities'][ $cap ] = $grant;
        $this->update_role( $role );
    }
}

// WP_Roles::remove_cap() 方法
public function remove_cap( $role, $cap ) {
    if ( isset( $this->roles[ $role ] ) ) {
        unset( $this->roles[ $role ]['capabilities'][ $cap ] );
        $this->update_role( $role );
    }
}

从源码可以看出，add_cap() 和 remove_cap() 的核心操作就是修改 $wp_roles->roles 数组。这个数组保存了所有角色和它们的 Capability。

• $wp_roles->roles 是一个多维数组，第一层键是角色名（比如 ‘administrator’、’editor’），第二层键是 ‘capabilities’，对应的值又是一个数组，这个数组的键是 Capability 名（比如 ‘edit_posts’、’manage_options’），值是布尔值（true 或 false），表示该角色是否拥有这个 Capability。

• add_cap() 就是在 $wp_roles->roles[$role]['capabilities'] 数组中添加或修改一个键值对。

• remove_cap() 就是从 $wp_roles->roles[$role]['capabilities'] 数组中删除一个键。

修改完 $wp_roles->roles 数组后，还会调用 $this->update_role( $role ) 方法，将修改后的角色信息保存到数据库中。

四、数据库存储：权限的“户口本”

那么，角色和权限的信息到底保存在数据库的哪个地方呢？答案是 wp_options 表。

WordPress会将 $wp_roles->roles 数组序列化后，存储在 wp_options 表中，option_name 为 wp_user_roles 的 option_value 里。

我们可以通过以下代码来查看：

global $wpdb;
$roles = $wpdb->get_var( "SELECT option_value FROM {$wpdb->options} WHERE option_name = 'wp_user_roles'" );
$roles = unserialize( $roles );
echo '<pre>';
print_r( $roles );
echo '</pre>';

这段代码会从数据库中取出 wp_user_roles 的值，反序列化后，打印出 $wp_roles->roles 数组的内容。

五、权限检查：谁说了算，还得看看能不能做到

光有权限还不行，还得能用才行。WordPress在很多地方都会进行权限检查，判断当前用户是否拥有执行某个操作的权限。

常用的权限检查函数是 current_user_can()。

// 检查当前用户是否拥有 'edit_posts' 权限
if ( current_user_can( 'edit_posts' ) ) {
    // 用户可以编辑文章
    echo '你可以编辑文章！';
} else {
    // 用户不能编辑文章
    echo '你没有权限编辑文章！';
}

current_user_can() 函数会根据当前用户的角色和 Capability，判断用户是否拥有指定的权限。

current_user_can() 函数内部的逻辑比较复杂，涉及到很多钩子和过滤器的调用。但核心思想是：

1. 获取当前用户的角色。
2. 获取角色拥有的所有 Capability。
3. 判断角色是否拥有指定的 Capability。
4. 如果角色没有指定的 Capability，还会检查是否存在 implied Capability（隐含的 Capability）。比如，edit_others_posts 隐含了 edit_posts 权限。

六、实战演练：修改权限的正确姿势

理论讲了一大堆，现在来点实际的。下面我们来演示几个修改权限的例子。

1. 给“编辑”角色添加管理分类目录的权限：

function add_category_management_capability_to_editor() {
    $role = get_role( 'editor' );
    if ( ! empty( $role ) ) {
        $role->add_cap( 'manage_categories' );
    }
}
add_action( 'init', 'add_category_management_capability_to_editor' );

这段代码会在 WordPress 初始化时，获取“编辑”角色，并添加 manage_categories 权限。

2. 阻止“作者”删除文章：

function remove_delete_posts_capability_from_author() {
    $role = get_role( 'author' );
    if ( ! empty( $role ) ) {
        $role->remove_cap( 'delete_posts' );
    }
}
add_action( 'init', 'remove_delete_posts_capability_from_author' );

这段代码会在 WordPress 初始化时，获取“作者”角色，并移除 delete_posts 权限。

3. 创建自定义角色并赋予权限：

function create_custom_role() {
    add_role(
        'book_reviewer',
        '图书评论员',
        array(
            'read'         => true,  // 可以阅读
            'edit_posts'   => false, // 不能编辑文章
            'upload_files' => true,  // 可以上传文件
            'review_books' => true,  // 自定义权限，用于评论图书
        )
    );
}
add_action( 'init', 'create_custom_role' );

// 自定义权限检查示例
function check_book_review_permission() {
    if ( current_user_can( 'review_books' ) ) {
        echo '你可以评论图书！';
    } else {
        echo '你没有权限评论图书！';
    }
}

这段代码会创建一个名为“图书评论员”的自定义角色，并赋予一些基本权限，以及一个自定义的 review_books 权限。

七、注意事项：修改权限的“坑”

修改权限虽然强大，但也要小心谨慎，一不小心就会掉进“坑”里。

1. 不要直接修改数据库： 永远不要直接修改 wp_options 表中的 wp_user_roles 值。因为 WordPress 会缓存角色信息，直接修改数据库可能会导致数据不一致。

2. 使用 init 钩子： 修改权限的代码应该放在 init 钩子中执行，确保在 WordPress 初始化完成后再进行修改。

3. 考虑插件冲突： 很多插件也会修改权限，要注意插件之间的冲突。

4. 谨慎移除权限： 移除权限可能会影响用户体验，要谨慎操作。

5. 了解 implied Capability： 有些 Capability 是隐含的，比如 edit_others_posts 隐含了 edit_posts 权限。移除 edit_others_posts 权限后，edit_posts 权限仍然可能存在。

6. 关于 $grant = false 的特殊用法: 在 add_cap() 中，如果 $grant 设置为 false，它不会直接授予权限，但会影响 current_user_can() 的行为。 一些插件或者主题可能会使用 current_user_can( 'some_cap' ) 来检查用户是否明确被禁止了某个权限。 如果 $role 没有 some_cap，current_user_can() 会返回 false；如果 $role 有 some_cap => false，current_user_can() 也会返回 false，但它们的原因不同。 前者是因为没有权限，后者是因为明确禁止了权限。 这在某些情况下可以用来实现更细粒度的权限控制。

八、总结：权限管理，任你掌控

今天我们深入了解了 WordPress 的权限系统，学习了 add_cap() 和 remove_cap() 函数的源码和使用方法。希望大家能够灵活运用这些知识，打造一个安全、可控的 WordPress 网站。

总而言之，权限管理就像搭积木，add_cap() 和 remove_cap() 就是你手中的积木块，只要掌握了它们的用法，就能搭建出各种各样的权限模型。希望今天的讲座能让你对 WordPress 的权限系统有更深入的理解，成为一个真正的权限管理大师！

权限相关函数和类概览表

函数/类	描述
add_cap()	给角色添加 Capability。
remove_cap()	从角色移除 Capability。
get_role()	获取指定角色的 WP_Role 对象。
add_role()	创建新的角色。
remove_role()	移除角色。 注意：移除角色前，确保没有用户使用该角色，否则会导致用户权限问题。
WP_Roles	WordPress 的角色管理类，负责管理所有角色和 Capability。
WP_Role	WordPress 的角色类，代表一个具体的角色，包含角色名和 Capability 列表。
current_user_can()	检查当前用户是否拥有指定 Capability。
map_meta_cap()	将抽象 Capability 映射到具体的 Capability。例如，edit_post 映射到 edit_posts 或 edit_others_posts，取决于当前用户是否是文章作者。
get_users_with_cap()	获取拥有指定 Capability 的所有用户。

现在，各位还有什么问题吗？尽管提，我保证知无不言，言无不尽！ （除非涉及到我不知道的…… 那就只能说抱歉啦！）