How to create and change WordPress user roles programmatically

In this tutorial we are going to look into how you can create, assign and bulk assign user roles programmatically without using a plugin.

By default, WordPress has user roles that can define the users’ access level and this is the main mechanism that WordPress uses to controls the content or requires different permissions or capabilities for the different roles. By default WordPress comes with some build in user roles with an array of capabilities, you can learn more about the basics WordPress user roles and what they can do in more details in this article. However there are some situations when you may want to use 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. Working with custom WordPress user roles allows you to define specific user-access and to control what the different user types can do at the same time.

WordPress custom user roles and capabilities is a powerful way to control how different users can interact with your WordPress site.  For example user roles can be used  in your theme or plugin to change visual aspects, such as menus or widgets or to hide or show content specific content. This is functionality that is quite common for membership websites. This powerful tool can be used in many different ways to add additional levels of security and prevent certain users from accessing specific information.

 

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. In WordPress a user can have multiple roles, or just one.

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:

function ui_new_role() {  

    //add the new user role
    add_role(
        'power_member',
        'Power Member',
        array(
            'read'         => true,
            'delete_posts' => false
        )
    );

}
add_action('admin_init', 'ui_new_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.

Getting user roles

In some situations you might want to check what user roles some user has been assigned to. It’s a little counterintuitive but in WordPress you can’t get the user role of a user just by passing the user ID. This is because the user roles data is stored in the user meta table in the database. For this, first we have to get the user_meta_data, this will return an Object that will contain all the user roles assigned to a user:

$user_meta=get_userdata($user_id);

$user_roles=$user_meta->roles; //returns an array of roles the user is assigned to

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 dedicated WordPress user role editor plugin to change the WordPress user role and capability of some of the existing default user role. Or you can also create a new custom role with its own custom capability and permission. And all this can be done with WordPress plugin via the WordPress dashboard. Alternatively, as we are exploring in this tutorial, you can use some custom code snippets to achieve the same results programmatically.

Since WordPress support multiple roles per user, you can use a single role that replaces all the roles of the user. Or you can assign different roles in addition to the default role used.

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:

$user = new WP_User(123); //123 is the user ID
$user->roles; // ["subscriber"]

$user->add_role('power_member');
$user->roles; // ["subscriber", "power_member"]

$user->set_role('editor');
$user->roles; // ["editor"]

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 10^th 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:

function ui_check_logins( $user_login, $user ) {
    
    //retrieve the number of sessions for this user
    $sessions = get_user_meta( $user->ID, 'ui_user_sessions', true );
    
    //if our sessions counter isn't empty let's see how many sessions this user's got
    if ( ! empty ($sessions) ) {
        //let's increase our sessions counter
        $sessions++;
        
        //now we check if the current session is the 10th and if our user is a subscriber
        if ( $sessions == 10 && in_array("subscriber", $user->roles) ) {
            //here our magic is done, we're setting the new role
            $user->set_role('power_member');
        }
        
        //let's update our user's session counter
        update_user_meta( $user->ID, 'ui_user_sessions', $sessions);
    }
    // in this case our sessions counter is empty, so let's create it
    else {
        update_user_meta( $user->ID, 'ui_user_sessions', 1);
    }
}
add_action('wp_login', 'ui_check_logins', 10, 2);

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.

 

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:

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

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?

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!