#842962 by jhodgdon, chx: Fixed hook_menu() and drupal_deliver_page() need to warn about access checks in documentation.

2 files changed, 21 insertions, 9 deletions

diff --git a/includes/common.inc b/includes/common.inc
index d02141269..e57d87cb7 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -2292,29 +2292,29 @@ function l($text, $path, array $options = array()) {
 }
 
 /**
- * Deliver a page callback result to the browser in the format appropriate.
+ * Delivers a page callback result to the browser in the appropriate format.
  *
  * This function is most commonly called by menu_execute_active_handler(), but
  * can also be called by error conditions such as drupal_not_found(),
  * drupal_access_denied(), and drupal_site_offline().
  *
- * When a user requests a page, index.php calls menu_execute_active_handler()
+ * When a user requests a page, index.php calls menu_execute_active_handler(),
  * which calls the 'page callback' function registered in hook_menu(). The page
  * callback function can return one of:
- * - NULL: to indicate no content
- * - an integer menu status constant: to indicate an error condition
- * - a string of HTML content
- * - a renderable array of content
+ * - NULL: to indicate no content.
+ * - An integer menu status constant: to indicate an error condition.
+ * - A string of HTML content.
+ * - A renderable array of content.
  * Returning a renderable array rather than a string of HTML is preferred,
  * because that provides modules with more flexibility in customizing the final
  * result.
  *
  * When the page callback returns its constructed content to
- * menu_execute_active_handler(), this functions gets called. The purpose of
+ * menu_execute_active_handler(), this function gets called. The purpose of
  * this function is to determine the most appropriate 'delivery callback'
  * function to route the content to. The delivery callback function then
  * sends the content to the browser in the needed format. The default delivery
- * callback is drupal_deliver_html_page() which delivers the content as an HTML
+ * callback is drupal_deliver_html_page(), which delivers the content as an HTML
  * page, complete with blocks in addition to the content. This default can be
  * overridden on a per menu router item basis by setting 'delivery callback' in
  * hook_menu() or hook_menu_alter(), and can also be overridden on a per request
@@ -2330,6 +2330,16 @@ function l($text, $path, array $options = array()) {
  * they should not issue any "print" or "echo" statements, but instead just
  * return content.
  *
+ * Also note that this function does not perform access checks. The delivery
+ * callback function specified in hook_menu(), hook_menu_alter(), or
+ * hook_page_delivery_callback_alter() will be called even if the router item
+ * access checks fail. This is intentional (it is needed for JSON and other
+ * purposes), but it has security implications. Do not call this function
+ * directly unless you understand the security implications, and be careful in
+ * writing delivery callbacks, so that they do not violate security. See
+ * drupal_deliver_html_page() for an example of a delivery callback that
+ * respects security.
+ *
  * @param $page_callback_result
  *   The result of a page callback. Can be one of:
  *   - NULL: to indicate no content.
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index 8f72133d9..fea9a9746 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -888,7 +888,9 @@ function hook_page_build(&$page) {
  *   - "delivery callback": The function to call to package the result of the
  *     page callback function and send it to the browser. Defaults to
  *     drupal_deliver_html_page() unless a value is inherited from a parent menu
- *     item.
+ *     item. Note that this function is called even if the access checks fail,
+ *     so any custom delivery callback function should take that into account.
+ *     See drupal_deliver_html_page() for an example.
  *   - "access callback": A function returning a boolean value that determines
  *     whether the user has access rights to this menu item. Defaults to
  *     user_access() unless a value is inherited from a parent menu item.