<?php

// $Id: menu.inc,v 1.255.2.31 2009/04/27 12:50:13 goba Exp $

/**

 * @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.

 *

 * 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. Menu items may

 * omit this attribute to use the value provided by an ancestor 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().

 */

/**

 * @name Menu flags

 * @{

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

 */

define('MENU_IS_ROOT', 0x0001);

define('MENU_VISIBLE_IN_TREE', 0x0002);

define('MENU_VISIBLE_IN_BREADCRUMB', 0x0004);

define('MENU_LINKS_TO_PARENT', 0x0008);

define('MENU_MODIFIED_BY_ADMIN', 0x0020);

define('MENU_CREATED_BY_ADMIN', 0x0040);

define('MENU_IS_LOCAL_TASK', 0x0080);

/**

 * @} End of "Menu flags".

 */

/**

 * @name Menu item types

 * @{

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

 * combinations of the above flags.

 */

/**

 * 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);

/**

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

 * when the URL is accessed. They are not shown in the menu.

 */

define('MENU_CALLBACK', MENU_VISIBLE_IN_BREADCRUMB);

/**

 * 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);

/**

 * Local tasks are rendered as tabs by default. Use this for 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);

/**

 * 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);

/**

 * @} End of "Menu item types".

 */

/**

 * @name Menu status codes

 * @{

 * Status codes for menu callbacks.

 */

define('MENU_FOUND', 1);

define('MENU_NOT_FOUND', 2);

define('MENU_ACCESS_DENIED', 3);

define('MENU_SITE_OFFLINE', 4);

/**

 * @} End of "Menu status codes".

 */

/**

 * @Name Menu tree parameters

 * @{

 * Menu tree

 */

 /**

 * The maximum number of path elements for a menu callback

 */

define('MENU_MAX_PARTS', 7);

/**

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

 */

define('MENU_MAX_DEPTH', 9);

/**

 * @} End of "Menu tree parameters".

 */

/**

 * 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);

  $placeholders = array();

  $ancestors = array();

  $length =  $number_parts - 1;

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

  $masks = variable_get('menu_masks', array());

  // 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--) {

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

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

      }

      else {

        $current .= '%';

      }

      if ($j) {

        $current .= '/';

      }

    }

    $placeholders[] = "'%s'";

    $ancestors[] = $current;

  }

  return array($ancestors, $placeholders);

}

/**

 * The menu system uses serialized arrays stored in the database for

 * arguments. However, often these need to change according to the

 * current path. This function unserializes such an array and does the

 * necessary change.

 *

 * Integer values are mapped according to the $map parameter. For

 * example, if unserialize($data) is array('view', 1) and $map is

 * array('node', '12345') then 'view' will not be changed because

 * it is not an integer, but 1 will as it is an integer. As $map[1]

 * is '12345', 1 will be replaced with '12345'. So the result will

 * be array('node_load', '12345').

 *

 * @param @data

 *   A serialized array.

 * @param @map

 *   An array of potential replacements.

 * @return

 *   The $data array unserialized and mapped.

 */

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 you take a router entry from menu_get_item and

 *   set it back either modified or to a different path. This lets you modify the

 *   navigation block, the page title, the breadcrumb and the page help in one

 *   call.

 */

function menu_set_item($path, $router_item) {

  menu_get_item($path, $router_item);

}

/**

 * Get a router item.

 *

 * @param $path

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

 *   node/% item and return that.

 * @param $router_item

 *   Internal use only.

 * @return

 *   The router item, an associate array corresponding to one row in the

 *   menu_router table. The value of key map holds the loaded objects. The

 *   value of key access is TRUE if the current user can access this page.

 *   The values for key title, page_arguments, access_arguments will be

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

 */

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

  static $router_items;

  if (!isset($path)) {

    $path = $_GET['q'];

  }

  if (isset($router_item)) {

    $router_items[$path] = $router_item;

  }

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

    $original_map = arg(NULL, $path);

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

    list($ancestors, $placeholders) = menu_get_ancestors($parts);

    if ($router_item = db_fetch_array(db_query_range('SELECT * FROM {menu_router} WHERE path IN ('. implode (',', $placeholders) .') ORDER BY fit DESC', $ancestors, 0, 1))) {

      $map = _menu_translate($router_item, $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_items[$path] = $router_item;

  }

  return $router_items[$path];

}

/**

 * Execute the page callback associated with the current path

 */

function menu_execute_active_handler($path = NULL) {

  if (_menu_site_is_offline()) {

    return MENU_SITE_OFFLINE;

  }

  // 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())) {

    menu_rebuild();

  }

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

    if ($router_item['access']) {

      if ($router_item['file']) {

        require_once($router_item['file']);

      }

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

    }

    else {

      return MENU_ACCESS_DENIED;

    }

  }

  return MENU_NOT_FOUND;

}

/**

 * Loads objects into the map as defined in the $item['load_functions'].

 *

 * @param $item

 *   A menu router or menu link item

 * @param $map

 *   An array of path arguments (ex: array('node', '5'))

 * @return

 *   Returns TRUE for success, FALSE if an object cannot be loaded.

 *   Names of object loading functions are placed in $item['load_functions'].

 *   Loaded objects are placed in $map[]; keys are the same as keys in the

 *   $item['load_functions'] array.

 *   $item['access'] is set to FALSE if an object cannot be loaded.

 */

function _menu_load_objects(&$item, &$map) {

  if ($load_functions = $item['load_functions']) {

    // If someone calls this function twice, then unserialize will fail.

    if ($load_functions_unserialized = unserialize($load_functions)) {

      $load_functions = $load_functions_unserialized;

    }

    $path_map = $map;

    foreach ($load_functions as $index => $function) {

      if ($function) {

        $value = isset($path_map[$index]) ? $path_map[$index] : '';

        if (is_array($function)) {

          // Set up arguments for the load function. These were pulled from

          // 'load arguments' in the hook_menu() entry, but they need

          // some processing. In this case the $function is the key to the

          // load_function array, and the value is the list of arguments.

          list($function, $args) = each($function);

          $load_functions[$index] = $function;

          // Some arguments are placeholders for dynamic items to process.

          foreach ($args as $i => $arg) {

            if ($arg === '%index') {

              // Pass on argument index to the load function, so multiple

              // occurances of the same placeholder can be identified.

              $args[$i] = $index;

            }

            if ($arg === '%map') {

              // Pass on menu map by reference. The accepting function must

              // also declare this as a reference if it wants to modify

              // the map.

              $args[$i] = &$map;

            }

            if (is_int($arg)) {

              $args[$i] = isset($path_map[$arg]) ? $path_map[$arg] : '';

            }

          }

          array_unshift($args, $value);

          $return = call_user_func_array($function, $args);

        }

        else {

          $return = $function($value);

        }

        // If callback returned an error or there is no callback, trigger 404.

        if ($return === FALSE) {

          $item['access'] = FALSE;

          $map = FALSE;

          return FALSE;

        }

        $map[$index] = $return;

      }

    }

    $item['load_functions'] = $load_functions;

  }

  return TRUE;

}

/**

 * Check access to a menu item using the access callback

 *

 * @param $item

 *   A menu router or menu link item

 * @param $map

 *   An array of path arguments (ex: array('node', '5'))

 * @return

 *   $item['access'] becomes TRUE if the item is accessible, FALSE otherwise.

 */

function _menu_check_access(&$item, $map) {

  // Determine access callback, which will decide whether or not the current

  // user has access to this path.

  $callback = empty($item['access_callback']) ? 0 : trim($item['access_callback']);

  // Check for a TRUE or FALSE value.

  if (is_numeric($callback)) {

    $item['access'] = (bool)$callback;

  }

  else {

    $arguments = menu_unserialize($item['access_arguments'], $map);

    // As call_user_func_array is quite slow and user_access is a very common

    // callback, it is worth making a special case for it.

    if ($callback == 'user_access') {

      $item['access'] = (count($arguments) == 1) ? user_access($arguments[0]) : user_access($arguments[0], $arguments[1]);