7.x 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 Drupal core). When set to TRUE, a standard warning message defined in user_admin_permissions() and 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 overrides the automatic warning generated by 'restrict access' being set to TRUE. This should rarely be used, since it is important for all permissions to have a clear, consistent security warning that is the same across the site. Use the 'description' key instead to provide any information that is specific to the permission you are defining.

See also


Related topics

30 functions implement hook_permission()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

aggregator_permission in modules/aggregator/aggregator.module
Implements hook_permission().
block_permission in modules/block/block.module
Implements hook_permission().
book_permission in modules/book/book.module
Implements hook_permission().
comment_permission in modules/comment/comment.module
Implements hook_permission().
contact_permission in modules/contact/contact.module
Implements hook_permission().

... See full list

5 invocations of hook_permission()
DrupalWebTestCase::checkPermissions in modules/simpletest/drupal_web_test_case.php
Check to make sure that the array of permissions are valid.
MenuBreadcrumbTestCase::setUp in modules/simpletest/tests/menu.test
Sets up a Drupal site for running functional and integration tests.
ModuleImplementsAlterTestCase::testModuleImplementsAlter in modules/simpletest/tests/module.test
Tests hook_module_implements_alter() adding an implementation.
standard_install in profiles/standard/standard.install
Implements hook_install().
SystemAdminTestCase::setUp in modules/system/system.test
Sets up a Drupal site for running functional and integration tests.


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


function hook_permission() {
  return array(
    'administer my module' => array(
      'title' => t('Administer my module'),
      'description' => t('Perform administration tasks for my module.'),


Wim Leers’s picture

In Drupal 6, this was called hook_perm().

perusio’s picture

but there's no equivalent to restrict access in D6. So it's not exactly the same under a different name.

EdgarPE’s picture

Basically the same, only now permissions have shiny translatable titles and such.

codesidekick’s picture

For a detailed explanation on how to define and use custom permissions to control access to nodes, prevent access to custom pages and display messages check out my blog at http://interactivejunky.com/blog/user-permissions-drupal .

aaronbauman’s picture

To implement an (incomplete) hook_alter pattern, implement your own permissions using hook_permission, then use hook_menu_alter() to replace a specific permission with your own.

Chi’s picture

Permissions are defined in $module.permissions.yml

flaviovs’s picture

When choosing permission names, you may be tempted to use generic names like "check files" or "edit all images". This seem to make sense, because permissions are defined in your YOURMODULE_permissions() hook, so everything looks like they are permissions put forward by YOURMODULE.

But they don't. Permission names are unique. A permission name like "check files" may clash with other modules doing (possibly unrelated) file checking. This may cause problems and confuse users. Worst, you may be granting access to site functions that users otherwise shoultn'd be allowed to access.

To avoid this problem, a good approach is to create permission names that include your module name in it. For example, "check YOURMODULE files", "check all YOURMODULE images", etc.

otrolopezmas’s picture

Hi, I noted a typo in your message :). Please note that is hook_permission() and not permissions. So you must use YOURMODULE_permission().