Creating roles

Sometimes, rather than adding capabilities to an existing role, you need to create a whole new role. The code to do so is relatively easy. Again, place these lines in your theme’s functions.php file:

// Create
add_role('privatereader', 'Private Reader', array(
            'read' => 1,
            'level_0′ => 1,
            'read_private_pages' => 1,
            'read_private_posts' => 1,
        ));
?>

The add_role function requires three arguments: the role’s name (for internal use), the display name, and an array of the role’s capabilities. (See the Codex page on Roles and Capabilities for a complete list of the capabilities in WordPress.) Here, we’ve given our role the same two capabilities a subscriber starts out with, ‘read’ and ‘level_0.’ (The level_n capabilities exist for backward compatibility with very early versions of WordPress, which used a 1-10 scale instead of named roles.) Then we’ve added the two roles relating to private content.

If you create or edit a user now, you should see the new Private Reader role as an option.

If we wanted to modify our new role, we’d use the same code we used to change capabilities before, but but we’d change the get_role function’s argument to our new role’s internal name.

// remove ability to read private pages
$PrivateRole = get_role('privatereader');
$PrivateRole -> remove_cap('read_private_pages');
?>

Need to remove the role? That’s easy:

remove_role('privatereader');
?>

That’s nice, but now what?

In this example, it makes sense to create a new role only if you wanted to keep the subscriber role as-is; otherwise; it was simpler to just modify the subscriber role.

When would it make sense to create a new role?

Let’s imagine a new scenario. You’re building a large site, and you, the programmer, are sharing responsibilities with a graphic designer. You want to give your designer complete control over the content and theme design, but you don’t want him editing other users, adding plugins, or importing content from other sites.

We could create a whole new role and enumerate every capability we want the designer to have, as we did above for the private reader, but this role will be similar to the administrator’s, and that’s a lot of capabilities! Instead, we’ll duplicate the admin role and remove the eight or nine capabilities we don’t want the designer to have.

Creating a designer role

$admin = get_role('administrator');

// get_role returns an object.
// We want the capabilities piece, which is an array.
$caps = $admin->capabilities;

// Remove the stuff we don't want in the new role.
unset($caps['activate_plugins']);
unset($caps['edit_plugins']);
unset($caps['update_plugins']);
unset($caps['delete_plugins']);
unset($caps['install_plugins']);
unset($caps['edit_users']);
unset($caps['delete_users']);
unset($caps['create_users']);
unset($caps['import']);

// Add the new role.
add_role('designer', 'Designer', $caps);
?>

And that’s that!

Note that WordPress’s admin menus and screens don’t always behave exactly as you’d expect. In this case, even though we’ve removed all capabilities involving plugins, the designer will still be able to access the Plugins → Add New screen, search for plugins, and install them — but s/he won’t be able to activate the new plugin, or see the list of installed plugins.

The user/role structure is due for an overhaul in version 3.1; hopefully these menu glitches will be addressed then.

Managing Roles with Plugins

If you’d rather click tickyboxes than write all this code, Justin Tadlock’s Members plugin provides an elegant user interface for everything I’ve shown here. It also has some extra features related to private content.