How to create and change WordPress user roles programmatically

Today we’re going to learn how to create and use custom roles for your WordPress users. Working with custom WordPress user roles allows you to define specific user-access. In addition, this approach allows you to differentiate users, by creating user levels. Our goal is to look into how you can create, assign and bulk assign user roles, as well as how to use this information in your site.

By default, WordPress has user roles that can define the users’ access level, their capabilities and their status in your site. Even though they are quite useful, they may be limited. Sometimes you may want to differentiate users, but you don’t want to grant them a subscriber or contributor role. Creating custom WordPress user roles is a great way to solve this problem, by giving users just the access that they should have.

The truth is: custom user roles can be used in many ways in a WordPress site. In addition to categorize different users, it can be a security tool. That’s because they only allow user access when they have the right role. But it also can be used to identify how your users interact with your site. For example, a long-time user may be rewarded with a specific role. An insightful commenter may also have a role for them.

wordpress custom role

It’s worth mentioning that WordPress custom roles have two implementation modes. They can be used in addition to your current user roles, or they can replace them. Thus, a user can have multiple roles, or just one. And these roles can be used in your theme or plugin to change visual aspects, such as menus or widgets. Another great use for them is to hide or show content, by creating a membership site.

Let’s get started by creating our new custom WordPress user roles.

Creating a new custom WordPress user role

Before assigning your users to a role we need to tell WordPress that we have this role in our site. We can create the role by using the add_role() function. Once a role is created, it is stored in the database. This means that you need to run the code that creates the role only once on your website. Even if you remove the code after it’s created, the role would still exist on your site. The only way we can remove that afterwards is by using yet another snippet.

Here is an example of using the add_role() function to create a new WordPress user role:

 

There are two components for that code, the role creation and our hook.

  • add_role( $name, $display_name, $capabilities)  – this is our main function. It creates a new role with the capabilities we set. You need to use a unique name to avoid conflicts, and you can add your user capabilities there or later.
  • add_action( 'admin_init', 'ui_new_role')  – this is what is calling our function. Here we’re telling WordPress “whenever you load an admin page, run this function as well”. In reality, the best place to run this code would be upon a theme or plugin activation. So if you have this possibility go for it! Since this is just an example we’ll simply add that code and save. Then we’ll reload any of our admin pages so that the role is created. Then we’ll remove that code. In this way our role is created and ready to be used.

Next step is finding the best function to change or add new WordPress user roles.

Changing User Role vs Adding User Role

There are two approaches when it comes to assigning custom roles to your WordPress users. You can use a single role that replaces all the roles of the user. Or you can assign different roles in addition to the current one.

Changing the role itself is quite easy. You just need to load the WordPress class for a user and use either the set_role method (for replacing) or the add_role method (for adding new roles).

The following example illustrates using both methods:

Both approaches have their pros and cons. When you use a WordPress role change, your users will be limited only to the capabilities that this specific role allows. This is particularly useful if you have well defined and excluding roles in your site. So, if a user can only be either member or manager, using the “set_role” method is the way to go.

On the other hand, if your site is used in a way that users can do different things at the same time, “add role” is your best option. For example, if you need your “Editor” users to also have “Member” capabilities, you can add the “Member” role to your users, so they won’t lose their editing capabilities.

Programmatically apply a custom user role

Now it’s time to get our hands dirty. Let’s see some examples of how you can change your WordPress user roles based on certain criteria.

Suppose we want to change users from the default “subscriber” role to the new “power member” role we’ve created. And that change should happen after the 10th login of a user. So here are the ingredients for our code:

  • Declare a new WordPress role – That’s been done above, you can use the code we have there
  • When a user logs in, let’s load the WordPress User Class for that user
  • Then we’ll check if this is the 10th login and if they are a subscriber (this shouldn’t affect other roles such as admins, contributors or any remaining role)
  • If all conditions are true, then let’s change the user role

Now this is the snippet to do it:

This code is just a very basic example, but you can use many variations of it. For instance, let’s say that we want to add the power_member role to users who have commented 15 times. A very similar approach can be used, but this time we’ll check the current comments count for that user. Also, we’ll run that code in different hooks, as we want to do that based on a different action.

In the end, the core of changing WordPress user roles programmatically is finding the right hooks. Once you find the right hook for what you want, then you’ll be able to plug in your custom function. In addition, often we need variables that aren’t stored yet. For these cases you can make use of new custom fields, as we’ve done with the sessions.

Bulk Change Roles

We have explained in detail how you can change WordPress user roles in bulk in our WooCommerce roles tutorial. There you’ll see how to change user roles in bulk using filtering criteria. But if you want a quick way to change all users from one role to another the “Bulk Change Role” plugin is a good tool.

WooCommerce change user role in bulk

 

Finding WordPress User Roles

Often, we also need to see some information about our users. And you can use the Users Insights  plugin for that. With it we can extract more information from our new user roles. For instance, you can just filter out all users who have our new role:

WordPress custom role users

We could also export these users and process their data using some external software:

Export users for our custom role

It’s also possible to filter even further users based on our role rules. So if we change user roles based on their sessions, are they still as active? If we change user roles based on their comment count, are they still commenting?

Users criteria for custom role is met

Based on that we can also define new WordPress user roles to customize even further our user experience.

Conclusion

Today we’ve looked into how you can create custom user roles in WordPress. We learned the different methods of applying these roles to our users, by adding or replacing them. Also we saw code examples of how to programmatically switch user roles. And finally, we found out ways to bulk change user roles, as well as how to extract information using the Users Insights plugin.

We hope you enjoyed it, and see you again next time!