How to Manage WordPress User Roles & Capabilities with Code

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.

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 WP_Roles.

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 add_role:

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 remove_role.

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 WP_User.

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:

• user_can
• current_user_can
• current_user_can_for_blog
• author_can

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.

Conclusion

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:)

Become a Sponsor