permissions_api.module

<?php
// $Id: permissions_api.module,v 1.14 2010/03/09 14:47:22 ebeyrent Exp $

/**
 * @file
 * Provides functions for granting and revoking permissions for given roles
 *
 * @ingroup permissions_api
 */

/**
 * Helper function to grant permissions to a given role.
 *
 * @param
 *   A string that represents a role name in the database.  Ex:  'site administrator'
 * @param
 *   An array of strings representing permissions to be granted to the role specified in the first parameter.
 *   - Ex. array('administer users', 'administer content types');
 * @return
 *   boolean to indicate success or failure
 * @see hook_perm()
 * @see permissions_get_role()
 * @see permissions_get_permissions_for_role()
 */
function permissions_grant_permissions($role_name, $new_permissions) {
  $permissions = array();
  $updated_permissions = '';
  $role = permissions_get_role($role_name);
  if($role->rid > 0) {
    if (count($new_permissions) > 0) {
      // Fetch the permissions string for the given role id
      $permissions = permissions_get_permissions_for_role($role->name);
      // Check to see if there are existing permissions
      if(count($permissions) > 0) {
        // Add the new permissions if the role doesn't already have the permission
        foreach($new_permissions as $permission) {
          if(! in_array($permission, $permissions)) {
            $permissions[] = trim($permission);
          }
        }

        // rebuild the permission string
        $updated_permissions = join(', ', $permissions);
        db_query("UPDATE {permission} SET perm = '%s' WHERE rid = %d", $updated_permissions, $role->rid);
        return true;
      }
      else {
        // No permissions have been set for this role, so we need to insert some
        foreach($new_permissions as $permission){
          $permissions[] = trim($permission);
        }
        // rebuild the permission string
        $updated_permissions = join(', ', $permissions);
        db_query('DELETE FROM {permission} WHERE rid = %d', $role->rid);
        db_query("INSERT INTO {permission} (rid, perm, tid) VALUES(%d,'%s',%d)",$role->rid,$updated_permissions,0);
        return true;
      }
    }
    watchdog('permissions_api', 'permissions_grant_permissions: permissions to grant is empty, expecting array', null, WATCHDOG_ERROR);
    return false;
  }
  watchdog('permissions_api', 'permissions_grant_permissions: failed to get role %rolename.', array('%rolename' => $role->name), WATCHDOG_ERROR);
  return false;
}

/**
 * Helper function to revoke permissions from a role.
 *
 * @param
 *   A string that represents a role name in the database.  Ex:  'site administrator'
 * @param
 *   An array of strings representing permissions to be revoked from the role specified in the first parameter.
 *   - Ex. array('administer users', 'administer content types');
 * @return
 *   boolean to indicate success or failure
 * @see hook_perm()
 * @see permissions_get_role()
 * @see permissions_get_permissions_for_role()
 */
function permissions_revoke_permissions($role_name, $new_permissions) {
  $permissions = array();
  $updated_permissions = '';
  $role = permissions_get_role($role_name);
  if($role->rid > 0) {
    if (! empty($new_permissions)) {
      $permissions = permissions_get_permissions_for_role($role->name);
      if (count($permissions) > 0) {
        // Unset the permission from the array
        foreach($new_permissions as $permission){
          $index = array_search($permission, $permissions);
          if($index !== false){
            unset($permissions[$index]);
          }
        }

        // rebuild the permission string
        $updated_permissions = join(', ', $permissions);
        db_query("UPDATE {permission} SET perm = '%s' WHERE rid = %d", $updated_permissions, $role->rid);
        return true;
      }
      watchdog('permissions_api', 'permissions_revoke_permissions: role %rolename has no permissions defined.', array('%rolename' => $role->name), WATCHDOG_WARNING);
      return false;
    }
    watchdog('permissions_api', 'permissions_revoke_permissions: permissions to revoke is empty, expecting array', null, WATCHDOG_ERROR);
    return false;
  }
  watchdog('permissions_api', 'permissions_revoke_permissions: failed to get role %rolename.', array('%rolename' => $role->name), WATCHDOG_ERROR);
  return false;
}

/**
 * Helper function to grant all defined permissions to a given role
 *
 * @param
 *   A string that represents a role name in the database.  Ex:  'site administrator'
 * @return
 *   boolean to indicate success or failure
 * @see hook_perm()
 * @see permissions_get_role()
 */
function permissions_grant_all_permissions($role_name) {
  $updated_permissions = '';
  $all_permissions = array();
  $role = permissions_get_role($role_name);
  if($role->rid > 0){
    // Build a list of all the permissions defined by hook_perm
    foreach (module_list(FALSE, FALSE, TRUE) as $module) {
      if ($permissions = module_invoke($module, 'perm')) {
        asort($permissions);
        foreach ($permissions as $perm) {
         $all_permissions[] = $perm;
        }
      }
    }

    // Build the permissions string
    $updated_permissions = join(', ', $all_permissions);

    $perm_string = db_result(db_query("SELECT perm FROM {permission} WHERE rid = %d", $role->rid));

    // Check to see if there are existing permissions
    if (strlen($perm_string) > 0) {
      db_query("UPDATE {permission} SET perm = '%s' WHERE rid = %d", $updated_permissions, $role->rid);
    }
    else{
      db_query("INSERT INTO {permission} (rid, perm, tid) VALUES(%d,'%s',%d)",$role->rid,$updated_permissions,0);
    }
    return true;
  }
  watchdog('permissions_api', 'permissions_grant_all_permissions: failed to get role %rolename.', array('%rolename' => $role->name), WATCHDOG_ERROR);
  return false;
}

/**
 * Helper function to grant all permissions defined by a given module to a given role
 *
 * @param
 *   A string that represents a role name in the database.  Ex:  'site administrator'
 * @param
 *   A string that represents the name of a module.  Ex:  'panels'
 * @return
 *   boolean to indicate success or failure
 * @see hook_perm()
 * @see permissions_get_role()
 * @see permissions_get_permissions_for_role()
 */
function permissions_grant_all_permissions_by_module($role_name, $module) {
  $updated_permissions = '';
  $permissions = array();
  $module_permissions = array();
  $role = permissions_get_role($role_name);
  if($role->rid > 0){
    // Fetch the permissions string for the given role id
    $permissions = permissions_get_permissions_for_role($role->name);

    // Check to see if there are existing permissions
    if (count($permissions) > 0) {
      // Build a list of all the permissions defined by hook_perm
      if ($module_permissions = module_invoke($module, 'perm')) {
        asort($module_permissions);
        foreach ($module_permissions as $perm) {
          if(! in_array($perm, $permissions)) {
            $permissions[] = $perm;
          }
        }
      }

      // Build the permissions string
      $updated_permissions = join(', ', $permissions);
      db_query("UPDATE {permission} SET perm = '%s' WHERE rid = %d", $updated_permissions, $role->rid);
      return true;
    }
    else {
      // Build a list of all the permissions defined by hook_perm
      if ($module_permissions = module_invoke($module, 'perm')) {
        asort($module_permissions);
        foreach ($module_permissions as $perm) {
          $permissions[] = $perm;
        }
      }

      // Build the permissions string
      $updated_permissions = join(', ', $permissions);
      db_query("INSERT INTO {permission} (rid, perm, tid) VALUES(%d,'%s',%d)",$role->rid,$updated_permissions,0);
      return true;
    }
  }
  watchdog('permissions_api', 'permissions_grant_all_permissions_by_module: failed to get role %rolename.', array('%rolename' => $role->name), WATCHDOG_ERROR);
  return false;
}

/**
 * Helper function to revoke all permissions defined by a given module from a given role
 *
 * @param
 *   A string that represents a role name in the database.  Ex:  'site administrator'
 * @param
 *   A string that represents the name of a module.  Ex:  'panels'
 * @return
 *   boolean to indicate success or failure
 * @see hook_perm()
 * @see permissions_get_role()
 * @see permissions_get_permissions_for_role()
 */
function permissions_revoke_all_permissions_by_module($role_name, $module) {
  $updated_permissions = '';
  $permissions = array();
  $module_permissions = array();
  $role = permissions_get_role($role_name);
  if($role->rid > 0){
    // Fetch the permissions string for the given role id
    $permissions = permissions_get_permissions_for_role($role->name);

    // Check to see if there are existing permissions
    if (count($permissions) > 0) {
      // Build a list of all the permissions defined by hook_perm
      if ($module_permissions = module_invoke($module, 'perm')) {
        asort($module_permissions);
        foreach ($module_permissions as $perm) {
          $index = array_search($perm, $permissions);
          if($index >= 0){
            unset($permissions[$index]);
          }
        }
      }

      // Build the permissions string
      $updated_permissions = join(', ', $permissions);
      db_query("UPDATE {permission} SET perm = '%s' WHERE rid = %d", $updated_permissions, $role->rid);
      return true;
    }
  }
  watchdog('permissions_api', 'permissions_revoke_all_permissions_by_module: failed to get role %rolename.', array('%rolename' => $role->name), WATCHDOG_ERROR);
  return false;
}

/**
 * Helper function to return an array of permissions for a given role
 *
 * @param
 *   A string that represents a role name in the database.  Ex:  'site administrator'
 * @return
 *   Array an strings representing permissions in the database for the given role
 * @see hook_perm()
 * @see permissions_get_role()
 */
function permissions_get_permissions_for_role($role_name){
  $role = permissions_get_role($role_name);
  $permissions = array();
  if($role->rid > 0){
    $perm_string = db_result(db_query("SELECT perm FROM {permission} WHERE rid = %d", $role->rid));
    if (strlen($perm_string) > 0) {
      $permissions = explode(',', $perm_string);
      foreach($permissions as $index => $perm){
        $permissions[$index] = trim($perm);
      }
    }
  }
  return $permissions;
}

/**
 * Helper function to look up the role by name
 *
 * @param
 *   A string that represents a role name in the database.  Ex:  'site administrator'
 * @return
 *   Object representing a role
 */
function permissions_get_role($role_name) {
  $role = db_fetch_object(db_query("SELECT * FROM {role} r WHERE r.name = '%s'", $role_name));
  return $role;
}

/**
 * Helper function to create a new role in the database
 *
 * @param
 *   String representing the name of the role to be created.  Ex:  'site administrator'
 * @return
 *   Returns either an object representing the newly created (or previously existing) role, or FALSE if there was an error
 */
function permissions_create_role($role_name) {
  // Look up the role to see if it exists already
  $role = permissions_get_role($role_name);
  if(!$role) {
    db_query("INSERT INTO {role} VALUES('', '%s')", $role_name);
    $role = permissions_get_role($role_name);
    if($role->rid > 0) {
      return $role;
    }
    watchdog('permissions_api', 'permissions_create_role: failed to create role %rolename', array('%rolename' => $role->name), WATCHDOG_ERROR);
    return false;
  }
  watchdog('permissions_api', 'permissions_create_role: role %rolename already exists, returning existing role', array('%rolename' => $role->name), WATCHDOG_WARNING);
  return $role;
}

/**
 * This function allows a role to inherit either all the permissions of another role
 *
 * @param
 *   A string that represents a role name in the database.  Ex:  'site administrator'
 * @param
 *   A string that represents another role name in the database.  Ex:  'site editor'
 * @return
 *   boolean to indicate success or failure
 * @see hook_perm()
 * @see permissions_get_role()
 * @see permissions_get_permissions_for_role()
 */
function permissions_role_inherit($new_role, $orig_role) {
  $role = permissions_get_role($orig_role);
  if(! $role) {
    watchdog('permissions_api', 'permissions_role_inherit: unable to inherit permissions from %rolename; role doesn\'t exist', array('%rolename' => $orig_role), WATCHDOG_ERROR);
    return false;
  }

  $clone = permissions_get_role($new_role);
  if(! $clone) {
    watchdog('permissions_api', 'permissions_role_inherit: unable to inherit permissions into %new_role; role doesn\'t exist', array('%new_role' => $new_role), WATCHDOG_ERROR);
    return false;
  }

  // Inherit all of the permissions
  $role_permissions = permissions_get_permissions_for_role($role->name);
  if(! empty($role_permissions)) {
    permissions_grant_permissions($clone->name, $role_permissions);
    return true;
  }
  watchdog('permissions_api', 'permissions_role_inherit: failed to retrieve permissions for role %rolename.', array('%rolename' => $role->name), WATCHDOG_ERROR);
  return false;
}
?>