<?php

/**

 * @file

 * API for the Drupal menu system.

 */

/**

 * @defgroup menu Menu system

 * @{

 * Define the navigation menus, and route page requests to code based on URLs.

 *

 * The Drupal menu system drives both the navigation system from a user

 * perspective and the callback system that Drupal uses to respond to URLs

 * passed from the browser. For this reason, a good understanding of the

 * menu system is fundamental to the creation of complex modules. As a note,

 * this is related to, but separate from menu.module, which allows menus

 * (which in this context are hierarchical lists of links) to be customized from

 * the Drupal administrative interface.

 *

 * Drupal's menu system follows a simple hierarchy defined by paths.

 * Implementations of hook_menu() define menu items and assign them to

 * paths (which should be unique). The menu system aggregates these items

 * and determines the menu hierarchy from the paths. For example, if the

 * paths defined were a, a/b, e, a/b/c/d, f/g, and a/b/h, the menu system

 * would form the structure:

 * - a

 *   - a/b

 *     - a/b/c/d

 *     - a/b/h

 * - e

 * - f/g

 * Note that the number of elements in the path does not necessarily

 * determine the depth of the menu item in the tree.

 *

 * When responding to a page request, the menu system looks to see if the

 * path requested by the browser is registered as a menu item with a

 * callback. If not, the system searches up the menu tree for the most

 * complete match with a callback it can find. If the path a/b/i is

 * requested in the tree above, the callback for a/b would be used.

 *

 * The found callback function is called with any arguments specified

 * in the "page arguments" attribute of its menu item. The

 * attribute must be an array. After these arguments, any remaining

 * components of the path are appended as further arguments. In this

 * way, the callback for a/b above could respond to a request for

 * a/b/i differently than a request for a/b/j.

 *

 * For an illustration of this process, see page_example.module.

 *

 * Access to the callback functions is also protected by the menu system.

 * The "access callback" with an optional "access arguments" of each menu

 * item is called before the page callback proceeds. If this returns TRUE,

 * then access is granted; if FALSE, then access is denied. Default local task

 * menu items (see next paragraph) may omit this attribute to use the value

 * provided by the parent item.

 *

 * In the default Drupal interface, you will notice many links rendered as

 * tabs. These are known in the menu system as "local tasks", and they are

 * rendered as tabs by default, though other presentations are possible.

 * Local tasks function just as other menu items in most respects. It is

 * convention that the names of these tasks should be short verbs if

 * possible. In addition, a "default" local task should be provided for

 * each set. When visiting a local task's parent menu item, the default

 * local task will be rendered as if it is selected; this provides for a

 * normal tab user experience. This default task is special in that it

 * links not to its provided path, but to its parent item's path instead.

 * The default task's path is only used to place it appropriately in the

 * menu hierarchy.

 *

 * Everything described so far is stored in the menu_router table. The

 * menu_links table holds the visible menu links. By default these are

 * derived from the same hook_menu definitions, however you are free to

 * add more with menu_link_save().

 */

/**

 * @defgroup menu_flags Menu flags

 * @{

 * Flags for use in the "type" attribute of menu items.

 */

/**

 * Internal menu flag -- menu item is the root of the menu tree.

 */

define('MENU_IS_ROOT', 0x0001);

/**

 * Internal menu flag -- menu item is visible in the menu tree.

 */

define('MENU_VISIBLE_IN_TREE', 0x0002);

/**

 * Internal menu flag -- menu item is visible in the breadcrumb.

 */

define('MENU_VISIBLE_IN_BREADCRUMB', 0x0004);

/**

 * Internal menu flag -- menu item links back to its parent.

 */

define('MENU_LINKS_TO_PARENT', 0x0008);

/**

 * Internal menu flag -- menu item can be modified by administrator.

 */

define('MENU_MODIFIED_BY_ADMIN', 0x0020);

/**

 * Internal menu flag -- menu item was created by administrator.

 */

define('MENU_CREATED_BY_ADMIN', 0x0040);

/**

 * Internal menu flag -- menu item is a local task.

 */

define('MENU_IS_LOCAL_TASK', 0x0080);

/**

 * Internal menu flag -- menu item is a local action.

 */

define('MENU_IS_LOCAL_ACTION', 0x0100);

/**

 * @} End of "Menu flags".

 */

/**

 * @defgroup menu_item_types Menu item types

 * @{

 * Definitions for various menu item types.

 *

 * Menu item definitions provide one of these constants, which are shortcuts for

 * combinations of @link menu_flags Menu flags @endlink.

 */

/**

 * Menu type -- A "normal" menu item that's shown in menu and breadcrumbs.

 *

 * Normal menu items show up in the menu tree and can be moved/hidden by

 * the administrator. Use this for most menu items. It is the default value if

 * no menu item type is specified.

 */

define('MENU_NORMAL_ITEM', MENU_VISIBLE_IN_TREE | MENU_VISIBLE_IN_BREADCRUMB);

/**

 * Menu type -- A hidden, internal callback, typically used for API calls.

 *

 * Callbacks simply register a path so that the correct function is fired

 * when the URL is accessed. They do not appear in menus or breadcrumbs.

 */

define('MENU_CALLBACK', 0x0000);

/**

 * Menu type -- A normal menu item, hidden until enabled by an administrator.

 *

 * Modules may "suggest" menu items that the administrator may enable. They act

 * just as callbacks do until enabled, at which time they act like normal items.

 * Note for the value: 0x0010 was a flag which is no longer used, but this way

 * the values of MENU_CALLBACK and MENU_SUGGESTED_ITEM are separate.

 */

define('MENU_SUGGESTED_ITEM', MENU_VISIBLE_IN_BREADCRUMB | 0x0010);

/**

 * Menu type -- A task specific to the parent item, usually rendered as a tab.

 *

 * Local tasks are menu items that describe actions to be performed on their

 * parent item. An example is the path "node/52/edit", which performs the

 * "edit" task on "node/52".

 */

define('MENU_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_VISIBLE_IN_BREADCRUMB);

/**

 * Menu type -- The "default" local task, which is initially active.

 *

 * Every set of local tasks should provide one "default" task, that links to the

 * same path as its parent when clicked.

 */

define('MENU_DEFAULT_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_LINKS_TO_PARENT | MENU_VISIBLE_IN_BREADCRUMB);

/**

 * Menu type -- An action specific to the parent, usually rendered as a link.

 *

 * Local actions are menu items that describe actions on the parent item such

 * as adding a new user, taxonomy term, etc.

 */

define('MENU_LOCAL_ACTION', MENU_IS_LOCAL_TASK | MENU_IS_LOCAL_ACTION | MENU_VISIBLE_IN_BREADCRUMB);

/**

 * @} End of "Menu item types".

 */

/**

 * @defgroup menu_context_types Menu context types

 * @{

 * Flags for use in the "context" attribute of menu router items.

 */

/**

 * Internal menu flag: Invisible local task.

 *

 * This flag may be used for local tasks like "Delete", so custom modules and

 * themes can alter the default context and expose the task by altering menu.

 */

define('MENU_CONTEXT_NONE', 0x0000);

/**

 * Internal menu flag: Local task should be displayed in page context.

 */

define('MENU_CONTEXT_PAGE', 0x0001);

/**

 * Internal menu flag: Local task should be displayed inline.

 */

define('MENU_CONTEXT_INLINE', 0x0002);

/**

 * @} End of "Menu context types".

 */

/**

 * @defgroup menu_status_codes Menu status codes

 * @{

 * Status codes for menu callbacks.

 */

/**

 * Internal menu status code -- Menu item was found.

 */

define('MENU_FOUND', 1);

/**

 * Menu status code -- Not found.

 *

 * This can be used as the return value from a page callback, although it is

 * preferable to use a load function to accomplish this; see the hook_menu()

 * documentation for details.

 */

define('MENU_NOT_FOUND', 2);

/**

 * Menu status code -- Access denied.

 *

 * This can be used as the return value from a page callback, although it is

 * preferable to use an access callback to accomplish this; see the hook_menu()

 * documentation for details.

 */

define('MENU_ACCESS_DENIED', 3);

/**

 * Internal menu status code -- Menu item inaccessible because site is offline.

 */

define('MENU_SITE_OFFLINE', 4);

/**

 * Internal menu status code -- Everything is working fine.

 */

define('MENU_SITE_ONLINE', 5);

/**

 * @} End of "Menu status codes".

 */

/**

 * @defgroup menu_tree_parameters Menu tree parameters

 * @{

 * Parameters for a menu tree.

 */

 /**

 * The maximum number of path elements for a menu callback

 */

define('MENU_MAX_PARTS', 9);

/**

 * The maximum depth of a menu links tree - matches the number of p columns.

 */

define('MENU_MAX_DEPTH', 9);

/**

 * @} End of "Menu tree parameters".

 */

/**

 * Reserved key to identify the most specific menu link for a given path.

 *

 * The value of this constant is a hash of the constant name. We use the hash

 * so that the reserved key is over 32 characters in length and will not

 * collide with allowed menu names:

 * @code

 * sha1('MENU_PREFERRED_LINK') = 1cf698d64d1aa4b83907cf6ed55db3a7f8e92c91

 * @endcode

 *

 * @see menu_link_get_preferred()

 */

define('MENU_PREFERRED_LINK', '1cf698d64d1aa4b83907cf6ed55db3a7f8e92c91');

/**

 * Returns the ancestors (and relevant placeholders) for any given path.

 *

 * For example, the ancestors of node/12345/edit are:

 * - node/12345/edit

 * - node/12345/%

 * - node/%/edit

 * - node/%/%

 * - node/12345

 * - node/%

 * - node

 *

 * To generate these, we will use binary numbers. Each bit represents a

 * part of the path. If the bit is 1, then it represents the original

 * value while 0 means wildcard. If the path is node/12/edit/foo

 * then the 1011 bitstring represents node/%/edit/foo where % means that

 * any argument matches that part. We limit ourselves to using binary

 * numbers that correspond the patterns of wildcards of router items that

 * actually exists. This list of 'masks' is built in menu_rebuild().

 *

 * @param $parts

 *   An array of path parts; for the above example, 

 *   array('node', '12345', 'edit').

 *

 * @return

 *   An array which contains the ancestors and placeholders. Placeholders

 *   simply contain as many '%s' as the ancestors.

 */

function menu_get_ancestors($parts) {

  $number_parts = count($parts);

  $ancestors = array();

  $length =  $number_parts - 1;

  $end = (1 << $number_parts) - 1;

  $masks = variable_get('menu_masks');

  // If the optimized menu_masks array is not available use brute force to get

  // the correct $ancestors and $placeholders returned. Do not use this as the

  // default value of the menu_masks variable to avoid building such a big

  // array.

  if (!$masks) {

    $masks = range(511, 1);

  }

  // Only examine patterns that actually exist as router items (the masks).

  foreach ($masks as $i) {

    if ($i > $end) {

      // Only look at masks that are not longer than the path of interest.

      continue;

    }

    elseif ($i < (1 << $length)) {

      // We have exhausted the masks of a given length, so decrease the length.

      --$length;

    }

    $current = '';

    for ($j = $length; $j >= 0; $j--) {

      // Check the bit on the $j offset.

      if ($i & (1 << $j)) {

        // Bit one means the original value.

        $current .= $parts[$length - $j];

      }

      else {

        // Bit zero means means wildcard.

        $current .= '%';

      }

      // Unless we are at offset 0, add a slash.

      if ($j) {

        $current .= '/';

      }

    }

    $ancestors[] = $current;

  }

  return $ancestors;

}

/**

 * Unserializes menu data, using a map to replace path elements.

 *

 * The menu system stores various path-related information (such as the 'page

 * arguments' and 'access arguments' components of a menu item) in the database

 * using serialized arrays, where integer values in the arrays represent

 * arguments to be replaced by values from the path. This function first

 * unserializes such menu information arrays, and then does the path

 * replacement.

 *

 * The path replacement acts on each integer-valued element of the unserialized

 * menu data array ($data) using a map array ($map, which is typically an array

 * of path arguments) as a list of replacements. For instance, if there is an

 * element of $data whose value is the number 2, then it is replaced in $data

 * with $map[2]; non-integer values in $data are left alone.

 *

 * As an example, an unserialized $data array with elements ('node_load', 1)

 * represents instructions for calling the node_load() function. Specifically,

 * this instruction says to use the path component at index 1 as the input

 * parameter to node_load(). If the path is 'node/123', then $map will be the

 * array ('node', 123), and the returned array from this function will have

 * elements ('node_load', 123), since $map[1] is 123. This return value will

 * indicate specifically that node_load(123) is to be called to load the node

 * whose ID is 123 for this menu item.

 *

 * @param $data

 *   A serialized array of menu data, as read from the database.

 * @param $map

 *   A path argument array, used to replace integer values in $data; an integer

 *   value N in $data will be replaced by value $map[N]. Typically, the $map

 *   array is generated from a call to the arg() function.

 *

 * @return

 *   The unserialized $data array, with path arguments replaced.

 */

function menu_unserialize($data, $map) {

  if ($data = unserialize($data)) {

    foreach ($data as $k => $v) {

      if (is_int($v)) {

        $data[$k] = isset($map[$v]) ? $map[$v] : '';

      }

    }

    return $data;

  }

  else {

    return array();

  }

}

/**

 * Replaces the statically cached item for a given path.

 *

 * @param $path

 *   The path.

 * @param $router_item

 *   The router item. Usually a router entry from menu_get_item() is either

 *   modified or set to a different path. This allows the navigation block,

 *   the page title, the breadcrumb, and the page help to be modified in one

 *   call.

 */

function menu_set_item($path, $router_item) {

  menu_get_item($path, $router_item);

}

/**

 * Gets a router item.

 *

 * @param $path

 *   The path; for example, 'node/5'. The function will find the corresponding

 *   node/% item and return that. Defaults to the current path.

 * @param $router_item

 *   Internal use only.

 *

 * @return

 *   The router item or, if an error occurs in _menu_translate(), FALSE. A

 *   router item is an associative array corresponding to one row in the

 *   menu_router table. The value corresponding to the key 'map' holds the

 *   loaded objects. The value corresponding to the key 'access' is TRUE if the

 *   current user can access this page. The values corresponding to the keys

 *   'title', 'page_arguments', 'access_arguments', and 'theme_arguments' will

 *   be filled in based on the database values and the objects loaded.

 */

function menu_get_item($path = NULL, $router_item = NULL) {

  $router_items = &drupal_static(__FUNCTION__);

  if (!isset($path)) {

    $path = $_GET['q'];

  }

  if (isset($router_item)) {

    $router_items[$path] = $router_item;

  }

  if (!isset($router_items[$path])) {

    // Rebuild if we know it's needed, or if the menu masks are missing which

    // occurs rarely, likely due to a race condition of multiple rebuilds.

    if (variable_get('menu_rebuild_needed', FALSE) || !variable_get('menu_masks', array())) {

      if (_menu_check_rebuild()) {

        menu_rebuild();

      }

    }

    $original_map = arg(NULL, $path);

    $parts = array_slice($original_map, 0, MENU_MAX_PARTS);

    $ancestors = menu_get_ancestors($parts);

    $router_item = db_query_range('SELECT * FROM {menu_router} WHERE path IN (:ancestors) ORDER BY fit DESC', 0, 1, array(':ancestors' => $ancestors))->fetchAssoc();

    if ($router_item) {

      // Allow modules to alter the router item before it is translated and

      // checked for access.

      drupal_alter('menu_get_item', $router_item, $path, $original_map);

      $map = _menu_translate($router_item, $original_map);

      $router_item['original_map'] = $original_map;

      if ($map === FALSE) {

        $router_items[$path] = FALSE;

        return FALSE;

      }

      if ($router_item['access']) {

        $router_item['map'] = $map;

        $router_item['page_arguments'] = array_merge(menu_unserialize($router_item['page_arguments'], $map), array_slice($map, $router_item['number_parts']));

        $router_item['theme_arguments'] = array_merge(menu_unserialize($router_item['theme_arguments'], $map), array_slice($map, $router_item['number_parts']));

      }

    }

    $router_items[$path] = $router_item;

  }

  return $router_items[$path];

}

/**

 * Execute the page callback associated with the current path.

 *

 * @param $path

 *   The drupal path whose handler is to be be executed. If set to NULL, then

 *   the current path is used.

 * @param $deliver

 *   (optional) A boolean to indicate whether the content should be sent to the

 *   browser using the appropriate delivery callback (TRUE) or whether to return

 *   the result to the caller (FALSE).

 */

function menu_execute_active_handler($path = NULL, $deliver = TRUE) {

  // Check if site is offline.

  $page_callback_result = _menu_site_is_offline() ? MENU_SITE_OFFLINE : MENU_SITE_ONLINE;

  // Allow other modules to change the site status but not the path because that

  // would not change the global variable. hook_url_inbound_alter() can be used

  // to change the path. Code later will not use the $read_only_path variable.

  $read_only_path = !empty($path) ? $path : $_GET['q'];

  drupal_alter('menu_site_status', $page_callback_result, $read_only_path);

  // Only continue if the site status is not set.

  if ($page_callback_result == MENU_SITE_ONLINE) {

    if ($router_item = menu_get_item($path)) {

      if ($router_item['access']) {

        if ($router_item['include_file']) {

          require_once DRUPAL_ROOT . '/' . $router_item['include_file'];

        }

        $page_callback_result = call_user_func_array($router_item['page_callback'], $router_item['page_arguments']);

      }

      else {