Adds a role name with capabilities to the list.
Description
Updates the list of roles, if the role doesn’t already exist.
The list of capabilities can be passed either as a numerically indexed array of capability names, or an associative array of boolean values keyed by the capability name. To explicitly deny the role a capability, set the value for that capability to false.
Examples:
// Add a role that can edit posts.
wp_roles()->add_role( 'custom_role', 'Custom Role', array(
'read',
'edit_posts',
) );Or, using an associative array:
// Add a role that can edit posts but explicitly cannot not delete them.
wp_roles()->add_role( 'custom_role', 'Custom Role', array(
'read' => true,
'edit_posts' => true,
'delete_posts' => false,
) );Parameters
$rolestringrequired- Role name.
$display_namestringrequired- Role display name.
$capabilities<span class="array”>array|<span class="array”>arrayoptional- Capabilities to be added to the role.
Default:
array()
Source
public function add_role( $role, $display_name, $capabilities = array() ) {
if ( empty( $role ) || isset( $this->roles[ $role ] ) ) {
return;
}
if ( wp_is_numeric_array( $capabilities ) ) {
$capabilities = array_fill_keys( $capabilities, true );
}
$this->roles[ $role ] = array(
'name' => $display_name,
'capabilities' => $capabilities,
);
if ( $this->use_db ) {
update_option( $this->role_key, $this->roles, true );
}
$this->role_objects[ $role ] = new WP_Role( $role, $capabilities );
$this->role_names[ $role ] = $display_name;
return $this->role_objects[ $role ];
}
As you may have seen, the role is added to an option called
$this->role_key. This property is initialized in the methodWP_Roles::for_sitein this way:Thus, if your website prefix is
wp_, then the option name will bewp_user_roles.Also, keep in mind that this method will create a new role only if it doesn’t exist already in the database.