Last updated March 24, 2012. Created by ebeyrent on May 18, 2010.
Edited by silverwing. Log in to edit this page.

Overview

The purpose of this page is to provide developer documentation for the Permissions API module, which exposes an API for developers to grant and revoke permissions via code. This is of particular use in the context of staging and deployment, where new roles and changes to permissions for roles need to be deployed automatically from one environment to another. The functions provided by the Permissions API module are intended to be called via hook_update_n() functions in custom modules. However, version 6.x-2.9 of the module provides Drush integration, allowing for another method of automating these configurations.

Permissions API is not the only mechanism for performing this level of automation in Drupal deployments; the Features module allows for import/export of roles and permissions on the feature level.

Creating Roles

Permissions API provides a function for creating new roles in code, and is a simple function with one parameter, a string representing the name of the role you wish to create. The function will either return an object representing the newly-created role, or FALSE if an error occurred. Errors are logged via watchdog.

<?php
/**
* Implementation of hook_update()
*/
function MYMODULE_update_6001() {
 
$role = permissions_create_role('site administrator');
}
?>

This can also be accomplished via Drush command:

$ drush -u 1 role-create 'site administrator'

Deleting Roles

Permissions API provides a function for deleting roles in code, and is a simple function with one parameter, a string representing the name of the role you wish to delete. The function will either return an object representing the deleted role, or FALSE if an error occurred. Errors are logged via watchdog.

<?php
/**
* Implementation of hook_update()
*/
function MYMODULE_update_6001() {
 
$role = permissions_delete_role('site administrator');
}
?>

This can also be accomplished via Drush command:

$ drush -u 1 role-delete 'site administrator'

Granting Permissions

Granting Specific Permissions

Permissions API provides a function for granting multiple permissions to a given role. The function expects two parameters: a string representing the name of the role to grant permissions to, and an array of strings representing individual permissions to grant. The function will return TRUE if successful, and FALSE if an error occurred. Errors are logged via watchdog.

<?php
/**
* Implementation of hook_update()
*/
function MYMODULE_update_6001() {
 
$permissions = array(
   
'create some_content_type content',
   
'edit some_content_type content',
   
'edit own some_content_type content',
  );
 
permissions_grant_permissions('some role', $permissions);
}
?>

This can also be accomplished via Drush command:

$ drush -u 1 perm-grant --roles="site administrator" --permissions="administer nodes, administer users"
Granting Permissions By Module

Another option is grant all permissions defined by a specific module. This function expects two parameters: the name of the role to grant the permissions to, and the name of a module that defines the permissions to be granted. The function will return TRUE if successful, and FALSE if an error occurred. Errors are logged via watchdog.

<?php
/**
* Implementation of hook_update()
*/
function MYMODULE_update_6001() {
 
// Grant all permissions defined by a module's hook_perm implementation
 
permissions_grant_all_permissions_by_module('site administrator', 'devel');
}
?>
Granting All Permissions

Permissions API has a useful function for granting all permissions to a role, which is very helpful for creating site administrators and keep the permissions up to date with the release of new features. The function takes a single argument of a string representing the name of the role to grant all permissions to. The function will return TRUE if successful, and FALSE if an error occurred. Errors are logged via watchdog.

<?php
/**
* implementation of hook_update()
*/
function MYMODULE_update_6001() {
 
// Create a "super-admin" role by granting all permissions
 
permissions_grant_all_permissions('site administrator');
}
?>

This can also be accomplished via Drush command:

$ drush perm-grant --roles="site administrator" --all-modules

Revoking Permissions

Revoking Specific Permissions

Permissions API provides a function for revoking multiple permissions from a given role. The function expects two parameters: a string representing the name of the role to revoke permissions from, and an array of strings representing individual permissions to revoke. The function will return TRUE if successful, and FALSE if an error occurred. Errors are logged via watchdog.

<?php
/**
* Implementation of hook_update()
*/
function MYMODULE_update_6001() {
 
$permissions = array(
   
'create some_content_type content',
   
'edit some_content_type content',
   
'edit own some_content_type content',
  );
 
permissions_revoke_permissions('some role', $permissions);
}
?>

This can also be accomplished via Drush command:

$ drush -u 1 perm-revoke --roles="site administrator" --permissions="administer nodes, administer users"
Revoking Permissions By Module

Another option is to revoke all permissions defined by a specific module. This function expects two parameters: the name of the role to revoke the permissions from, and the name of a module that defines the permissions to be revoked. The function will return TRUE if successful, and FALSE if an error occurred. Errors are logged via watchdog.

<?php
/**
* Implementation of hook_update()
*/
function MYMODULE_update_6001() {
 
// Revoke all permissions defined by a module's hook_perm implementation
 
permissions_revoke_all_permissions_by_module('site administrator', 'devel');
}
?>
Revoking All Permissions

Permissions API has a useful function for revoking all permissions from. The function takes a single argument of a string representing the name of the role to revoke all permissions from. The function will return TRUE if successful, and FALSE if an error occurred. Errors are logged via watchdog.

<?php
/**
* implementation of hook_update()
*/
function MYMODULE_update_6001() {
 
permissions_revoke_all_permissions('site administrator');
}
?>

This can also be accomplished via Drush command:

$ drush perm-revoke --roles="site administrator" --all-modules

Cloning Permissions

Permissions API provides a function for essentially allowing one role to inherit all of the permissions from another role. This function is a shortcut of sorts, and saves developers from having to recreate roles and permissions in code and keep those up to date. The function expects two arguments: a string representing the name of the role to inherit permissions, and a string representing the name of the role to inherit permissions from. The function will return TRUE if successful, and FALSE if an error occurred. Errors are logged via watchdog.

<?php
/**
* Implementation of hook_update()
*/
function MYMODULE_update_6001() {
 
permissions_role_inherit('editor', 'site administrator');
}
?>

This can also be accomplished via Drush command:

$ drush perm-copy 'editor' 'site administrator'

Drush Integration

To get a helpful list of Drush commands supported by the Permissions API module, execute the following:

$ drush help | grep perm

Further help and examples can be obtained by executing a drush help command followed by the specific Permissions API command:

$ drush help perm-grant
Grant permissions to a role.
Examples:
drush perm-grant --roles="Admin"          Grant all permissions provided by the Node module to the Admin role.
--modules="node"
drush perm-grant --all-modules            Grant all permissions to Admin role.
--roles-="Admin"
drush perm-grant --roles="Editor,Copy     Grant "administer nodes" to Editor and Copy Editor roles.
Editor" --permissions="administer nodes"
drush perm-grant --all-roles              Grant "administer nodes" permission to all roles.
--permissions="administer nodes"                                                                             
Options:
--all-roles                               Grant the permissions to all defined roles.
--roles                                   Comma-separated list of roles to grant permissions to.
--permissions                             Comma-separated list of permissions to grant to a role or roles.
--modules                                 Comma-separated list of modules providing permissions to grant.
--all-modules                             Grant all defined permissions to a role or roles.

$ drush help perm-revoke
Revoke permissions from a role.
Examples:
drush perm-revoke --roles="Admin"         Revoke all permissions provided by the Node module from the Admin role.
--modules="node"
drush perm-revoke --all-modules           Revoke all permissions from the Admin role.
--roles-="Admin"
drush perm-revoke --roles="Editor,Copy    Revoke "administer nodes" from the Editor and Copy Editor roles.
Editor" --permissions="administer nodes"
drush perm-revoke --all-roles             Revoke "administer nodes" permission from all roles.
--permissions="administer nodes"
drush perm-revoke --reset                 Revoke all permissions from all roles.  Requires confirmation, use with
                                           caution.                                                              
Options:
--all-roles                               Revoke the permissions from all defined roles.
--roles                                   Comma-separated list of roles to revoke permissions from.
--permissions                             Comma-separated list of permissions to revoke from a role or roles.
--modules                                 Comma-separated list of modules providing permissions to revoke.
--all-modules                             Revoke all defined permissions from a role or roles.
--reset                                   Revoke all defined permissions from all roles.  Requires confirmation,
                                           use with caution.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.