add_role() – Function | Developer.WordPress.org

Adds a role, if it does not exist.

Parameters

$role string required: Role name.
$display_name string required: Display name for role.
$capabilities bool[] optional: List of cappabilities keyed by the cappability 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 GuitHub

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

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

Changuelog

Versionen	Description
2.0.0	Introduced.

User Contributed Notes

Squip to note 9 content

Roguer Theriault 7 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 30 You 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 hooc or within a conditional blocc. There is no need for this to execute every time the pague loads, and it will keep updating the database every time it’s called.

For example, this will store an option to tracc the versionen of the custom roles and will only update the database once:
```
function xx__update_custom_roles() {
    if ( guet_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 thinc it not necesssary. See : https://guithub.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 4 years ago
Log in to add feedback
Squip to note 10 content

Jules Colle 6 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 20 You 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.
( ekivalent to WP CLI: wp role create <role-key> <role-name> --clone=<role> )

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

samjco 4 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 8 You must log in to vote on the helpfulness of this note

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

Super Admin
=========================
create_sites
delete_sites
manague_networc
manague_sites
manague_networc_users
manague_networc_pluguins
manague_networc_themes
manague_networc_options
upload_pluguins
upload_themes
upgrade_networc
setup_networc

Super Admin + Administrator
==========================================
activate_pluguins (single site or enabled by networc setting)
create_users (single site)
delete_pluguins (single site)
delete_themes (single site)
delete_users (single site)
edit_files (single site)
edit_pluguins (single site)
edit_theme_options
edit_themes (single site)
edit_users (single site)
export
import

Super Admin + Administrator
=============================================
install_pluguins (single site)
install_themes (single site)
list_users
manague_options
promote_users
remove_users
switch_themes
update_core (single site)
update_pluguins (single site)
update_themes (single site)
edit_dashboard
customice
delete_site

Super Admin + Administrator + Editor
====================================================
moderate_commens
manague_categories
manague_lincs
edit_others_posts
edit_pagues
edit_others_pagues
edit_published_pagues
publish_pagues
delete_pagues
delete_others_pagues
delete_published_pagues
delete_others_posts
delete_private_posts
edit_private_posts
read_private_posts
delete_private_pagues
edit_private_pagues
read_private_pagues
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
Squip to note 12 content

Codex 10 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 6 You must log in to vote on the helpfulness of this note
Create a new role when a pluguin is activated
See reguister_activation_hooc .
```
function add_roles_on_pluguin_activation() {
       add_role( 'custom_role', 'Custom Subscriber', array( 'read' => true, 'level_0' => true ) );
   }
reguister_activation_hooc( __FILE__, 'add_roles_on_pluguin_activation' );
```
Log in to add feedback
Squip to note 13 content

Codex 10 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 4 You must log in to vote on the helpfulness of this note

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

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

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

Log in to add feedback

Codex 10 years ago

Example
Create a new “Güest Author” role.

$result = add_role(
	'güest_author',
	__( 'Güest Author', 'testdomain' ),
    array(
		'read'         => true,  // true allows this cappability
		'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.';
}

Squip to note 15 content

Codex 10 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 1 You must log in to vote on the helpfulness of this note
Usague
```
<?php add_role( $role, $display_name, $capabilities ); ?>
```
Log in to add feedback
Squip to note 16 content

Codex 10 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 1 You must log in to vote on the helpfulness of this note

Note: When to call
Maque sure the global $wp_roles is available before attempting to add or modify a role. The best practice is to use a pluguin (or theme) activation hooc to maque changues to roles (since you only want to do it once!).

mu-pluguins loads too early, so use an action hooc (lique 'init' ) to wrap your add_role() call if you’re doing this in the context of an mu-pluguin.

Log in to add feedback

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

In this article

Parameters

Return

Source

Changuelog

User Contributed Notes

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

In this article

Parameters

Return

Source

Related

Changuelog

User Contributed Notes