Programmatically assign roles to users in Drupal

This post is part of a series of posts on making changes in Drupal programmatically rather than in the Drupal interface.

The problem

You want to programmatically assign role(s) to user(s). You would typically do this in a site deployment module in order to automate this task rather than having to manually assign the roles in the Drupal UI.

One role to one user

If you only have to assign a single role to a single user, the code is relatively simple.

In this example, we will assign the 'editor' role to a user with a user id of 2.

  1. $uid = 2;
  2. $role = user_role_load_by_name("editor");
  3. user_multiple_role_edit(array($user->uid), 'add_role', $role->rid);

First we load the role by its name and then use user_multiple_role_edit() to save it to the user. user_multiple_role_edit() is a callback function that is used when mass updating user accounts. It comes in very handy for cases like this.

Alternative method

Another way to do this is to add the new role to existing roles for the user and then save the user object.

  1. $uid = 2;
  2. $user = user_load($id);
  3. $role = user_role_load_by_name("editor");
  4. $user->roles = $user->roles + array($role->rid => $role->name);
  5. user_save($user);

But this is an extra two lines of code. First we need to load the user by its ID and then the role by its name. Then join (using array union) the new role to the existing roles ($user->roles) and assign it to the user role's property. Finally, save the user object. This will work, but using user_multiple_role_edit() is simpler and cleaner.

One role to more than one user

In this example, we will assign the editor role to three users. The three users have user IDs of 2, 7 and 61.

  1. $users = array(2, 7, 61);
  2. $role = user_role_load_by_name("editor");
  3. foreach($users as $uid) {
  4. user_multiple_role_edit(array($user->uid), 'add_role', $role->rid);
  5. }

This is similar to the first example, except here we are looping through the array of user IDs and then calling user_multiple_role_edit() for each one in turn.

More than one role to more than one user

This is the most complex of our examples because we need to assign more than one role to more than one user.

  1. $users = array(2, 7, 61);
  2. $roles = array("editor", "administrator");
  3. foreach($users as $uid) {
  4. foreach($roles as $role) {
  5. $role = user_role_load_by_name($role);
  6. user_multiple_role_edit(array($uid), 'add_role', $role->rid);
  7. }
  8. }

In this example, there are two roles in an array, editor and administrator. We loop through each user and then loop through each role. Then we assign the individual roles to each user.

Wrapping up

This is three examples of programmatically assigning roles to users. You would normally do this in the Drupal UI but it is sometimes helpful to do it in code in order to automate it during deployment and save any manual steps. For more information on making changes programmatically during deployment, check out my post on creating a site deployment module.


  1. $users = array(2, 7, 61);
  2. $roles = array("editor", "administrator");
  3. foreach($roles as $role) {
  4. $role = user_role_load_by_name($role);
  5. user_multiple_role_edit($users, 'add_role', $role->rid);
  6. }

thanks for your info

Thanks for this helpful article.. In "One role to more than one user" section, this could be more concise:

$users = array(2, 7, 61);
$role = user_role_load_by_name('editor');
user_multiple_role_edit($users, 'add_role', $role->rid);

Based from the official docs (, "user_multiple_role_edit" will automatically load the $users array parameter using the "user_load_multiple" function, hence there's no need to loop the user objects.

Blair Wadman's picture

Looks good, thanks for this ranelpadon

Add new comment