WordPress功能函数add_role()，如果角色不存在，请添加角色。

参数：

$role

(string) (必需) 角色的名字。

$display_name

(string) (必需) 显示角色的名称。

$capabilities

(bool[]) (可选) 按能力名称键的能力列表，例如array(‘edit_posts’ => true， ‘delete_posts’ => false)。

默认值: array()

返回

(WP_Role|null) 如果添加了role，则为WP_Role对象，如果已经存在，则为空。

来源：

文件: wp-includes/capabilities.php

function add_role( $role, $display_name, $capabilities = array() ) {

if ( empty( $role ) ) {

return;

}

return wp_roles()->add_role( $role, $display_name, $capabilities );

}

更新日志：

用户贡献的笔记

（由Roger Theriault贡献- 2年前）

请确保仅在激活钩子或条件块中使用此函数(和类似的角色函数)。不需要在每次加载页面时都执行它，并且每次调用它时都会更新数据库。

例如，这将存储一个选项来跟踪自定义角色的版本，并且只更新一次数据库:

function xx__update_custom_roles() {

if ( get_option( ‘custom_roles_version’ ) < 1 ) {

add_role( ‘custom_role’, ‘Custom Subscriber’, array( ‘read’ => true, ‘level_0’ => true ) );

update_option( ‘custom_roles_version’, 1 );

}

}

add_action( ‘init’, ‘xx__update_custom_roles’ );

　　（由Jules Colle于1年前贡献）

您还可以根据现有的用户角色轻松地创建新的用户角色。

(等同于WP CLI: WP role create ——clone=)

示例:创建具有Administrator权限的角色“supervisor”

add_role( ‘superintendent’, ‘Superintendent’, get_role( ‘administrator’ )->capabilities );

　　（由Codex – 5年前贡献）

当一个插件被激活时，创建一个新的角色

看到register_activation_hook。

function add_roles_on_plugin_activation() {

add_role( ‘custom_role’, ‘Custom Subscriber’, array( ‘read’ => true, ‘level_0’ => true ) );

}

register_activation_hook( __FILE__, ‘add_roles_on_plugin_activation’ );

　　（由Codex – 5年前贡献）

例子

创建一个新的“客座作者”角色。

$result = add_role(

‘guest_author’,

__( ‘Guest Author’, ‘testdomain’ ),

array(

‘read’ => true, // true allows this capability

‘edit_posts’ => true,

‘delete_posts’ => false, // Use false to explicitly deny

)

);

if ( null !== $result ) {

echo “Success: {$result->name} user role created.”;

}

else {

echo ‘Failure: user role already exists.’;

}

　　（由Codex – 5年前贡献）

注意:什么时候打电话

在尝试添加或修改角色之前，请确保全局$wp_roles可用。最佳实践是使用一个插件(或主题)激活钩子来更改角色(因为您只希望这样做一次!)

mu-plugins加载得太早了，所以如果你在mu-plugin的上下文中这样做的话，可以使用一个action钩子(比如’init’)来封装你的add_role()调用。
　　
　　（由Codex – 5年前贡献）

备注:删除已存在的角色

不能使用add_role()更改现有角色的功能。这个函数将停止执行，如果指定的角色名已经存在，则返回null。

可以通过使用remove_role()，然后使用add_role()来更改用户角色的功能(或显示名称)。

这只是为了发展。一旦确定了功能列表，就不需要保留remove_role()代码。

　　（由Codex – 5年前贡献）

使用

<?php add_role( $role, $display_name, $capabilities ); ?>