WordPress User Roles are one of the first things you learn about when working with a team inside WordPress. When you install a WordPress site, you also create a user with the user role administrator. In this tutorial, I will show you how you can create different roles and also how to add custom capabilities to roles or users.
You may wonder why would you use the code and programmatically set some of the WordPress user roles or capabilities. In my career as a developer, especially WordPress developer, I have encountered various projects where I needed custom user roles.
User Roles & Capabilities
The user roles & capabilities can be used to add a specific feature to a particular user role or a particular user. The system of roles & capabilities is really great in WordPress and it can allow you to do various things.
You can add a feature to a specific role or user, but you can also remove one. This means that a user could be an editor, but for some reason, you don’t want them to edit the posts. You can disable that capability from that user while retaining the user role.
Why would you manage them with Code
To get you the idea closer to you, I will show you a simple example.
Let’s imagine a shop done with WooCommerce. We want a feature that will enable a special discount of 30% only to customers that have already bought 10 of our products.
Would you do that with a WordPress user role? You could, but is that really a good approach? We could forget to add a capability from a role that the user has and thus disable a feature.
Why not just add a capability to that user that says use_special_discount?
We could then use the function
current_user_can('user_special_discount') and see if that is enabled or not.
WordPress User Roles
User roles can be accessed through the global variable
$wp_roles. This variable is actually an object of
Here is a simplified view of this object. I have written it as an array for easier reading. You can always check this variable by using the PHP function
var_dump. This will get you the whole object.
To check the whole definition of the class
WP_Roles, check the WordPress Code Reference.
User Role Object
Each role that is created is also instantiated as an object of
WP_Role. When we want to retrieve a role, we will also receive this object.
By using the
WP_Role we can easily update the role by removing or adding new capabilities. Here is a simple example of a single object for the WordPress user role Administrator.
Adding a User Role
To add a new WordPress user role, we need to use the function
The first parameter is the role slug (name), the second one is the display name which will be shown in the WordPress dashboard and other areas. The last parameter is an array of capabilities that this role does enable for a user.
Updating a User Role
To update a WordPress user role, you will need to get the role using the function
get_role. This function will return an object of
WP_Role. You can use the methods from that object to update the role.
Whenever we add or remove a capability, the database will be updated and this will then remain until we remove or add (again) the capability.
Removing a User Role
WordPress user roles can be easily removed by using the function
What will happen here? First, role objects, names and role definitions will be unset for that role. After that, WordPress will update the roles and also reset the default role if that role was set as a default role.
Warning: be sure to check users with those roles and add them to a new role if they don’t have any.
I am not really sure how this would work out if you don’t manage those users. I assume they will have the default role then, but I have not tried it yet.
Manage Roles for a User
We can also manage all the roles a user has. To do that, we need the object
WordPress User Capabilities
The capabilities are the flags that enable a feature for a user. When a user has various roles, all those capabilities are merged together. This enables us to have roles with completely different capabilities.
You can add a capability to a role or a user. If the capability is set specifically to a user, it will overwrite the current capability value (true/false).
Check the capability
When we are checking if a user can do something (ex. edit a post, create a page), we need to check the capability for that user. This can be done with several functions:
Manage Capabilities for a User
To add or remove a capability from a user, we need to get the
WP_User object of the user. This can be done by using the function
get_userdata where we provide the User ID.
Manage Capabilities for a Role
We have already seen how to add or remove a capability to a Role when we learned how to update a Role. It won’t hurt, repeating it.
Hooking into the WordPress User
There are various hooks there that can be used to add additional events when a function occurs.
Adding a Role
Removing a Role
Setting a Role
When Should you Create a Role?
You don’t want to create a role on each WordPress load because it will access the database for no reason.
Before WordPress 4.7, you had to create the WordPress user roles on plugin activation. That is a fine approach, and you can use it now also. I would actually advise you to do so still if you want the roles to be permanently saved.
As of WordPress 4.7 there is a new hook
wp_roles_init. When using this hook, you have direct access to the object
WP_Roles. You could add roles or capabilities on each WordPress load but without any database usage.
In this tutorial, you have learned how to set a role, create one or remove one. You have also seen how to add a capability to a specific user and thus overwrite the default capability value.
The roles and capabilities can be used to provided various parts of your solution to many users or to just one user. This can come in handy if you are providing a connection to a service and need to check the capability of a single user.
Have you ever worked with WordPress User roles and capabilties? If you have written a solution or know a scenario where the roles have been programmatically added or removed, please do share in the comments below:)