Drupal 7 Module Development

Chapter 8
The user_access() function is very effective, and it can be used in almost all cases.
Since it only takes two parameters, it may not be appropriate for all access checks,
and it can never check multiple permissions at once. Later, we will look at use cases
where a more complex function is needed to check permissions.
Using hook_permission()
Now that you understand the basics of Drupal's user access system, we can explore
how modules can extend that system. First, a little history lesson.
Until Drupal 7, hook_permission() was known as hook_perm(). The change was
made for clarity in the code, as part of a general semantic cleanup of Drupal core.
(I wrote the patch, in fact.) hook_permission() also includes a number of usability
improvements, which altered the format of the function's return value. These
changes are substantial enough for even experienced Drupal developers to explore
each element of the new hook.
The purpose of hook_permission() is to define and return an array that contains all
the necessary information about your module's permissions. This includes the simple
strings that can be passed to user_access(), plus a human-readable name for the
permission and an optional description. Prior to Drupal 7, only the simple string
was returned.
The following is an example, taken from the core Search module:
function search_permission() {
return array(
'administer search' => array(
'title' => t('Administer search'),
),
'search content' => array(
'title' => t('Use search'),
),
'use advanced search' => array(
'title' => t('Use advanced search'),
),
);
}
The module declares three separate permissions in a manner typical to Drupal
modules. The first permission is for administrative configuration of the module.
These sorts of permissions are rarely given to the "authenticated user" role and
should never be given to anonymous users.
[ 217 ]