You are here

Drupal 7 - Adding Roles

This post builds upon a previous post: Drupal 7 - A Simple Content Type: Permissions & Access

Roles and permissions are central to managing user access to content within Drupal. Out of the box Drupal has three user roles defined:

  • Anonymous - This user is not logged into the site.
  • Authenticated - This user is logged into the site. All roles besides 'anonymous' are considered to be authenticated users and have the same permissions included in it's list of permissions.
  • Administrator - This user has free run of all functionality within the site.

Roles - Authenticated vs Anonymous users

As you can see from the above image, the new roles we are creating in this example, will also have the same permissions assigned to them as an 'authenticated' user does with other permissions being optional. For this example we will create a module that defines two new roles with some permissions assigned to each by default. There will be two hooks and a couple helper functions to handle the lifting, first thing we need to do is define the hook_install() and hook_uninstall() functions:

 * Implements hook_install()
function simple_roles_install() {
	// create any roles we will be using
	$newb_permissions = array(
		'search content',
		'view simple content type',
	$pangus_permissions = array(
		'search content',
		'use advanced search',
		'view simple content type',
		'create simple content type',
		'edit simple content type',
		'delete simple content type',
	_add_role('pangus', 1);
	_add_permissions('newb', $newb_permissions);
	_add_permissions('pangus', $pangus_permissions);
 * Implements hook_uninstall()
function simple_roles_uninstall() {
	// remove any roles we created

The install hook defines two arrays which are the lists of permissions we will use to assign to each role. Next we create two roles and then assign permissions to each one using some helper functions we define in a moment. The uninstall hook uses user_role_delete() to remove the roles we created. Now let's define the helper functions:

 *	Adds a new role
 *      @machine_name - the name of the role to be added
 *      @weight - the optional display weight for role
function _add_role($machine_name, $weight = 0)  {
	$role = new stdClass();
	$role->name = $machine_name;
	$role->weight = $weight;
 *	Adds permissions to a role
 *	@role_name - the name of the role to receive an update
 *	@permissions - the array of permissions to add
function _add_permissions($role_name, $permissions)  {
	$role = user_role_load_by_name($role_name);
	user_role_grant_permissions($role->rid, $permissions);

We really only need one piece of info to add a new role with user_role_save() but we also want to make it possible to position the role appropriately on the permissions configuration page so we have two parameters for the _add_role() function, $machine_name - the name of the role to be added and $weight - the optional display weight for role. To add permissions to a role we need just two pieces of info: $role_name - the machine name of the role to receive a permissions update and $permissions - the array of permissions to add to that role as formatted in the install hook. That's the bulk of what we need for this module. We do still need to tell Drupal about our module and even though there is no actual code in it, without the module.module file Drupal won't see it when we try to enable it:

 * @file
 * This file is required for all modules

And lastly here's the file:

name = Simple Roles
description = A demonstration on adding roles
package = Andy Pangus Examples
core = 7.x
dependencies[] = search
dependencies[] = simple_content_type
files[] = simple_roles.install
files[] = simple_roles.module

This module has two dependencies which provide the permissions we use in this example: the Search module and the Simple Content Type module we created in the "Permissions and Access" example. Once the Simple Roles module has been enabled if you go to admin/people/permissions you will see something similar to the following:

The two new roles with assigned permissions

You can still add and remove permissions from roles once they have been created using the Drupal Admin UI. I might use something like this to create roles for use within a package of modules.

Download the source for this example.

See what you can do with roles in the post: Drupal 7 - Adding Roles to Users Dynamically