Roles and Capabilities
Topics
Roles and capabilities are two important aspects of WordPress that allow you to control user privileges.
WordPress stores the Roles and their Capabilities in the options table under the user_roles key.
Roles Roles
A role defines a set of capabilities for a user. For example, what the user may see and do in his dashboard.
By default, WordPress have six roles:
- Super Admin
- Administrator
- Editor
- Author
- Contributor
- Subscriber
More roles can be added and the default roles can be removed.
Adding Roles Adding Roles
Add new roles and assign capabilities to them with add_role().
function wporg_simple_role()
{
add_role(
'simple_role',
'Simple Role',
[
'read' => true,
'edit_posts' => true,
'upload_files' => true,
]
);
}
// add the simple_role
add_action('init', 'wporg_simple_role');
Alert:
After the first call to add_role(), the Role and it’s Capabilities will be stored in the database!
Sequential calls will do nothing: including altering the capabilities list, which might not be the behavior that you’re expecting.
Note:
To alter the capabilities list in bulk: remove the role using remove_role() and add it again using add_role() with the new capabilities.
Make sure to do it only if the capabilities differ from what you’re expecting (i.e. condition this) or you’ll degrade performance considerably!
Removing Roles Removing Roles
Remove roles with remove_role().
function wporg_simple_role_remove()
{
remove_role('simple_role');
}
// remove the simple_role
add_action('init', 'wporg_simple_role_remove');
Alert:
After the first call to remove_role(), the Role and it’s Capabilities will be removed from the database!
Sequential calls will do nothing.
Note:
If you’re removing the default roles:
- We advise against removing the Administrator and Super Admin roles!
- Make sure to keep the code in your plugin/theme as future WordPress updates may add these roles again.
- Run
update_option('default_role', YOUR_NEW_DEFAULT_ROLE)
since you’ll be deletingsubscriberwhich is WP’s default role.
Capabilities Capabilities
Capabilities define what a role can and can not do: edit posts, publish posts, etc.
Note:
Custom post types can require a certain set of Capabilities.
Adding Capabilities Adding Capabilities
You may define new capabilities for a role.
Use get_role() to get the role object, then use the add_cap() method of that object to add a new capability.
function wporg_simple_role_caps()
{
// gets the simple_role role object
$role = get_role('simple_role');
// add a new capability
$role->add_cap('edit_others_posts', true);
}
// add simple_role capabilities, priority must be after the initial role definition
add_action('init', 'wporg_simple_role_caps', 11);
Note:
It’s possible to add custom capabilities to any role.
Under the default WordPress admin, they would have no effect, but they can be used for custom admin screen and front-end areas.
Removing Capabilities Removing Capabilities
You may remove capabilities from a role.
The implementation is similar to Adding Capabilities with the difference being the use of remove_cap() method for the role object.
Using Roles and Capabilities Using Roles and Capabilities
Get Role Get Role
Get the role object including all of it’s capabilities with get_role().
get_role(
string $role
);
User Can User Can
Check if a user have a specified role or capability with user_can().
user_can(
int|object $user,
string $capability
);
Warning:
There is an undocumented, third argument, $args, that may include the object against which the test should be performed.
E.g. Pass a post ID to test for the capability of that specific post.
Current User Can Current User Can
current_user_can() is a wrapper function for user_can() using the current user object as the $user parameter.
Use this in scenarios where back-end and front-end areas should require a certain level of privileges to access and/or modify.
current_user_can(
string $capability
);
Example Example
Here’s a practical example of adding an Edit link on the in a template file if the user has the proper capability:
if (current_user_can('edit_posts')) {
edit_post_link('Edit', '<p>', '</p>');
}
Multisite Multisite
The current_user_can_for_blog() function is used to test if the current user has a certain role or capability on a specific blog.
current_user_can_for_blog(
int $blog_id,
string $capability
);
Reference Reference
Codex Reference for User Roles and Capabilities.