This post is a part 11 of Creating a WordPress Admin Theme post series.
A WordPress site can have multiple registered users. All these users don’t have the same authority for site customisation, posting, editing etc. They all have different set of permissions to deal with the website. In this article I will explain what are user roles and capabilities And how to create customized roles.
Roles and Capabilities
A capability in WordPress is a permission given to a registered user. There many different kinds of capabilities defined in WordPress. We cannot create our own capabilities we can only assign defined capabilities to registered users. Example of some capabilities are: activate_plugins, delete_pages, manage_options, read etc.
A role is a set of capabilities. We cannot directly assign capabilities to a registered user, we always assign role to a registered user. A registered user must have a role. Example of some roles are administrator, editor, author, contributor and subscriber.
We can programatically add/remove capabilities from roles. We can also create our own custom roles.
User responsible for creating the website is by default assigned to administrator role. A administrator has all capabilities. A site can have multiple administrators. Administrators can alter other administrators accounts also.
While registering new users if you don’t provide a role then by default assigned to subscriber role. We can change this default behavior by navigating to Settings → General in admin menu. There you will find a option to change it.
Here you will find list of predefined user roles and their respective capabilities.
Creating new roles
add_role is used to create new roles.
Put this code in your plugin or theme file:
<?php
//check if role already exists
if(get_role("ninja") == null)
{
//role doesn't exist create it.
//parameters: role name, display name, an array of capabilities
$role_created = add_role("ninja", "Ninja", array(
'read' => true, // true allows this capability
'edit_posts' => true,
'delete_posts' => false, // Use false to explicitly deny
));
if($role_created !== null)
{
//role created successfully
}
else
{
//failed to create a new role
}
}
else
{
//role exists
}
?>
//check if role already exists
if(get_role("ninja") == null)
{
//role doesn't exist create it.
//parameters: role name, display name, an array of capabilities
$role_created = add_role("ninja", "Ninja", array(
'read' => true, // true allows this capability
'edit_posts' => true,
'delete_posts' => false, // Use false to explicitly deny
));
if($role_created !== null)
{
//role created successfully
}
else
{
//failed to create a new role
}
}
else
{
//role exists
}
?>
Remove a role
We can remove a predefined role and also a custom created role using remove_role.
Put this code in plugin or theme file to delete subscriber role
<?php
//check if role exists
if(get_role("subscriber") !== null)
{
//role exists.
//parameters: role name
$role_deleted = remove_role("subscriber");
if($role_deleted !== null)
{
//role deleted successfully
}
else
{
//failed to delete role
}
}
else
{
//role doesn't exist
}
?>
//check if role exists
if(get_role("subscriber") !== null)
{
//role exists.
//parameters: role name
$role_deleted = remove_role("subscriber");
if($role_deleted !== null)
{
//role deleted successfully
}
else
{
//failed to delete role
}
}
else
{
//role doesn't exist
}
?>
Adding and Removing Capabilities
We can add capabilities to predefined roles or custom roles using add_cap. Similarly we can remove capabilities from predefined roles and custom roles using remove_cap.
<?php
//check if role exists
$role = get_role("author");
if($role !== null)
{
//role exists.
$role->remove_cap( 'read' );
$role->remove_cap( 'delete_posts' );
$role->add_cap( 'edit_pages' );
$role->add_cap( 'manage_links' );
}
else
{
//role doesn't exist
}
?>
//check if role exists
$role = get_role("author");
if($role !== null)
{
//role exists.
$role->remove_cap( 'read' );
$role->remove_cap( 'delete_posts' );
$role->add_cap( 'edit_pages' );
$role->add_cap( 'manage_links' );
}
else
{
//role doesn't exist
}
?>
