1 system.api.php hook_permission()

Define user permissions.

This hook can supply permissions that the module defines, so that they can be selected on the user permissions page and used to grant or restrict access to actions the module performs.

Permissions are checked using user_access().

For a detailed usage example, see page_example.module.

Return value

An array whose keys are permission names and whose corresponding values: are arrays containing the following key-value pairs:

  • title: The human-readable name of the permission, to be shown on the permission administration page. This should be wrapped in the t() function so it can be translated.
  • description: (optional) A description of what the permission does. This should be wrapped in the t() function so it can be translated.
  • restrict access: (optional) A boolean which can be set to TRUE to indicate that site administrators should restrict access to this permission to trusted users. This should be used for permissions that have inherent security risks across a variety of potential use cases (for example, the "administer filters" and "bypass node access" permissions provided by Backdrop core). When set to TRUE, a standard warning message output via theme_user_permission_description() will be associated with the permission and displayed with it on the permission administration page. Defaults to FALSE.
  • warning: (optional) A translated warning message to display for this permission on the permission administration page. This warning should describe the security implications of this permission and accompanies the automatic warning generated by 'restrict access' being set to TRUE. This warning message will be initially hidden and can be viewed by clicking the 'more' link.

See also

theme_user_permission_description()

Related topics

Hooks Allow modules to interact with the Backdrop core.

File

core/modules/system/system.api.php, line 1703
Hooks provided by Backdrop core and the System module.

Code

function hook_permission() {
  return array(
    'configure my module' => array(
      'title' => t('Configure my module'),
      'description' => t('Configure settings for my module.'),
    ),
    'administer my module' => array(
      'title' => t('Administer my module'),
      'description' => t('Perform administration tasks for my module.'),
      'restrict access' => TRUE,
      'warning' => t('Allows people to perform actions that could lead to data loss.'),
    ),
  );
}