menu.inc 113 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\Cache;
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

Dries's avatar
 
Dries committed
152
/**
153
 * @} End of "defgroup menu_flags".
Dries's avatar
 
Dries committed
154 155 156
 */

/**
157
 * @defgroup menu_item_types Menu item types
Dries's avatar
 
Dries committed
158
 * @{
159
 * Definitions for various menu item types.
160
 *
Dries's avatar
 
Dries committed
161
 * Menu item definitions provide one of these constants, which are shortcuts for
162
 * combinations of @link menu_flags Menu flags @endlink.
Dries's avatar
 
Dries committed
163
 */
Dries's avatar
 
Dries committed
164

Dries's avatar
 
Dries committed
165
/**
166
 * Menu type -- A "normal" menu item that's shown in menus.
167
 *
Dries's avatar
 
Dries committed
168
 * Normal menu items show up in the menu tree and can be moved/hidden by
Dries's avatar
 
Dries committed
169 170
 * 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
171
 */
172
define('MENU_NORMAL_ITEM', MENU_VISIBLE_IN_TREE | MENU_VISIBLE_IN_BREADCRUMB);
173

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

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

/**
193 194 195 196 197
 * 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
198
 */
199
define('MENU_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_VISIBLE_IN_BREADCRUMB);
Dries's avatar
 
Dries committed
200

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

209 210 211
/**
 * Menu type -- A task specific to the parent, which is never rendered.
 *
212
 * Sibling local tasks are not rendered themselves, but affect the active
213 214
 * trail and need their sibling tasks rendered as tabs.
 */
215
define('MENU_SIBLING_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_VISIBLE_IN_BREADCRUMB);
216

Dries's avatar
 
Dries committed
217
/**
218
 * @} End of "defgroup menu_item_types".
Dries's avatar
 
Dries committed
219 220
 */

221
/**
222
 * @defgroup menu_context_types Menu context types
223 224 225 226
 * @{
 * Flags for use in the "context" attribute of menu router items.
 */

227 228 229 230 231 232
/**
 * 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.
 */
233
const MENU_CONTEXT_NONE = 0x0000;
234

235 236 237
/**
 * Internal menu flag: Local task should be displayed in page context.
 */
238
const MENU_CONTEXT_PAGE = 0x0001;
239 240

/**
241
 * @} End of "defgroup menu_context_types".
242 243
 */

Dries's avatar
 
Dries committed
244
/**
245
 * @defgroup menu_status_codes Menu status codes
Dries's avatar
 
Dries committed
246
 * @{
Dries's avatar
 
Dries committed
247 248
 * Status codes for menu callbacks.
 */
Dries's avatar
 
Dries committed
249

250 251 252
/**
 * Internal menu status code -- Menu item was not found.
 */
253
const MENU_NOT_FOUND = 404;
254 255 256 257

/**
 * Internal menu status code -- Menu item access is denied.
 */
258
const MENU_ACCESS_DENIED = 403;
259 260 261 262

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

265 266 267
/**
 * Internal menu status code -- Everything is working fine.
 */
268
const MENU_SITE_ONLINE = 5;
269

Dries's avatar
 
Dries committed
270
/**
271
 * @} End of "defgroup menu_status_codes".
Dries's avatar
 
Dries committed
272
 */
273

274
/**
275
 * @defgroup menu_tree_parameters Menu tree parameters
276
 * @{
277
 * Parameters for a menu tree.
278 279
 */

280 281
 /**
 * The maximum number of path elements for a menu callback
282
 */
283
const MENU_MAX_PARTS = 9;
284

285 286

/**
287
 * The maximum depth of a menu links tree - matches the number of p columns.
288 289 290
 *
 * @todo Move this constant to MenuLinkStorageController along with all the tree
 * functionality.
291
 */
292
const MENU_MAX_DEPTH = 9;
293

294 295

/**
296
 * @} End of "defgroup menu_tree_parameters".
297 298
 */

299 300 301 302 303 304 305 306 307 308 309 310 311 312
/**
 * 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';

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

/**
386
 * Unserializes menu data, using a map to replace path elements.
Dries's avatar
 
Dries committed
387
 *
388 389 390 391 392 393
 * 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.
394
 *
395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415
 * 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.
416
 *
417
 * @return
418
 *   The unserialized $data array, with path arguments replaced.
419
 */
420 421 422 423 424 425 426 427
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;
428
  }
429 430
  else {
    return array();
431 432 433
  }
}

434 435


436
/**
437
 * Replaces the statically cached item for a given path.
438
 *
439
 * @param $path
440 441
 *   The path.
 * @param $router_item
442 443
 *   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,
444
 *   the page title, the active trail, and the page help to be modified in one
445
 *   call.
446
 */
447 448 449 450 451
function menu_set_item($path, $router_item) {
  menu_get_item($path, $router_item);
}

/**
452
 * Gets a router item.
453 454
 *
 * @param $path
455
 *   The path; for example, 'node/5'. The function will find the corresponding
456 457 458
 *   node/% item and return that.
 * @param $router_item
 *   Internal use only.
459
 *
460
 * @return
461 462 463 464 465
 *   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
466 467
 *   'title', 'page_arguments', and 'access_arguments', will be filled in based
 *   on the database values and the objects loaded.
468 469
 */
function menu_get_item($path = NULL, $router_item = NULL) {
470
  $router_items = &drupal_static(__FUNCTION__);
471
  if (!isset($path)) {
472
    $path = current_path();
473
  }
474 475 476
  if (isset($router_item)) {
    $router_items[$path] = $router_item;
  }
477
  if (!isset($router_items[$path])) {
478
    \Drupal::service('router.builder')->rebuildIfNeeded();
479
    $original_map = arg(NULL, $path);
480

481 482 483 484
    $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();

485
    if ($router_item) {
486 487 488 489
      // 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);

490
      $map = _menu_translate($router_item, $original_map);
491
      $router_item['original_map'] = $original_map;
492
      if ($map === FALSE) {
493
        $router_items[$path] = FALSE;
494
        return FALSE;
495
      }
496 497 498
      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']));
Dries's avatar
 
Dries committed
499 500
      }
    }
501
    $router_items[$path] = $router_item;
Dries's avatar
 
Dries committed
502
  }
503
  return $router_items[$path];
Dries's avatar
 
Dries committed
504 505
}

506
/**
507
 * Loads objects into the map as defined in the $item['load_functions'].
508
 *
509
 * @param $item
510
 *   A menu router or menu link item
511
 * @param $map
512
 *   An array of path arguments; for example, array('node', '5').
513
 *
514
 * @return
515 516
 *   Returns TRUE for success, FALSE if an object cannot be loaded.
 *   Names of object loading functions are placed in $item['load_functions'].
517
 *   Loaded objects are placed in $map[]; keys are the same as keys in the
518 519
 *   $item['load_functions'] array.
 *   $item['access'] is set to FALSE if an object cannot be loaded.
520
 */
521 522 523
function _menu_load_objects(&$item, &$map) {
  if ($load_functions = $item['load_functions']) {
    // If someone calls this function twice, then unserialize will fail.
524 525
    if (!is_array($load_functions)) {
      $load_functions = unserialize($load_functions);
526
    }
527 528 529
    $path_map = $map;
    foreach ($load_functions as $index => $function) {
      if ($function) {
530 531 532 533 534 535 536
        $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);
537
          $load_functions[$index] = $function;
538 539 540

          // Some arguments are placeholders for dynamic items to process.
          foreach ($args as $i => $arg) {
541
            if ($arg === '%index') {
542
              // Pass on argument index to the load function, so multiple
543
              // occurrences of the same placeholder can be identified.
544 545
              $args[$i] = $index;
            }
546
            if ($arg === '%map') {
547 548 549 550 551
              // 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;
            }
552 553 554
            if (is_int($arg)) {
              $args[$i] = isset($path_map[$arg]) ? $path_map[$arg] : '';
            }
555 556 557 558 559 560 561
          }
          array_unshift($args, $value);
          $return = call_user_func_array($function, $args);
        }
        else {
          $return = $function($value);
        }
562
        // If callback returned an error or there is no callback, trigger 404.
563
        if (empty($return)) {
564
          $item['access'] = FALSE;
565
          $map = FALSE;
566
          return FALSE;
567 568 569 570
        }
        $map[$index] = $return;
      }
    }
571
    $item['load_functions'] = $load_functions;
572
  }
573 574 575 576
  return TRUE;
}

/**
577
 * Checks access to a menu item using the access callback.
578 579
 *
 * @param $item
580
 *   A menu router or menu link item
581
 * @param $map
582
 *   An array of path arguments; for example, array('node', '5').
583
 *
584
 * @return
585
 *   $item['access'] becomes TRUE if the item is accessible, FALSE otherwise.
586 587
 */
function _menu_check_access(&$item, $map) {
588 589
  // Determine access callback, which will decide whether or not the current
  // user has access to this path.
590
  $callback = empty($item['access_callback']) ? 0 : trim($item['access_callback']);
591
  // Check for a TRUE or FALSE value.
592
  if (is_numeric($callback)) {
593
    $item['access'] = (bool) $callback;
Dries's avatar
 
Dries committed
594
  }
595
  else {
596
    $arguments = menu_unserialize($item['access_arguments'], $map);
597 598 599
    // 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') {
600
      $item['access'] = (count($arguments) == 1) ? user_access($arguments[0]) : user_access($arguments[0], $arguments[1]);
601
    }
602
    else {
603
      $item['access'] = call_user_func_array($callback, $arguments);
604
    }
Dries's avatar
 
Dries committed
605
  }
606
}
607

608
/**
609
 * Localizes the router item title using t() or another callback.
610
 *
611 612 613 614 615 616 617 618 619 620 621 622 623
 * 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.
624
 *
625 626 627
 * @return
 *   No return value.
 *   $item['title'] is localized according to $item['title_callback'].
628
 *   If an item's callback is check_plain(), $item['options']['html'] becomes
629
 *   TRUE.
630 631
 *   $item['description'] is computed using $item['description_callback'] if
 *   specified; otherwise it is translated using t().
632
 *   When doing link translation and the $item['options']['attributes']['title']
633
 *   (link title attribute) matches the description, it is translated as well.
634 635
 */
function _menu_item_localize(&$item, $map, $link_translate = FALSE) {
636
  $title_callback = $item['title_callback'];
637
  $item['localized_options'] = $item['options'];
638 639 640 641 642 643 644 645
  // 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']);
  }
646 647 648 649 650 651
  // 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.
652
  if (!$link_translate || !isset($item['link_title']) || ($item['title'] == $item['link_title'])) {
653 654
    // 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.
655
    if ($title_callback == 't') {
656 657 658 659 660 661
      if (empty($item['title_arguments'])) {
        $item['title'] = t($item['title']);
      }
      else {
        $item['title'] = t($item['title'], menu_unserialize($item['title_arguments'], $map));
      }
662
    }
663
    elseif ($title_callback) {
664
      if (empty($item['title_arguments'])) {
665
        $item['title'] = $title_callback($item['title']);
666 667
      }
      else {
668
        $item['title'] = call_user_func_array($title_callback, menu_unserialize($item['title_arguments'], $map));
669
      }
670
      // Avoid calling check_plain again on l() function.
671
      if ($title_callback == 'check_plain') {
672
        $item['localized_options']['html'] = TRUE;
673
      }
674 675
    }
  }
676 677
  elseif ($link_translate) {
    $item['title'] = $item['link_title'];
678 679 680
  }

  // Translate description, see the motivation above.
681
  if (!empty($item['description'])) {
682
    $original_description = $item['description'];
683 684 685 686 687 688 689 690 691 692 693
  }
  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));
      }
694
    }
695 696 697 698 699 700 701 702 703 704 705 706 707 708 709
    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'];
710
  }
711 712 713 714 715 716 717 718 719 720 721 722 723 724 725
}

/**
 * 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
726
 * to the language required to generate the current page.
727
 *
728 729
 * @param $router_item
 *   A menu router item
730
 * @param $map
731
 *   An array of path arguments; for example, array('node', '5').
732
 * @param $to_arg
733
 *   Execute $item['to_arg_functions'] or not. Use only if you want to render a
734
 *   path from the menu table, for example tabs.
735
 *
736 737
 * @return
 *   Returns the map with objects loaded as defined in the
738
 *   $item['load_functions']. $item['access'] becomes TRUE if the item is
739
 *   accessible, FALSE otherwise. $item['href'] is set according to the map.
740
 *   If an error occurs during calling the load_functions (like trying to load
741
 *   a non-existent node) then this function returns FALSE.
742
 */
743
function _menu_translate(&$router_item, $map, $to_arg = FALSE) {
744
  if ($to_arg && !empty($router_item['to_arg_functions'])) {
745 746 747 748 749
    // 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.
750
  $path_map = $map;
751
  if (!empty($router_item['load_functions']) && !_menu_load_objects($router_item, $map)) {
752
    // An error occurred loading an object.
753
    $router_item['access'] = FALSE;
754 755
    return FALSE;
  }
756 757 758 759
  // Avoid notices until we remove this function.
  // @see https://drupal.org/node/2107533
  $tab_root_map = array();
  $tab_parent_map = array();
760
  // Generate the link path for the page request or local tasks.
761
  $link_map = explode('/', $router_item['path']);
762 763 764 765 766 767
  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']);
  }
768
  for ($i = 0; $i < $router_item['number_parts']; $i++) {
769 770 771
    if ($link_map[$i] == '%') {
      $link_map[$i] = $path_map[$i];
    }
772 773 774 775 776 777
    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];
    }
778
  }
779
  $router_item['href'] = implode('/', $link_map);
780 781
  $router_item['tab_root_href'] = implode('/', $tab_root_map);
  $router_item['tab_parent_href'] = implode('/', $tab_parent_map);
782
  $router_item['options'] = array();
783
  if (!empty($router_item['route_name'])) {
784 785 786 787
    // Route-provided menu items do not have menu loaders, so replace the map
    // with the link map.
    $map = $link_map;

788
    $route_provider = \Drupal::getContainer()->get('router.route_provider');
789
    $route = $route_provider->getRouteByName($router_item['route_name']);
790
    $router_item['access'] = menu_item_route_access($route, $router_item['href'], $map);
791 792 793 794 795
  }
  else {
    // @todo: Remove once all routes are converted.
    _menu_check_access($router_item, $map);
  }
796

797 798 799 800
  // For performance, don't localize an item the user can't access.
  if ($router_item['access']) {
    _menu_item_localize($router_item, $map);
  }
801 802 803 804 805

  return $map;
}

/**
806
 * Translates the path elements in the map using any to_arg helper function.
807
 *
808
 * @param $map
809
 *   An array of path arguments; for example, array('node', '5').
810
 * @param $to_arg_functions
811
 *   An array of helper functions; for example, array(2 => 'menu_tail_to_arg').
812 813
 *
 * @see hook_menu()
814 815
 */
function _menu_link_map_translate(&$map, $to_arg_functions) {
816 817 818 819 820 821 822 823 824
  $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]);
825 826 827 828
    }
  }
}

829
/**
830
 * Returns a string containing the path relative to the current index.
831
 */
832 833 834 835
function menu_tail_to_arg($arg, $map, $index) {
  return implode('/', array_slice($map, $index));
}

836
/**
837
 * Loads the path as one string relative to the current index.
838 839 840 841 842 843 844 845 846 847 848 849 850 851 852
 *
 * To use this load function, you must specify the load arguments
 * in the router item as:
 * @code
 * $item['load arguments'] = array('%map', '%index');
 * @endcode
 *
 * @see search_menu().
 */
function menu_tail_load($arg, &$map, $index) {
  $arg = implode('/', array_slice($map, $index));
  $map = array_slice($map, 0, $index);
  return $arg;
}

853
/**
854
 * Provides menu link unserializing, access control, and argument handling.
855 856 857
 *
 * This function is similar to _menu_translate(), but it also does
 * link-specific preparation (such as always calling to_arg() functions).
858
 *
859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874
 * @param array $item
 *   The passed in item has the following keys:
 *   - access: (optional) Becomes TRUE if the item is accessible, FALSE
 *     otherwise. If the key is not set, the access manager is used to
 *     determine the access.
 *   - options: (required) Is unserialized and copied to $item['localized_options'].
 *   - link_title: (required) The title of the menu link.
 *   - route_name: (required) The route name of the menu link.
 *   - route_parameters: (required) The unserialized route parameters of the menu link.
 *   The passed in item is changed by the following keys:
 *   - href: The actual path to the link. This path is generated from the
 *     link_path of the menu link entity.
 *   - title: The title of the link. This title is generated from the
 *     link_title of the menu link entity.
 */
function _menu_link_translate(&$item) {
875
  if (!is_array($item['options'])) {
876
    $item['options'] = (array) unserialize($item['options']);
877
  }
878 879 880
  $item['localized_options'] = $item['options'];
  $item['title'] = $item['link_title'];
  if ($item['external'] || empty($item['route_name'])) {
881 882
    $item['access'] = 1;
    $item['href'] = $item['link_path'];
883 884 885
    $item['route_parameters'] = array();
    // Set to NULL so that drupal_pre_render_link() is certain to skip it.
    $item['route_name'] = NULL;
886 887
  }
  else {
888 889 890
    $item['href'] = NULL;
    if (!is_array($item['route_parameters'])) {
      $item['route_parameters'] = (array) unserialize($item['route_parameters']);