深入解读 WordPress `WP_Roles` 类源码：角色与权限的存储与管理机制。

各位观众老爷们，大家好！今天咱们来聊聊WordPress里一个相当重要的角色——WP_Roles类。这玩意儿就像是WordPress王国里的人事部部长，负责管理各种角色的权限，决定谁能干什么，谁不能干什么。

咱们的目标是：扒开WP_Roles类的源码，看看它到底是如何存储和管理角色与权限的。争取让大家看完之后，下次再遇到权限问题，不用挠头，直接上手改代码！

一、WP_Roles：WordPress权限体系的核心

在WordPress中，每个用户都被赋予一个角色（Role）。角色决定了用户在网站上能做什么。比如，管理员（Administrator）可以做任何事，而订阅者（Subscriber）只能看文章。

WP_Roles类是用来管理这些角色的。它负责：

• 存储所有已定义的角色及其权限。
• 添加新的角色。
• 删除角色。
• 给角色添加或移除权限。
• 判断用户是否拥有某个权限。

可以把 WP_Roles 看作一个关联数组，键是角色名称，值是该角色拥有的权限列表。

二、源码剖析：深入WP_Roles的骨髓

WP_Roles类位于wp-includes/class-wp-roles.php文件中。咱们一点点把它拆开来看看。

1. 构造函数 __construct()

这是WP_Roles类的入口，负责初始化角色数据。

public function __construct() {
    global $wpdb;

    $this->roles = get_option( 'wp_user_roles' );

    if ( empty( $this->roles ) ) {
        $this->init_roles();
    }

    if ( is_array( $this->roles ) ) {
        $this->role_objects = array();
        $this->role_names   = array();

        foreach ( $this->roles as $name => $details ) {
            $this->role_objects[ $name ] = new WP_Role( $name, $details['capabilities'] );
            $this->role_names[ $name ]   = isset( $details['name'] ) ? $details['name'] : $name;
        }
    }

    /**
     * Fires after the WP_Roles instance is completely initialized.
     *
     * @since 2.3.0
     *
     * @param WP_Roles &$this WP_Roles instance.
     */
    do_action_ref_array( 'wp_roles_init', array( &$this ) );
}

这段代码主要做了几件事：

• 从数据库加载角色数据： 使用get_option( 'wp_user_roles' )从数据库中获取存储的角色数据。这些数据以数组形式存储，键是角色名称，值是角色详细信息（包括权限列表）。
• 初始化角色： 如果数据库中没有角色数据（第一次安装WordPress时），调用init_roles()方法初始化默认角色（管理员、编辑、作者、贡献者、订阅者）。
• 创建WP_Role对象： 遍历角色数据，为每个角色创建一个WP_Role对象。WP_Role类负责处理单个角色的权限管理。
• 触发wp_roles_init钩子： 允许插件和主题在WP_Roles类初始化完成后执行一些自定义操作。

2. 初始化默认角色 init_roles()

如果没有从数据库获取到角色，init_roles() 会初始化五个默认角色。

public function init_roles() {
    if ( ! isset( $this->roles ) ) {
        $this->roles = array();
    }

    $this->add_role( 'administrator', __( 'Administrator' ), array(
        'switch_themes'          => true,
        'edit_themes'            => true,
        'activate_plugins'       => true,
        'edit_plugins'           => true,
        'edit_users'             => true,
        'create_users'           => true,
        'delete_users'           => true,
        'import'                 => true,
        'unfiltered_html'        => true,
        'manage_options'         => true,
        'read'                   => true,
        'edit_posts'             => true,
        'delete_posts'           => true,
        'publish_posts'          => true,
        'edit_pages'             => true,
        'read_private_pages'     => true,
        'read_private_posts'     => true,
        'delete_pages'           => true,
        'publish_pages'          => true,
        'upload_files'           => true,
        'manage_categories'      => true,
        'moderate_comments'      => true,
        'manage_links'           => true,
        'edit_others_posts'      => true,
        'delete_others_posts'    => true,
        'read_private_posts'     => true,
        'read_private_pages'     => true,
        'edit_private_posts'     => true,
        'edit_private_pages'     => true,
        'delete_private_posts'   => true,
        'delete_private_pages'   => true,
        'delete_published_posts' => true,
        'edit_published_posts'   => true,
        'approve_comments'       => true,
        'export'                 => true,
        'delete_published_pages' => true,
        'edit_published_pages'   => true,
        'delete_others_pages'    => true,
        'edit_others_pages'      => true,
        'unfiltered_upload'      => true,
        'install_plugins'        => true,
        'update_plugins'         => true,
        'delete_plugins'         => true,
        'install_themes'         => true,
        'update_themes'          => true,
        'delete_themes'          => true,
        'update_core'            => true,
        'list_users'             => true,
        'remove_users'           => true,
        'add_users'              => true,
        'promote_users'          => true,
        'edit_theme_options'     => true,
        'delete_site'            => true,
        'create_sites'           => true,
        'manage_network'         => true,
        'manage_sites'           => true,
        'upload_plugins'         => true,
        'upload_themes'          => true
    ) );

    $this->add_role( 'editor', __( 'Editor' ), array(
        'moderate_comments'       => true,
        'manage_categories'      => true,
        'manage_links'           => true,
        'upload_files'            => true,
        'edit_posts'              => true,
        'edit_others_posts'       => true,
        'delete_posts'            => true,
        'delete_others_posts'     => true,
        'publish_posts'           => true,
        'read_private_posts'      => true,
        'edit_pages'              => true,
        'read_private_pages'      => true,
        'publish_pages'           => true,
        'delete_pages'            => true,
        'delete_private_pages'    => true,
        'delete_published_pages'  => true,
        'edit_private_pages'      => true,
        'edit_published_pages'    => true,
        'unfiltered_html'         => true,
        'approve_comments'        => true
    ) );

    $this->add_role( 'author', __( 'Author' ), array(
        'upload_files'    => true,
        'edit_posts'      => true,
        'delete_posts'    => true,
        'publish_posts'   => true,
        'read'            => true
    ) );

    $this->add_role( 'contributor', __( 'Contributor' ), array(
        'edit_posts'    => true,
        'delete_posts'  => true,
        'read'          => true
    ) );

    $this->add_role( 'subscriber', __( 'Subscriber' ), array(
        'read'    => true
    ) );

    update_option( 'wp_user_roles', $this->roles );
}

这里可以看到，init_roles() 方法调用了 add_role() 方法来创建角色，并为每个角色分配了相应的权限。最后，它使用 update_option() 将角色数据保存到数据库中。

3. 添加角色 add_role()

add_role() 方法用于添加一个新的角色。

public function add_role( $role, $display_name, $capabilities = array() ) {
    if ( isset( $this->roles[ $role ] ) ) {
        return;
    }

    $this->roles[ $role ] = array(
        'name'         => $display_name,
        'capabilities' => $capabilities,
    );

    $this->role_objects[ $role ] = new WP_Role( $role, $capabilities );
    $this->role_names[ $role ]   = $display_name;

    update_option( 'wp_user_roles', $this->roles );

    /**
     * Fires after a role is added.
     *
     * @since 2.0.0
     *
     * @param string $role         Role name.
     * @param string $display_name Role display name.
     * @param array  $capabilities List of role capabilities.
     */
    do_action( 'add_role', $role, $display_name, $capabilities );
}

这个方法接收三个参数：

• $role：角色名称（字符串，唯一标识符）。
• $display_name：角色显示名称（字符串，用于在后台显示）。
• $capabilities：角色权限列表（数组，键值对，键是权限名称，值通常是 true）。

add_role() 的主要步骤：

• 检查角色是否已存在： 如果角色已经存在，直接返回，避免重复添加。
• 添加到 $this->roles 数组： 将角色信息添加到 $this->roles 数组中。
• 创建 WP_Role 对象： 为新角色创建一个 WP_Role 对象。
• 更新数据库： 使用 update_option() 将更新后的角色数据保存到数据库。
• 触发 add_role 钩子： 允许插件和主题在角色添加完成后执行一些自定义操作。

4. 移除角色 remove_role()

remove_role() 方法用于删除一个角色。

public function remove_role( $role ) {
    if ( ! isset( $this->roles[ $role ] ) ) {
        return;
    }

    unset( $this->roles[ $role ] );
    unset( $this->role_objects[ $role ] );
    unset( $this->role_names[ $role ] );

    update_option( 'wp_user_roles', $this->roles );

    /**
     * Fires after a role is removed.
     *
     * @since 2.0.0
     *
     * @param string $role Role name.
     */
    do_action( 'remove_role', $role );
}

这个方法接收一个参数：

• $role：要删除的角色名称（字符串）。

remove_role() 的主要步骤：

• 检查角色是否存在： 如果角色不存在，直接返回。
• 从 $this->roles 数组中删除： 将角色从 $this->roles 数组中移除。
• 从 $this->role_objects 和 $this->role_names 数组中删除： 删除相关的 WP_Role 对象和角色名称。
• 更新数据库： 使用 update_option() 将更新后的角色数据保存到数据库。
• 触发 remove_role 钩子： 允许插件和主题在角色删除完成后执行一些自定义操作。

5. 获取角色对象 get_role()

get_role() 方法用于获取一个角色的 WP_Role 对象。

public function get_role( $role ) {
    if ( isset( $this->role_objects[ $role ] ) ) {
        return $this->role_objects[ $role ];
    }

    return null;
}

这个方法接收一个参数：

• $role：要获取的角色的名称（字符串）。

get_role() 的主要步骤：

• 检查角色对象是否存在： 如果 $this->role_objects 数组中存在该角色的 WP_Role 对象，则直接返回该对象。
• 返回 null： 如果角色对象不存在，则返回 null。

6. 获取所有角色 get_names()

get_names() 方法用于获取所有角色的显示名称。

public function get_names() {
    return $this->role_names;
}

这个方法直接返回 $this->role_names 数组，该数组包含了所有角色的显示名称。

三、WP_Role：单个角色的权限管理

WP_Role 类负责处理单个角色的权限管理。它位于 wp-includes/class-wp-role.php 文件中。

1. 构造函数 __construct()

public function __construct( $role, $capabilities ) {
    $this->name         = $role;
    $this->capabilities = $capabilities;
}

构造函数接收两个参数：

• $role：角色名称（字符串）。
• $capabilities：角色权限列表（数组）。

构造函数会将角色名称和权限列表赋值给 $this->name 和 $this->capabilities 属性。

2. 添加权限 add_cap()

add_cap() 方法用于给角色添加一个权限。

public function add_cap( $cap, $grant = true ) {
    $this->capabilities[ $cap ] = $grant;
    $this->update_role();
}

这个方法接收两个参数：

• $cap：要添加的权限名称（字符串）。
• $grant：是否授予该权限（布尔值，默认为 true）。

add_cap() 的主要步骤：

• 添加到 $this->capabilities 数组： 将权限添加到 $this->capabilities 数组中。
• 更新角色： 调用 update_role() 方法更新数据库中的角色数据。

3. 移除权限 remove_cap()

remove_cap() 方法用于移除角色的一个权限。

public function remove_cap( $cap ) {
    unset( $this->capabilities[ $cap ] );
    $this->update_role();
}

这个方法接收一个参数：

• $cap：要移除的权限名称（字符串）。

remove_cap() 的主要步骤：

• 从 $this->capabilities 数组中删除： 将权限从 $this->capabilities 数组中移除。
• 更新角色： 调用 update_role() 方法更新数据库中的角色数据。

4. 判断是否拥有权限 has_cap()

has_cap() 方法用于判断角色是否拥有某个权限。

public function has_cap( $cap ) {
    if ( isset( $this->capabilities[ $cap ] ) ) {
        return $this->capabilities[ $cap ];
    }

    return false;
}

这个方法接收一个参数：

• $cap：要判断的权限名称（字符串）。

has_cap() 的主要步骤：

• 检查权限是否存在： 如果 $this->capabilities 数组中存在该权限，则返回该权限的值（true 或 false）。
• 返回 false： 如果权限不存在，则返回 false。

5. 更新角色 update_role()

update_role() 方法用于更新数据库中的角色数据。

private function update_role() {
    global $wp_roles;

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

    $wp_roles->roles[ $this->name ]['capabilities'] = $this->capabilities;

    update_option( 'wp_user_roles', $wp_roles->roles );
}

update_role() 的主要步骤：

• 获取 $wp_roles 对象： 获取全局的 $wp_roles 对象。
• 更新角色数据： 将 $this->capabilities 数组更新到 $wp_roles->roles 数组中。
• 更新数据库： 使用 update_option() 将更新后的角色数据保存到数据库。

四、使用场景示例：自定义角色与权限

现在，咱们通过一个例子来演示如何使用 WP_Roles 类自定义角色和权限。

假设我们要创建一个名为“内容审核员”（Content Reviewer）的角色，该角色可以阅读文章、评论，并审核评论。

function create_content_reviewer_role() {
    $role = 'content_reviewer';
    $display_name = '内容审核员';
    $capabilities = array(
        'read'            => true,
        'moderate_comments' => true,
        'edit_posts' => true, // 允许审核员编辑文章（可选，取决于需求）
    );

    add_role( $role, $display_name, $capabilities );
}
add_action( 'init', 'create_content_reviewer_role' );

这段代码在 WordPress 初始化时（init 钩子）创建了一个名为“内容审核员”的角色，并赋予了阅读文章、审核评论和编辑文章（可选）的权限。

如果要删除这个角色，可以使用以下代码：

function remove_content_reviewer_role() {
    remove_role( 'content_reviewer' );
}
add_action( 'init', 'remove_content_reviewer_role' );

注意，删除角色会删除所有与该角色相关的用户数据，所以要谨慎操作。

五、权限体系的存储方式

WordPress角色和权限数据存储在 wp_options 表中的 wp_user_roles 选项中。这是一个序列化的 PHP 数组。

数据结构大致如下：

array(
    'administrator' => array(
        'name' => 'Administrator',
        'capabilities' => array(
            'switch_themes' => true,
            'edit_themes' => true,
            // ... 其他权限
        ),
    ),
    'editor' => array(
        'name' => 'Editor',
        'capabilities' => array(
            'moderate_comments' => true,
            'manage_categories' => true,
            // ... 其他权限
        ),
    ),
    // ... 其他角色
)

六、总结与建议

WP_Roles 类是 WordPress 权限体系的核心，理解它的源码对于自定义角色和权限至关重要。

在使用 WP_Roles 类时，需要注意以下几点：

• 谨慎操作： 修改角色和权限可能会影响网站的安全性和功能，所以要谨慎操作。
• 使用钩子： 尽量使用 WordPress 提供的钩子来扩展和修改角色和权限，避免直接修改核心代码。
• 了解权限： 熟悉 WordPress 内置的权限，可以更有效地管理用户角色。

七、权限能力表

以下是一个简化的WordPress权限能力表，列出了一些常用的权限及其含义。

Capability	Description
read	允许用户阅读文章。
edit_posts	允许用户编辑自己的文章。
edit_others_posts	允许用户编辑其他用户的文章。
publish_posts	允许用户发布文章。
delete_posts	允许用户删除自己的文章。
delete_others_posts	允许用户删除其他用户的文章。
moderate_comments	允许用户审核评论。
manage_categories	允许用户管理文章分类。
upload_files	允许用户上传文件。
manage_options	允许用户管理网站设置。
install_plugins	允许用户安装插件。（通常只有管理员拥有此权限）
edit_themes	允许用户编辑主题。（通常只有管理员拥有此权限）
create_users	允许用户创建新用户。（通常只有管理员拥有此权限）

八、安全提示

请记住，权限管理是安全的关键环节。不要随意赋予用户过高的权限，这可能会导致安全漏洞。定期审查用户的角色和权限，确保他们只拥有完成工作所需的最小权限集。

好了，今天的讲座就到这里。希望大家通过今天的学习，对 WordPress 的角色与权限管理有了更深入的理解。下次遇到权限问题，就能轻松应对了！ 咱们下回再见！