4.3. Defining Permissions: hook_perm

In Chapter 3 you learned about the permissions page and how an errant click on that page could allow a typical user to perform actions she shouldn't be allowed to do. Let's dig into how that page is constructed and how the permissions are checked.

The hook hook_perm() is a function that any module can implement to add more permissions to the list at Administer User Management Permissions. Here is an example usage of the function from the Drupal core blog module:

function blog_perm() {
  return array('create blog entries', 'delete own blog entries', 'delete
any blog entry', 'edit own blog entries', 'edit any blog entry'),
}

That's it! Creating a new permission for your module is as simple as adding a new entry in the array that is returned.

Let's take a look at the implementation of this function in the Node module:

function node_perm() {
  $perms = array('administer content types', 'administer nodes', 'access
content', 'view revisions', 'revert revisions', 'delete revisions'),

  foreach (node_get_types() as $type) {
    if ($type->module == 'node') {
      $name = check_plain($type->type);
      $perms[] = 'create '. $name .' content';
      $perms[] = 'delete own '. $name .' content';
      $perms[] = 'delete any '. $name .' content';
      $perms[] = 'edit own '. $name .' content';
      $perms[] = 'edit any '. $name .' content';
    }
  }

  return $perms;
}

The Node module's version of the function first creates a simple array of permissions. Then it builds a set of permissions based on the list of content types available on a site. Note the use of the check_plain() function. Chapter 5 covers the check_plain and other similar functions.

You don't really need to worry about this, but for further understanding, here is the code that actually builds the list of permissions. This code can be found in the User module in the file user.admin.inc.

$options = array();
  foreach (module_list(FALSE, FALSE, TRUE) as $module) {
    if ($permissions = module_invoke($module, 'perm')) {
      $form['permission'][] = array(
        '#value' => $module,
      );
      asort($permissions);
      foreach ($permissions as $perm) {
        $options[$perm] = '';
        $form['permission'][$perm] = array('#value' => t($perm));
        foreach ($role_names as $rid => $name) {
          // Builds arrays for checked boxes for each role
          if (strpos($role_permissions[$rid], $perm .',') !== FALSE) {
            $status[$rid][] = $perm;
          }
        }
      }
    }
  }

Reading through this code, you can see that it initializes an array of options and then iterates over a list of modules and checks each module to see if it provides a list of permissions. The module_invoke function is a part of the Drupal API specifically for calling hook implementations. The code then sorts the permissions alphabetically and sets about building the big sea of check boxes for the permissions, setting the boxes to be checked or not depending on the permissions and roles on a site.