menu.inc 119 KB
Newer Older
Dries's avatar
 
Dries committed
1
<?php
Kjartan's avatar
Kjartan committed
2

3 4 5 6 7
/**
 * @file
 * API for the Drupal menu system.
 */

8
use Drupal\Component\Utility\NestedArray;
9
use Drupal\Component\Utility\String;
10
use Drupal\Core\Cache\CacheBackendInterface;
11
use Drupal\Core\Language\Language;
12
use Drupal\Core\Routing\RequestHelper;
13
use Drupal\Core\Template\Attribute;
14
use Drupal\menu_link\Entity\MenuLink;
15
use Drupal\menu_link\MenuLinkStorageController;
16
use Symfony\Cmf\Component\Routing\RouteObjectInterface;
17 18
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
19
use Symfony\Component\Routing\Route;
20

Dries's avatar
 
Dries committed
21
/**
22
 * @defgroup menu Menu and routing system
Dries's avatar
 
Dries committed
23
 * @{
Dries's avatar
 
Dries committed
24
 * Define the navigation menus, and route page requests to code based on URLs.
Dries's avatar
 
Dries committed
25
 *
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
 * The Drupal routing system defines how Drupal responds to URLs passed to the
 * browser. The menu system, which depends on the routing system, is used for
 * navigation. The Menu module allows menus to be created in the user interface
 * as hierarchical lists of links.
 *
 * @section registering_paths Registering router paths
 * To register a path, you need to add lines similar to this in a
 * module.routing.yml file:
 * @code
 * block.admin_display:
 *   path: '/admin/structure/block'
 *   defaults:
 *     _content: '\Drupal\block\Controller\BlockListController::listing'
 *   requirements:
 *     _permission: 'administer blocks'
 * @endcode
 * @todo Add more information here, especially about controllers and what all
 *   the stuff in the routing.yml file means.
 *
 * @section Defining menu links
 * Once you have a route defined, you can use hook_menu() to define links
 * for your module's paths in the main Navigation menu or other menus. See
 * the hook_menu() documentation for more details.
 *
 * @todo The rest of this topic has not been reviewed or updated for Drupal 8.x
 *   and is not correct!
 * @todo It is quite likely that hook_menu() will be replaced with a different
 *   hook, configuration system, or plugin system before the 8.0 release.
Dries's avatar
 
Dries committed
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
 *
 * 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.
 *
Steven Wittens's avatar
Steven Wittens committed
76
 * The found callback function is called with any arguments specified
77
 * in the "page arguments" attribute of its menu item. The
Steven Wittens's avatar
Steven Wittens committed
78 79 80 81
 * 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.
Dries's avatar
 
Dries committed
82 83 84 85
 *
 * For an illustration of this process, see page_example.module.
 *
 * Access to the callback functions is also protected by the menu system.
86 87
 * The "access callback" with an optional "access arguments" of each menu
 * item is called before the page callback proceeds. If this returns TRUE,
88 89 90
 * 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.
Dries's avatar
 
Dries committed
91 92 93 94 95 96 97 98 99 100 101 102 103
 *
 * 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.
104 105 106
 *
 * Everything described so far is stored in the menu_router table. The
 * menu_links table holds the visible menu links. By default these are
107
 * derived from the same hook_menu definitions, however you are free to
108
 * add more with menu_link_save().
Dries's avatar
 
Dries committed
109 110
 */

Dries's avatar
 
Dries committed
111
/**
112
 * @defgroup menu_flags Menu flags
Dries's avatar
 
Dries committed
113
 * @{
Dries's avatar
 
Dries committed
114 115
 * Flags for use in the "type" attribute of menu items.
 */
Dries's avatar
 
Dries committed
116

117 118 119
/**
 * Internal menu flag -- menu item is the root of the menu tree.
 */
120
const MENU_IS_ROOT = 0x0001;
121 122 123 124

/**
 * Internal menu flag -- menu item is visible in the menu tree.
 */
125
const MENU_VISIBLE_IN_TREE = 0x0002;
126 127 128 129

/**
 * Internal menu flag -- menu item is visible in the breadcrumb.
 */
130
const MENU_VISIBLE_IN_BREADCRUMB = 0x0004;
131 132

/**
133
 * Internal menu flag -- menu item links back to its parent.
134
 */
135
const MENU_LINKS_TO_PARENT = 0x0008;
136 137 138 139

/**
 * Internal menu flag -- menu item can be modified by administrator.
 */
140
const MENU_MODIFIED_BY_ADMIN = 0x0020;
141 142 143 144

/**
 * Internal menu flag -- menu item was created by administrator.
 */
145
const MENU_CREATED_BY_ADMIN = 0x0040;
146 147 148 149

/**
 * Internal menu flag -- menu item is a local task.
 */
150
const MENU_IS_LOCAL_TASK = 0x0080;
Dries's avatar
 
Dries committed
151

152 153 154
/**
 * Internal menu flag -- menu item is a local action.
 */
155
const MENU_IS_LOCAL_ACTION = 0x0100;
156

Dries's avatar
 
Dries committed
157
/**
158
 * @} End of "defgroup menu_flags".
Dries's avatar
 
Dries committed
159 160 161
 */

/**
162
 * @defgroup menu_item_types Menu item types
Dries's avatar
 
Dries committed
163
 * @{
164
 * Definitions for various menu item types.
165
 *
Dries's avatar
 
Dries committed
166
 * Menu item definitions provide one of these constants, which are shortcuts for
167
 * combinations of @link menu_flags Menu flags @endlink.
Dries's avatar
 
Dries committed
168
 */
Dries's avatar
 
Dries committed
169

Dries's avatar
 
Dries committed
170
/**
171
 * Menu type -- A "normal" menu item that's shown in menus.
172
 *
Dries's avatar
 
Dries committed
173
 * Normal menu items show up in the menu tree and can be moved/hidden by
Dries's avatar
 
Dries committed
174 175
 * the administrator. Use this for most menu items. It is the default value if
 * no menu item type is specified.
Dries's avatar
 
Dries committed
176
 */
177
define('MENU_NORMAL_ITEM', MENU_VISIBLE_IN_TREE | MENU_VISIBLE_IN_BREADCRUMB);
178

Dries's avatar
 
Dries committed
179
/**
180 181
 * Menu type -- A hidden, internal callback, typically used for API calls.
 *
Dries's avatar
 
Dries committed
182
 * Callbacks simply register a path so that the correct function is fired
183
 * when the URL is accessed. They do not appear in menus.
Dries's avatar
 
Dries committed
184
 */
185
const MENU_CALLBACK = 0x0000;
Dries's avatar
 
Dries committed
186

Dries's avatar
 
Dries committed
187
/**
188 189
 * Menu type -- A normal menu item, hidden until enabled by an administrator.
 *
Dries's avatar
 
Dries committed
190 191
 * 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.
192 193
 * 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.
Dries's avatar
 
Dries committed
194
 */
195
define('MENU_SUGGESTED_ITEM', MENU_VISIBLE_IN_BREADCRUMB | 0x0010);
Dries's avatar
 
Dries committed
196 197

/**
198 199 200 201 202
 * 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".
Dries's avatar
 
Dries committed
203
 */
204
define('MENU_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_VISIBLE_IN_BREADCRUMB);
Dries's avatar
 
Dries committed
205

Dries's avatar
 
Dries committed
206
/**
207 208
 * Menu type -- The "default" local task, which is initially active.
 *
Dries's avatar
 
Dries committed
209 210 211
 * Every set of local tasks should provide one "default" task, that links to the
 * same path as its parent when clicked.
 */
212
define('MENU_DEFAULT_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_LINKS_TO_PARENT | MENU_VISIBLE_IN_BREADCRUMB);
Dries's avatar
 
Dries committed
213

214 215 216 217 218 219
/**
 * 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.
 */
220
define('MENU_LOCAL_ACTION', MENU_IS_LOCAL_TASK | MENU_IS_LOCAL_ACTION | MENU_VISIBLE_IN_BREADCRUMB);
221

222 223 224
/**
 * Menu type -- A task specific to the parent, which is never rendered.
 *
225
 * Sibling local tasks are not rendered themselves, but affect the active
226 227 228 229
 * trail and need their sibling tasks rendered as tabs.
 */
define('MENU_SIBLING_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_IS_LOCAL_ACTION | MENU_VISIBLE_IN_BREADCRUMB);

Dries's avatar
 
Dries committed
230
/**
231
 * @} End of "defgroup menu_item_types".
Dries's avatar
 
Dries committed
232 233
 */

234
/**
235
 * @defgroup menu_context_types Menu context types
236 237 238 239
 * @{
 * Flags for use in the "context" attribute of menu router items.
 */

240 241 242 243 244 245
/**
 * 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.
 */
246
const MENU_CONTEXT_NONE = 0x0000;
247

248 249 250
/**
 * Internal menu flag: Local task should be displayed in page context.
 */
251
const MENU_CONTEXT_PAGE = 0x0001;
252 253

/**
254
 * @} End of "defgroup menu_context_types".
255 256
 */

Dries's avatar
 
Dries committed
257
/**
258
 * @defgroup menu_status_codes Menu status codes
Dries's avatar
 
Dries committed
259
 * @{
Dries's avatar
 
Dries committed
260 261
 * Status codes for menu callbacks.
 */
Dries's avatar
 
Dries committed
262

263 264 265
/**
 * Internal menu status code -- Menu item was not found.
 */
266
const MENU_NOT_FOUND = 404;
267 268 269 270

/**
 * Internal menu status code -- Menu item access is denied.
 */
271
const MENU_ACCESS_DENIED = 403;
272 273 274 275

/**
 * Internal menu status code -- Menu item inaccessible because site is offline.
 */
276
const MENU_SITE_OFFLINE = 4;
Dries's avatar
 
Dries committed
277

278 279 280
/**
 * Internal menu status code -- Everything is working fine.
 */
281
const MENU_SITE_ONLINE = 5;
282

Dries's avatar
 
Dries committed
283
/**
284
 * @} End of "defgroup menu_status_codes".
Dries's avatar
 
Dries committed
285
 */
286

287
/**
288
 * @defgroup menu_tree_parameters Menu tree parameters
289
 * @{
290
 * Parameters for a menu tree.
291 292
 */

293 294
 /**
 * The maximum number of path elements for a menu callback
295
 */
296
const MENU_MAX_PARTS = 9;
297

298 299

/**
300
 * The maximum depth of a menu links tree - matches the number of p columns.
301 302 303
 *
 * @todo Move this constant to MenuLinkStorageController along with all the tree
 * functionality.
304
 */
305
const MENU_MAX_DEPTH = 9;
306

307 308

/**
309
 * @} End of "defgroup menu_tree_parameters".
310 311
 */

312 313 314 315 316 317 318 319 320 321 322 323 324 325
/**
 * 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()
 */
const MENU_PREFERRED_LINK = '1cf698d64d1aa4b83907cf6ed55db3a7f8e92c91';

326
/**
327 328 329
 * Returns the ancestors (and relevant placeholders) for any given path.
 *
 * For example, the ancestors of node/12345/edit are:
330 331 332 333 334 335 336
 * - node/12345/edit
 * - node/12345/%
 * - node/%/edit
 * - node/%/%
 * - node/12345
 * - node/%
 * - node
337 338 339 340 341
 *
 * 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
342
 * any argument matches that part. We limit ourselves to using binary
343
 * numbers that correspond the patterns of wildcards of router items that
344
 * actually exists. This list of 'masks' is built in menu_router_rebuild().
345 346 347 348
 *
 * @param $parts
 *   An array of path parts, for the above example
 *   array('node', '12345', 'edit').
349
 *
350 351
 * @return
 *   An array which contains the ancestors and placeholders. Placeholders
352
 *   simply contain as many '%s' as the ancestors.
353 354
 */
function menu_get_ancestors($parts) {
355
  $number_parts = count($parts);
356
  $ancestors = array();
357 358
  $length =  $number_parts - 1;
  $end = (1 << $number_parts) - 1;
359
  $masks = \Drupal::state()->get('menu.masks');
360
  // If the optimized menu.masks array is not available use brute force to get
361
  // the correct $ancestors and $placeholders returned. Do not use this as the
362
  // default value of the menu.masks variable to avoid building such a big
363 364 365 366
  // array.
  if (!$masks) {
    $masks = range(511, 1);
  }
367 368 369 370 371 372 373 374 375 376
  // 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;
    }
377 378
    $current = '';
    for ($j = $length; $j >= 0; $j--) {
379
      // Check the bit on the $j offset.
380
      if ($i & (1 << $j)) {
381
        // Bit one means the original value.
382 383 384
        $current .= $parts[$length - $j];
      }
      else {
385
        // Bit zero means means wildcard.
386 387
        $current .= '%';
      }
388
      // Unless we are at offset 0, add a slash.
389 390 391
      if ($j) {
        $current .= '/';
      }
Dries's avatar
 
Dries committed
392
    }
393
    $ancestors[] = $current;
394
  }
395
  return $ancestors;
Dries's avatar
 
Dries committed
396 397 398
}

/**
399
 * Unserializes menu data, using a map to replace path elements.
Dries's avatar
 
Dries committed
400
 *
401 402 403 404 405 406
 * 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.
407
 *
408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428
 * 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.
429
 *
430
 * @return
431
 *   The unserialized $data array, with path arguments replaced.
432
 */
433 434 435 436 437 438 439 440
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;
441
  }
442 443
  else {
    return array();
444 445 446
  }
}

447 448


449
/**
450
 * Replaces the statically cached item for a given path.
451
 *
452
 * @param $path
453 454
 *   The path.
 * @param $router_item
455 456
 *   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,
457
 *   the page title, the active trail, and the page help to be modified in one
458
 *   call.
459
 */
460 461 462 463 464
function menu_set_item($path, $router_item) {
  menu_get_item($path, $router_item);
}

/**
465
 * Gets a router item.
466 467
 *
 * @param $path
468
 *   The path; for example, 'node/5'. The function will find the corresponding
469 470 471
 *   node/% item and return that.
 * @param $router_item
 *   Internal use only.
472
 *
473
 * @return
474 475 476 477 478 479 480
 *   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.
481 482
 */
function menu_get_item($path = NULL, $router_item = NULL) {
483
  $router_items = &drupal_static(__FUNCTION__);
484
  if (!isset($path)) {
485
    $path = current_path();
486
  }
487 488 489
  if (isset($router_item)) {
    $router_items[$path] = $router_item;
  }
490
  if (!isset($router_items[$path])) {
491 492
    // 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.
493
    if (\Drupal::state()->get('menu_rebuild_needed') || !\Drupal::state()->get('menu.masks')) {
494
      menu_router_rebuild();
495
      \Drupal::service('router.builder')->rebuild();
496
    }
497
    $original_map = arg(NULL, $path);
498

499 500 501 502
    $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();

503
    if ($router_item) {
504 505 506 507
      // 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);

508
      $map = _menu_translate($router_item, $original_map);
509
      $router_item['original_map'] = $original_map;
510
      if ($map === FALSE) {
511
        $router_items[$path] = FALSE;
512
        return FALSE;
513
      }
514 515 516
      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']));
517
        $router_item['theme_arguments'] = array_merge(menu_unserialize($router_item['theme_arguments'], $map), array_slice($map, $router_item['number_parts']));
Dries's avatar
 
Dries committed
518 519
      }
    }
520
    $router_items[$path] = $router_item;
Dries's avatar
 
Dries committed
521
  }
522
  return $router_items[$path];
Dries's avatar
 
Dries committed
523 524
}

525
/**
526
 * Loads objects into the map as defined in the $item['load_functions'].
527
 *
528
 * @param $item
529
 *   A menu router or menu link item
530
 * @param $map
531
 *   An array of path arguments; for example, array('node', '5').
532
 *
533
 * @return
534 535
 *   Returns TRUE for success, FALSE if an object cannot be loaded.
 *   Names of object loading functions are placed in $item['load_functions'].
536
 *   Loaded objects are placed in $map[]; keys are the same as keys in the
537 538
 *   $item['load_functions'] array.
 *   $item['access'] is set to FALSE if an object cannot be loaded.
539
 */
540 541 542
function _menu_load_objects(&$item, &$map) {
  if ($load_functions = $item['load_functions']) {
    // If someone calls this function twice, then unserialize will fail.
543 544
    if (!is_array($load_functions)) {
      $load_functions = unserialize($load_functions);
545
    }
546 547 548
    $path_map = $map;
    foreach ($load_functions as $index => $function) {
      if ($function) {
549 550 551 552 553 554 555
        $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);
556
          $load_functions[$index] = $function;
557 558 559

          // Some arguments are placeholders for dynamic items to process.
          foreach ($args as $i => $arg) {
560
            if ($arg === '%index') {
561
              // Pass on argument index to the load function, so multiple
562
              // occurrences of the same placeholder can be identified.
563 564
              $args[$i] = $index;
            }
565
            if ($arg === '%map') {
566 567 568 569 570
              // 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;
            }
571 572 573
            if (is_int($arg)) {
              $args[$i] = isset($path_map[$arg]) ? $path_map[$arg] : '';
            }
574 575 576 577 578 579 580
          }
          array_unshift($args, $value);
          $return = call_user_func_array($function, $args);
        }
        else {
          $return = $function($value);
        }
581
        // If callback returned an error or there is no callback, trigger 404.
582
        if (empty($return)) {
583
          $item['access'] = FALSE;
584
          $map = FALSE;
585
          return FALSE;
586 587 588 589
        }
        $map[$index] = $return;
      }
    }
590
    $item['load_functions'] = $load_functions;
591
  }
592 593 594 595
  return TRUE;
}

/**
596
 * Checks access to a menu item using the access callback.
597 598
 *
 * @param $item
599
 *   A menu router or menu link item
600
 * @param $map
601
 *   An array of path arguments; for example, array('node', '5').
602
 *
603
 * @return
604
 *   $item['access'] becomes TRUE if the item is accessible, FALSE otherwise.
605 606
 */
function _menu_check_access(&$item, $map) {
607 608
  // Determine access callback, which will decide whether or not the current
  // user has access to this path.
609
  $callback = empty($item['access_callback']) ? 0 : trim($item['access_callback']);
610
  // Check for a TRUE or FALSE value.
611
  if (is_numeric($callback)) {
612
    $item['access'] = (bool) $callback;
Dries's avatar
 
Dries committed
613
  }
614
  else {
615
    $arguments = menu_unserialize($item['access_arguments'], $map);
616 617 618
    // 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') {
619
      $item['access'] = (count($arguments) == 1) ? user_access($arguments[0]) : user_access($arguments[0], $arguments[1]);
620
    }
621
    else {
622
      $item['access'] = call_user_func_array($callback, $arguments);
623
    }
Dries's avatar
 
Dries committed
624
  }
625
}
626

627
/**
628
 * Localizes the router item title using t() or another callback.
629
 *
630 631 632 633 634 635 636 637 638 639 640 641 642
 * Translate the title and description to allow storage of English title
 * strings in the database, yet display of them in the language required
 * by the current user.
 *
 * @param $item
 *   A menu router item or a menu link item.
 * @param $map
 *   The path as an array with objects already replaced. E.g., for path
 *   node/123 $map would be array('node', $node) where $node is the node
 *   object for node 123.
 * @param $link_translate
 *   TRUE if we are translating a menu link item; FALSE if we are
 *   translating a menu router item.
643
 *
644 645 646
 * @return
 *   No return value.
 *   $item['title'] is localized according to $item['title_callback'].
647
 *   If an item's callback is check_plain(), $item['options']['html'] becomes
648
 *   TRUE.
649 650
 *   $item['description'] is computed using $item['description_callback'] if
 *   specified; otherwise it is translated using t().
651
 *   When doing link translation and the $item['options']['attributes']['title']
652
 *   (link title attribute) matches the description, it is translated as well.
653 654
 */
function _menu_item_localize(&$item, $map, $link_translate = FALSE) {
655
  $title_callback = $item['title_callback'];
656
  $item['localized_options'] = $item['options'];
657 658 659 660 661 662 663 664
  // All 'class' attributes are assumed to be an array during rendering, but
  // links stored in the database may use an old string value.
  // @todo In order to remove this code we need to implement a database update
  //   including unserializing all existing link options and running this code
  //   on them, as well as adding validation to menu_link_save().
  if (isset($item['options']['attributes']['class']) && is_string($item['options']['attributes']['class'])) {
    $item['localized_options']['attributes']['class'] = explode(' ', $item['options']['attributes']['class']);
  }
665 666 667 668 669 670 671
  // If we are translating the title of a menu link, and its title is the same
  // as the corresponding router item, then we can use the title information
  // from the router. If it's customized, then we need to use the link title
  // itself; can't localize.
  // If we are translating a router item (tabs, page, breadcrumb), then we
  // can always use the information from the router item.
  if (!$link_translate || ($item['title'] == $item['link_title'])) {
672 673
    // t() is a special case. Since it is used very close to all the time,
    // we handle it directly instead of using indirect, slower methods.
674
    if ($title_callback == 't') {
675 676 677 678 679 680
      if (empty($item['title_arguments'])) {
        $item['title'] = t($item['title']);
      }
      else {
        $item['title'] = t($item['title'], menu_unserialize($item['title_arguments'], $map));
      }
681
    }
682
    elseif ($title_callback) {
683
      if (empty($item['title_arguments'])) {
684
        $item['title'] = $title_callback($item['title']);
685 686
      }
      else {
687
        $item['title'] = call_user_func_array($title_callback, menu_unserialize($item['title_arguments'], $map));
688
      }
689
      // Avoid calling check_plain again on l() function.
690
      if ($title_callback == 'check_plain') {
691
        $item['localized_options']['html'] = TRUE;
692
      }
693 694
    }
  }
695 696
  elseif ($link_translate) {
    $item['title'] = $item['link_title'];
697 698 699
  }

  // Translate description, see the motivation above.
700
  if (!empty($item['description'])) {
701
    $original_description = $item['description'];
702 703 704 705 706 707 708 709 710 711 712
  }
  if (!empty($item['description_arguments']) || !empty($item['description'])) {
    $description_callback = $item['description_callback'];
    // If the description callback is t(), call it directly.
    if ($description_callback == 't') {
      if (empty($item['description_arguments'])) {
        $item['description'] = t($item['description']);
      }
      else {
        $item['description'] = t($item['description'], menu_unserialize($item['description_arguments'], $map));
      }
713
    }
714 715 716 717 718 719 720 721 722 723 724 725 726 727 728
    elseif ($description_callback) {
      // If there are no arguments, call the description callback directly.
      if (empty($item['description_arguments'])) {
        $item['description'] = $description_callback($item['description']);
      }
      // Otherwise, use call_user_func_array() to pass the arguments.
      else {
        $item['description'] = call_user_func_array($description_callback, menu_unserialize($item['description_arguments'], $map));
      }
    }
  }
  // If the title and description are the same, use the translated description
  // as a localized title.
  if ($link_translate && isset($original_description) && isset($item['options']['attributes']['title']) && $item['options']['attributes']['title'] == $original_description) {
    $item['localized_options']['attributes']['title'] = $item['description'];
729
  }
730 731 732 733 734 735 736 737 738 739 740 741 742 743 744
}

/**
 * Handles dynamic path translation and menu access control.
 *
 * When a user arrives on a page such as node/5, this function determines
 * what "5" corresponds to, by inspecting the page's menu path definition,
 * node/%node. This will call node_load(5) to load the corresponding node
 * object.
 *
 * It also works in reverse, to allow the display of tabs and menu items which
 * contain these dynamic arguments, translating node/%node to node/5.
 *
 * Translation of menu item titles and descriptions are done here to
 * allow for storage of English strings in the database, and translation
745
 * to the language required to generate the current page.
746
 *
747 748
 * @param $router_item
 *   A menu router item
749
 * @param $map
750
 *   An array of path arguments; for example, array('node', '5').
751
 * @param $to_arg
752
 *   Execute $item['to_arg_functions'] or not. Use only if you want to render a
753
 *   path from the menu table, for example tabs.
754
 *
755 756
 * @return
 *   Returns the map with objects loaded as defined in the
757
 *   $item['load_functions']. $item['access'] becomes TRUE if the item is
758
 *   accessible, FALSE otherwise. $item['href'] is set according to the map.
759
 *   If an error occurs during calling the load_functions (like trying to load
760
 *   a non-existent node) then this function returns FALSE.
761
 */
762
function _menu_translate(&$router_item, $map, $to_arg = FALSE) {
763
  if ($to_arg && !empty($router_item['to_arg_functions'])) {
764 765 766 767 768
    // Fill in missing path elements, such as the current uid.
    _menu_link_map_translate($map, $router_item['to_arg_functions']);
  }
  // The $path_map saves the pieces of the path as strings, while elements in
  // $map may be replaced with loaded objects.
769
  $path_map = $map;
770
  if (!empty($router_item['load_functions']) && !_menu_load_objects($router_item, $map)) {
771
    // An error occurred loading an object.
772
    $router_item['access'] = FALSE;
773 774 775 776
    return FALSE;
  }

  // Generate the link path for the page request or local tasks.
777
  $link_map = explode('/', $router_item['path']);
778 779 780 781 782 783
  if (isset($router_item['tab_root'])) {
    $tab_root_map = explode('/', $router_item['tab_root']);
  }
  if (isset($router_item['tab_parent'])) {
    $tab_parent_map = explode('/', $router_item['tab_parent']);
  }
784
  for ($i = 0; $i < $router_item['number_parts']; $i++) {
785 786 787
    if ($link_map[$i] == '%') {
      $link_map[$i] = $path_map[$i];
    }
788 789 790 791 792 793
    if (isset($tab_root_map[$i]) && $tab_root_map[$i] == '%') {
      $tab_root_map[$i] = $path_map[$i];
    }
    if (isset($tab_parent_map[$i]) && $tab_parent_map[$i] == '%') {
      $tab_parent_map[$i] = $path_map[$i];
    }
794
  }
795
  $router_item['href'] = implode('/', $link_map);
796 797
  $router_item['tab_root_href'] = implode('/', $tab_root_map);
  $router_item['tab_parent_href'] = implode('/', $tab_parent_map);
798
  $router_item['options'] = array();
799
  if (!empty($router_item['route_name'])) {
800 801 802 803
    // Route-provided menu items do not have menu loaders, so replace the map
    // with the link map.
    $map = $link_map;

804
    $route_provider = \Drupal::getContainer()->get('router.route_provider');
805
    $route = $route_provider->getRouteByName($router_item['route_name']);
806
    $router_item['access'] = menu_item_route_access($route, $router_item['href'], $map);
807 808 809 810 811
  }
  else {
    // @todo: Remove once all routes are converted.
    _menu_check_access($router_item, $map);
  }
812

813 814 815 816
  // For performance, don't localize an item the user can't access.
  if ($router_item['access']) {
    _menu_item_localize($router_item, $map);
  }
817 818 819 820 821

  return $map;
}

/**
822
 * Translates the path elements in the map using any to_arg helper function.
823
 *
824
 * @param $map
825
 *   An array of path arguments; for example, array('node', '5').
826
 * @param $to_arg_functions
827
 *   An array of helper functions; for example, array(2 => 'menu_tail_to_arg').
828 829
 *
 * @see hook_menu()
830 831
 */
function _menu_link_map_translate(&$map, $to_arg_functions) {
832 833 834 835 836 837 838 839 840
  $to_arg_functions = unserialize($to_arg_functions);
  foreach ($to_arg_functions as $index => $function) {
    // Translate place-holders into real values.
    $arg = $function(!empty($map[$index]) ? $map[$index] : '', $map, $index);
    if (!empty($map[$index]) || isset($arg)) {
      $map[$index] = $arg;
    }
    else {
      unset($map[$index]);
841 842 843 844
    }
  }
}

845
/**
846
 * Returns a string containing the path relative to the current index.
847
 */
848 849