function hook_node_access_records

Same name and namespace in other branches
  1. 9 core/modules/node/node.api.php \hook_node_access_records()
  2. 8.9.x core/modules/node/node.api.php \hook_node_access_records()
  3. 10 core/modules/node/node.api.php \hook_node_access_records()
  4. 11.x core/modules/node/node.api.php \hook_node_access_records()

Set permissions for a node to be written to the database.

When a node is saved, a module implementing hook_node_access_records() will be asked if it is interested in the access permissions for a node. If it is interested, it must respond with an array of permissions arrays for that node.

Node access grants apply regardless of the published or unpublished status of the node. Implementations must make sure not to grant access to unpublished nodes if they don't want to change the standard access control behavior. Your module may need to create a separate access realm to handle access to unpublished nodes.

Note that the grant values in the return value from your hook must be integers and not boolean TRUE and FALSE.

Each permissions item in the array is an array with the following elements:

  • 'realm': The name of a realm that the module has defined in hook_node_grants().
  • 'gid': A 'grant ID' from hook_node_grants().
  • 'grant_view': If set to 1 a user that has been identified as a member of this gid within this realm can view this node. This should usually be set to $node->status. Failure to do so may expose unpublished content to some users.
  • 'grant_update': If set to 1 a user that has been identified as a member of this gid within this realm can edit this node.
  • 'grant_delete': If set to 1 a user that has been identified as a member of this gid within this realm can delete this node.
  • 'priority': If multiple modules seek to set permissions on a node, the realms that have the highest priority will win out, and realms with a lower priority will not be written. If there is any doubt, it is best to leave this 0.

When an implementation is interested in a node but want to deny access to everyone, it may return a "deny all" grant:

$grants[] = array(
    'realm' => 'all',
    'gid' => 0,
    'grant_view' => 0,
    'grant_update' => 0,
    'grant_delete' => 0,
    'priority' => 1,

Setting the priority should cancel out other grants. In the case of a conflict between modules, it is safer to use hook_node_access_records_alter() to return only the deny grant.

Note: a deny all grant is not written to the database; denies are implicit.


$node: The node that has just been saved.

Return value

An array of grants as defined above.

See also



Related topics

2 functions implement hook_node_access_records()

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

node_access_test_node_access_records in modules/node/tests/node_access_test.module
Implements hook_node_access_records().
node_test_node_access_records in modules/node/tests/node_test.module
Implements hook_node_access_records().
1 invocation of hook_node_access_records()
node_access_acquire_grants in modules/node/node.module
Gets the list of node access grants and writes them to the database.


modules/node/node.api.php, line 271


function hook_node_access_records($node) {
    // We only care about the node if it has been marked private. If not, it is
    // treated just like any other node and we completely ignore it.
    if ($node->private) {
        $grants = array();
        // Only published nodes should be viewable to all users. If we allow access
        // blindly here, then all users could view an unpublished node.
        if ($node->status) {
            $grants[] = array(
                'realm' => 'example',
                'gid' => 1,
                'grant_view' => 1,
                'grant_update' => 0,
                'grant_delete' => 0,
                'priority' => 0,
        // For the example_author array, the GID is equivalent to a UID, which
        // means there are many groups of just 1 user.
        // Note that an author can always view his or her nodes, even if they
        // have status unpublished.
        $grants[] = array(
            'realm' => 'example_author',
            'gid' => $node->uid,
            'grant_view' => 1,
            'grant_update' => 1,
            'grant_delete' => 1,
            'priority' => 0,
        return $grants;

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.