From bb01454c129c6a4fdf6ab0096bb14a916c6744d0 Mon Sep 17 00:00:00 2001
From: Bradley M. Froehle <bfroehle@math.berkeley.edu>
Date: Sat, 13 Nov 2010 12:20:53 -0800
Subject: [PATCH] #963656 follow-up by agentrickard, bfroehle: Improve documentation for {node_access} and node_access_view_all_nodes()

---
 modules/node/node.api.php |   37 +++++++++++++++++++++++++++++++++++++
 modules/node/node.module  |   23 ++++++++++-------------
 2 files changed, 47 insertions(+), 13 deletions(-)

diff --git modules/node/node.api.php modules/node/node.api.php
index 41dcdca..50734bf 100644
--- modules/node/node.api.php
+++ modules/node/node.api.php
@@ -143,6 +143,43 @@
  * module's responsibility to provide appropriate realms to limit access to
  * unpublished content.
  *
+ * Node access records are stored in the {node_access} table and define which
+ * grants are required to access a node.  An entry in the {node_access} table
+ * with node ID 0 corresponds to a global grant for the view operation.  It
+ * has no effect for other other operations like edit and delete.  If no node
+ * access modules are present, the core node module provides this global view
+ * permission for grant ID 0 and realm 'all'.
+ *
+ * Node access modules can replicate this behavior by providing their own
+ * conditional grant for an entry of {node_access} corresponding to node ID 0.
+ * For example, a module could create a record in {node_access} with:
+ * @code
+ * $record = array(
+ *   'nid' => 0,
+ *   'gid' => 888,
+ *   'realm' => 'example_realm',
+ *   'grant_view' => 1,
+ *   'grant_update' => 0,
+ *   'grant_delete' => 0,
+ * );
+ * drupal_write_record('node_access', $record);
+ * @endcode
+ * To grant global view access, the module may now return the following array
+ * in response to hook_node_grants():
+ * @code
+ * if ($op == 'view') {
+ *   $grants['example_realm'] = array(888);
+ * }
+ * @endcode
+ *
+ * Beware that node_access_rebuild() function will erase any node ID 0 entry
+ * when it is called, as there is currently no hook to generate node ID 0
+ * grants.  Module developers are responsible for ensuring these gloabl view
+ * grants are restored after node_access_rebuild() is called.
+ *
+ * @see node_access_view_all_nodes()
+ * @see node_access_rebuild()
+ *
  * @param $account
  *   The user object whose grants are requested.
  * @param $op
diff --git modules/node/node.module modules/node/node.module
index 252d722..5468d29 100644
--- modules/node/node.module
+++ modules/node/node.module
@@ -3007,16 +3007,13 @@ function node_access_grants($op, $account = NULL) {
 /**
  * Determines whether the user has a global viewing grant for all nodes.
  *
- * Checks to see whether any module grants 'view' for nid = 0. The node module
- * provides this record if no node access modules are enabled. Other modules
- * can replicate this behavior by providing their own conditional grant for
- * nid = 0. For example, hook_node_grants() can return the following array to
- * give the 'view' privilege to all nodes:
- * @code
- * if ($op == 'view') {
- *   $grants['example_realm'] = array(0);
- * }
- * @endcode
+ * Checks to see whether any module grants 'view' for node ID 0. The node
+ * module provides this record if no node access modules are enabled.
+ *
+ * Note that this function does not allow a user to view all nodes. Instead, it
+ * removes the default JOIN from the {node} to the {node_access} table
+ * provided by node_query_node_access_alter() when querying for lists of
+ * nodes. Other rules enforced by the node_access() function are still applied.
  *
  * @return
  *   TRUE if 'view' access to all nodes is granted, FALSE otherwise.
@@ -3108,15 +3105,15 @@ function _node_query_node_access_alter($query, $base_table, $type) {
     $op = 'view';
   }
 
-  // If $account can bypass node access, or there are no node access
-  // modules, we don't need to alter the query.
+  // If $account can bypass node access, or there are no node access modules,
+  // or we are viewing and have a global view grant (i.e., a view grant for
+  // node ID 0), we don't need to alter the query.
   if (user_access('bypass node access', $account)) {
     return;
   }
   if (!count(module_implements('node_grants'))) {
     return;
   }
-  // If viewing nodes, make sure access rules should be enforced.
   if ($op == 'view' && node_access_view_all_nodes()) {
     return;
   }
-- 
1.7.3.1