add_role() │ WP 2.0.0

Add a new role to WordPress.

The function must be called only once. Because it changes the data in the database (field wp_user_roles of wp_options table). Therefore, it is better to change them during activation/deactivation of the plugin/theme (see an example).

When to use

Before adding or changing roles, make sure that the global variable $wp_roles is available. And it's better to use plugin/theme activation hooks for adding new roles. To add a plugin activation hook, use register_activation_hook().

Delete an existing role

If you create a new role and give it capabilities, make sure that such a role doesn't exist, because this function doesn't work if the role already exists.

To avoid this issue, you can use remove_role() before creating a new role.

Uses: wp_roles(), WP_Roles()

No Hooks.

Return

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

add_role( $role, $display_name, $capabilities );
$role(string) (обязательный)
Role name: administrator, editor, author, contributor, subscriber.
$display_name(string) (обязательный)
Display name for role: Administrator, Author, Subscriber etc.
$capabilities(array)
List of capabilities, e.g. array( 'edit_posts' => true, 'delete_posts' => false ). See the list of capabilities here.
Default: array()

Examples

1

#1 Create a new role on plugin activation, and remove it on plugin deactivation. 

// Delete a role on plugin deactivation
add_action( 'switch_theme', 'deactivate_my_theme' );
function deactivate_my_theme() {
	remove_role( 'basic_contributor' );
}

// Add a role on plugin activation
add_action( 'after_switch_theme', 'activate_my_theme' );
function activate_my_theme() {
	add_role( 'basic_contributor', 'Basic Contributor',
		[
			'read'         => true,
			'edit_posts'   => true,
			'upload_files' => true,
		]
	);
}
0

#2 Create a new role

The name of the role will be basic_contributor and it will be displayed as "Basic Contributor".

Important. The code must be run only once! Do not leave it to work all the time!

$result = add_role( 'basic_contributor', 'Basic Contributor',
	array(
		'read'         => true, 
		'edit_posts'   => true, 
		'upload_files' => true, 
	)
);
if ( null !== $result ) {
	echo 'Hooray! A new role has been created!';
}
else {
	echo 'Oops... This role already exists.';
}
0

#3 Create a new role on plugin activation 

register_activation_hook( __FILE__, 'add_roles_on_plugin_activation' );
function add_roles_on_plugin_activation() {
	add_role('custom_role', 'Custom Subscriber', array( 'read' => true, 'level_0' => true ) );
}
0

#4 Inherit capabilities of role "Author" 

$author = get_role( 'author' );
add_role( 'project_manager', 'Project Manager', $author->capabilities );

Changelog

Since 2.0.0 Introduced.

add_role() code WP 6.7.2

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 );
}

Roles capabilities