add_role() – Function | Developer.WordPress.org

Adds a role, if it does not exist.

Parameters

$rolestringrequired: Role name.
$display_namestringrequired: Display name for role.
$capabilitiesbool[]optional: List of capabilities keyed by the capability name, e.g. array( 'edit_posts' => true, 'delete_posts' => false ).
Default:array()

Return

WP_Role|void WP_Role object, if the role is added.

Source

function add_role( $role, $display_name, $capabilities = array() ) {
	if ( empty( $role ) ) {
		return;
	}

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

View all references View on Trac View on GitHub

Uses	Description
wp_roles()`wp-includes/capabilities.php`	Retrieves the global WP_Roles instance and instantiates it if necessary.
WP_Roles::add_role()`wp-includes/class-wp-roles.php`	Adds a role name with capabilities to the list.

Used by	Description
populate_roles_160()`wp-admin/includes/schema.php`	Create the roles for WordPress 2.0

Changelog

Version	Description
2.0.0	Introduced.

User Contributed Notes

Skip to note 9 content

Roger Theriault 5 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 29You must log in to vote on the helpfulness of this note
Be sure to use this function (and similar role functions) only in an activation hook or within a conditional block. There is no need for this to execute every time the page loads, and it will keep updating the database every time it’s called.

For example, this will store an option to track the version of the custom roles and will only update the database once:
```
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' );
```
- Hi, Maybe, this code has been useful at some point, but currently I think it not necessary. See : https://github.com/WordPress/wordpress-develop/blob/efead24c16b84bfb1b5b5e83748e8654e77e54d2/src/wp-includes/class-wp-roles.php#L156-L159 If the role already exists, the database is not updated. The function just does nothing.
  
  Aurélien Joahny 2 years ago
Log in to add feedback
Skip to note 10 content

Jules Colle 4 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 19You must log in to vote on the helpfulness of this note
You can also easily create a new user role based on an existing user role.
( equivalent to WP CLI: wp role create <role-key> <role-name> --clone=<role> )

Example: create a role Superintended with the same capabilities as Administrator
```
add_role( 'superintendent', 'Superintendent', get_role( 'administrator' )->capabilities );
```
Log in to add feedback
Skip to note 11 content

samjco 2 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 8You must log in to vote on the helpfulness of this note

A list of all possible Capabilities per user roles:
https://wordpress.org/support/article/roles-and-capabilities/#capability-vs-role-table

Super Admin
=========================
create_sites
delete_sites
manage_network
manage_sites
manage_network_users
manage_network_plugins
manage_network_themes
manage_network_options
upload_plugins
upload_themes
upgrade_network
setup_network

Super Admin + Administrator
==========================================
activate_plugins (single site or enabled by network setting)
create_users (single site)
delete_plugins (single site)
delete_themes (single site)
delete_users (single site)
edit_files (single site)
edit_plugins (single site)
edit_theme_options
edit_themes (single site)
edit_users (single site)
export
import

Super Admin + Administrator
=============================================
install_plugins (single site)
install_themes (single site)
list_users
manage_options
promote_users
remove_users
switch_themes
update_core (single site)
update_plugins (single site)
update_themes (single site)
edit_dashboard
customize
delete_site

Super Admin + Administrator + Editor
====================================================
moderate_comments
manage_categories
manage_links
edit_others_posts
edit_pages
edit_others_pages
edit_published_pages
publish_pages
delete_pages
delete_others_pages
delete_published_pages
delete_others_posts
delete_private_posts
edit_private_posts
read_private_posts
delete_private_pages
edit_private_pages
read_private_pages
unfiltered_html (single site)
unfiltered_html

Super Admin + Administrator + Editor + Author
==========================================================
edit_published_posts
upload_files
publish_posts
delete_published_posts

Super Admin + Administrator + Editor + Author + Contributor
========================================================================
edit_posts
delete_posts

Super Admin + Administrator + Editor + Author + Contributor + Subscriber
======================================================================================
read

Log in to add feedback
Skip to note 12 content

Codex 8 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note
Create a new role when a plugin is activated
See 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' );
```
Log in to add feedback

Codex 8 years ago

Example
Create a new “Guest Author” role.

$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.';
}

Skip to note 14 content

Codex 8 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
Usage
```
<?php add_role( $role, $display_name, $capabilities ); ?>
```
Log in to add feedback
Skip to note 15 content

Codex 8 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

Note: When to call
Make sure the global $wp_roles is available before attempting to add or modify a role. The best practice is to use a plugin (or theme) activation hook to make changes to roles (since you only want to do it once!).

mu-plugins loads too early, so use an action hook (like 'init') to wrap your add_role() call if you’re doing this in the context of an mu-plugin.

Log in to add feedback
Skip to note 16 content

Codex 8 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

Note: Delete existing role
You can not change the capabilities of an existing role using add_role(). This function will stop executing and return null is the specified role name already exists.

You can change a user role’s capabilities (or display name) by using remove_role(), then add_role().

This is for development only. Once you have nailed down your list of capabilities, there’s no need to keep the remove_role() code.

Log in to add feedback

add_role( string $role, string $display_name, bool[] $capabilities = array() ): WP_Role|void

In this article

Parameters

Return

Source

Changelog

User Contributed Notes

add_role( string $role, string $display_name, bool[] $capabilities = array() ): WP_Role|void

In this article

Parameters

Return

Source

Related

Changelog

User Contributed Notes