add_role( string $role, string $display_name, bool[] $capabilities = array() )

Add role, if it does not exist.


Parameters Parameters

$role

(string) (Required) Role name.

$display_name

(string) (Required) Display name for role.

$capabilities

(bool[]) (Optional) List of capabilities keyed by the capability name, e.g. array( 'edit_posts' => true, 'delete_posts' => false ).

Default value: array()


Top ↑

Return Return

(WP_Role|null) WP_Role object if role is added, null if already exists.


Top ↑

Source Source

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


Top ↑

Changelog Changelog

Changelog
Version Description
2.0.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Roger Theriault

    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' );
    
  2. Skip to note 2 content
    Contributed by Jules Colle

    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 );
    
  3. Skip to note 3 content
    Contributed by Codex

    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' );
  4. Skip to note 4 content
    Contributed by Codex

    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.

  5. Skip to note 5 content
    Contributed by Codex

    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.';
    }
  6. Skip to note 6 content
    Contributed by Codex

    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.

  7. Skip to note 8 content
    Contributed by samjco

    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

You must log in before being able to contribute a note or feedback.