Change record status: 
Introduced in branch: 

As a part of #1479454: Convert user roles to configurables the 'role' table has been removed from the database schema and user roles have been converted to configuration entities (configurables).


  • The 'role' table has been removed from the database schema.
  • User roles become classed objects a.k.a. Drupal\user\Plugin\Core\Entity\UserRole.
  • Core and Standard Installation Profile user roles are now defined in .yml files.
  • Instead of directly accessing user role values we now use the appropriate Entity API methods (e.g. $role->label() or $role->id())
  • The custom CRUD API for user roles has been removed in favor of a proper Entity API storage controller a.k.a. Drupal\user\Plugin\Core\Entity\UserRoleStorageController.
  • The old CRUD methods (user_role_save(), user_role_load() and user_role_delete()) have been removed in favor of the Entity CRUD API. Role::load() can be used as a shortcut to load a user role.

API changes

Use the Entity API CRUD functions & methods in the future instead of user_role_load(), user_role_delete() or user_role_save().
Custom user roles previously defined in code through user_role_save() should be defined through .yml files in the future.
A new function user_role_names() has been added.


Defining a custom user role

Drupal 7

// Create a default role for site administrators, with all available permissions assigned.
$admin_role = new stdClass();
$admin_role->rid = 'administrator';
$admin_role->name = 'Administrator';
$admin_role->weight = 2;

Drupal 8

Through a YAML file (@see core/profiles/standard/config/install/user.role.administrator.yml).

id: administrator
label: Administrator
weight: 2

User role CRUD operations

Drupal 7

// Load 'anonymous' user role.
$role = user_role_load(DRUPAL_ANONYMOUS_RID);

// Change the weight of a user role.
$role->weight = 30;

// Delete a user role.

Drupal 8

// Load 'anonymous' user role.
$role = entity_load('user_role', DRUPAL_ANONYMOUS_RID);

// Change the weight of a user role.
$role->weight = 30;

// Delete a user role that has already been loaded.

// Delete a user role by name/ID.
entity_delete('user_role', 'administrator');

Site builders, administrators, editors
Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other updates done