Codex

Attention Help us to improve the Codex by filling out our documentation survey!

Function Reference/add role

Contents

Description

Adds a new role to WordPress.

NB: This setting is saved to the database (in table wp_options, field wp_user_roles), so it might be better to run this on theme/plugin activation

Usage

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

Parameters

$role
(string) (required) Role name
Default: None
$display_name
(string) (required) Display name for role
Default: None
$capabilities
(array) (optional) Array of capabilities (see Roles_and_Capabilities for list of available capabilities)
Default: array()

Returns

(mixed) 
Returns a WP_Role object on success, null if that role already exists.

Example 

$result = add_role('basic_contributor', 'Basic Contributor', array(
    'read' => true, // True allows that capability
    'edit_posts' => true,
    'delete_posts' => false, // Use false to explicitly deny
));
if (null !== $result) {
    echo 'Yay!  New role created!';
} else {
    echo 'Oh... the basic_contributor role already exists.';
}

Notes

Changelog

Source Code

add_role() is located in wp-includes/capabilities.php.

Related

Roles and Capabilities: add_role(), remove_role(), get_role(), add_cap(), remove_cap()

See also index of Function Reference and index of Template Tags.
Retrieved from "http://codex.wordpress.org/Function_Reference/add_role"

Codex Resources