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

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

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

Dries Buytaert's avatar
   
Dries Buytaert committed
19
20
21
/**
 * @defgroup menu Menu system
 * @{
Dries Buytaert's avatar
   
Dries Buytaert committed
22
 * Define the navigation menus, and route page requests to code based on URLs.
Dries Buytaert's avatar
   
Dries Buytaert committed
23
24
25
26
 *
 * 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
27
28
29
30
 * 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.
Dries Buytaert's avatar
   
Dries Buytaert committed
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 *
 * 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
53
 * The found callback function is called with any arguments specified
54
 * in the "page arguments" attribute of its menu item. The
Steven Wittens's avatar
Steven Wittens committed
55
56
57
58
 * 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 Buytaert's avatar
   
Dries Buytaert committed
59
60
61
62
 *
 * For an illustration of this process, see page_example.module.
 *
 * Access to the callback functions is also protected by the menu system.
63
64
 * The "access callback" with an optional "access arguments" of each menu
 * item is called before the page callback proceeds. If this returns TRUE,
65
66
67
 * 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 Buytaert's avatar
   
Dries Buytaert committed
68
69
70
71
72
73
74
75
76
77
78
79
80
 *
 * 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.
81
82
83
 *
 * Everything described so far is stored in the menu_router table. The
 * menu_links table holds the visible menu links. By default these are
84
 * derived from the same hook_menu definitions, however you are free to
85
 * add more with menu_link_save().
Dries Buytaert's avatar
   
Dries Buytaert committed
86
87
 */

Dries Buytaert's avatar
   
Dries Buytaert committed
88
/**
89
 * @defgroup menu_flags Menu flags
Dries Buytaert's avatar
   
Dries Buytaert committed
90
 * @{
Dries Buytaert's avatar
   
Dries Buytaert committed
91
92
 * Flags for use in the "type" attribute of menu items.
 */
Dries Buytaert's avatar
   
Dries Buytaert committed
93

94
95
96
/**
 * Internal menu flag -- menu item is the root of the menu tree.
 */
97
const MENU_IS_ROOT = 0x0001;
98
99
100
101

/**
 * Internal menu flag -- menu item is visible in the menu tree.
 */
102
const MENU_VISIBLE_IN_TREE = 0x0002;
103
104
105
106

/**
 * Internal menu flag -- menu item is visible in the breadcrumb.
 */
107
const MENU_VISIBLE_IN_BREADCRUMB = 0x0004;
108
109

/**
110
 * Internal menu flag -- menu item links back to its parent.
111
 */
112
const MENU_LINKS_TO_PARENT = 0x0008;
113
114
115
116

/**
 * Internal menu flag -- menu item can be modified by administrator.
 */
117
const MENU_MODIFIED_BY_ADMIN = 0x0020;
118
119
120
121

/**
 * Internal menu flag -- menu item was created by administrator.
 */
122
const MENU_CREATED_BY_ADMIN = 0x0040;
123
124
125
126

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

129
130
131
/**
 * Internal menu flag -- menu item is a local action.
 */
132
const MENU_IS_LOCAL_ACTION = 0x0100;
133

Dries Buytaert's avatar
   
Dries Buytaert committed
134
/**
135
 * @} End of "defgroup menu_flags".
Dries Buytaert's avatar
   
Dries Buytaert committed
136
137
138
 */

/**
139
 * @defgroup menu_item_types Menu item types
Dries Buytaert's avatar
   
Dries Buytaert committed
140
 * @{
141
 * Definitions for various menu item types.
142
 *
Dries Buytaert's avatar
   
Dries Buytaert committed
143
 * Menu item definitions provide one of these constants, which are shortcuts for
144
 * combinations of @link menu_flags Menu flags @endlink.
Dries Buytaert's avatar
   
Dries Buytaert committed
145
 */
Dries Buytaert's avatar
   
Dries Buytaert committed
146

Dries Buytaert's avatar
   
Dries Buytaert committed
147
/**
148
149
 * Menu type -- A "normal" menu item that's shown in menu and breadcrumbs.
 *
Dries Buytaert's avatar
   
Dries Buytaert committed
150
 * Normal menu items show up in the menu tree and can be moved/hidden by
Dries Buytaert's avatar
   
Dries Buytaert committed
151
152
 * the administrator. Use this for most menu items. It is the default value if
 * no menu item type is specified.
Dries Buytaert's avatar
   
Dries Buytaert committed
153
 */
154
define('MENU_NORMAL_ITEM', MENU_VISIBLE_IN_TREE | MENU_VISIBLE_IN_BREADCRUMB);
155

Dries Buytaert's avatar
   
Dries Buytaert committed
156
/**
157
158
 * Menu type -- A hidden, internal callback, typically used for API calls.
 *
Dries Buytaert's avatar
   
Dries Buytaert committed
159
 * Callbacks simply register a path so that the correct function is fired
160
 * when the URL is accessed. They do not appear in menus or breadcrumbs.
Dries Buytaert's avatar
   
Dries Buytaert committed
161
 */
162
const MENU_CALLBACK = 0x0000;
Dries Buytaert's avatar
 
Dries Buytaert committed
163

Dries Buytaert's avatar
   
Dries Buytaert committed
164
/**
165
166
 * Menu type -- A normal menu item, hidden until enabled by an administrator.
 *
Dries Buytaert's avatar
   
Dries Buytaert committed
167
168
 * 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.
169
170
 * 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 Buytaert's avatar
   
Dries Buytaert committed
171
 */
172
define('MENU_SUGGESTED_ITEM', MENU_VISIBLE_IN_BREADCRUMB | 0x0010);
Dries Buytaert's avatar
   
Dries Buytaert committed
173
174

/**
175
176
177
178
179
 * 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 Buytaert's avatar
   
Dries Buytaert committed
180
 */
181
define('MENU_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_VISIBLE_IN_BREADCRUMB);
Dries Buytaert's avatar
   
Dries Buytaert committed
182

Dries Buytaert's avatar
   
Dries Buytaert committed
183
/**
184
185
 * Menu type -- The "default" local task, which is initially active.
 *
Dries Buytaert's avatar
   
Dries Buytaert committed
186
187
188
 * Every set of local tasks should provide one "default" task, that links to the
 * same path as its parent when clicked.
 */
189
define('MENU_DEFAULT_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_LINKS_TO_PARENT | MENU_VISIBLE_IN_BREADCRUMB);
Dries Buytaert's avatar
   
Dries Buytaert committed
190

191
192
193
194
195
196
/**
 * 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.
 */
197
define('MENU_LOCAL_ACTION', MENU_IS_LOCAL_TASK | MENU_IS_LOCAL_ACTION | MENU_VISIBLE_IN_BREADCRUMB);
198

199
200
201
202
203
204
205
206
/**
 * Menu type -- A task specific to the parent, which is never rendered.
 *
 * Sibling local tasks are not rendered themselves, but affect the breadcrumb
 * 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 Buytaert's avatar
   
Dries Buytaert committed
207
/**
208
 * @} End of "defgroup menu_item_types".
Dries Buytaert's avatar
   
Dries Buytaert committed
209
210
 */

211
/**
212
 * @defgroup menu_context_types Menu context types
213
214
215
216
 * @{
 * Flags for use in the "context" attribute of menu router items.
 */

217
218
219
220
221
222
/**
 * 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.
 */
223
const MENU_CONTEXT_NONE = 0x0000;
224

225
226
227
/**
 * Internal menu flag: Local task should be displayed in page context.
 */
228
const MENU_CONTEXT_PAGE = 0x0001;
229
230
231
232

/**
 * Internal menu flag: Local task should be displayed inline.
 */
233
const MENU_CONTEXT_INLINE = 0x0002;
234
235

/**
236
 * @} End of "defgroup menu_context_types".
237
238
 */

Dries Buytaert's avatar
   
Dries Buytaert committed
239
/**
240
 * @defgroup menu_status_codes Menu status codes
Dries Buytaert's avatar
   
Dries Buytaert committed
241
 * @{
Dries Buytaert's avatar
   
Dries Buytaert committed
242
243
 * Status codes for menu callbacks.
 */
Dries Buytaert's avatar
   
Dries Buytaert committed
244

245
246
247
/**
 * Internal menu status code -- Menu item was not found.
 */
248
const MENU_NOT_FOUND = 404;
249
250
251
252

/**
 * Internal menu status code -- Menu item access is denied.
 */
253
const MENU_ACCESS_DENIED = 403;
254
255
256
257

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

260
261
262
/**
 * Internal menu status code -- Everything is working fine.
 */
263
const MENU_SITE_ONLINE = 5;
264

Dries Buytaert's avatar
   
Dries Buytaert committed
265
/**
266
 * @} End of "defgroup menu_status_codes".
Dries Buytaert's avatar
   
Dries Buytaert committed
267
 */
268

269
/**
270
 * @defgroup menu_tree_parameters Menu tree parameters
271
 * @{
272
 * Parameters for a menu tree.
273
274
 */

275
276
 /**
 * The maximum number of path elements for a menu callback
277
 */
278
const MENU_MAX_PARTS = 9;
279

280
281

/**
282
 * The maximum depth of a menu links tree - matches the number of p columns.
283
284
285
 *
 * @todo Move this constant to MenuLinkStorageController along with all the tree
 * functionality.
286
 */
287
const MENU_MAX_DEPTH = 9;
288

289
290

/**
291
 * @} End of "defgroup menu_tree_parameters".
292
293
 */

294
295
296
297
298
299
300
301
302
303
304
305
306
307
/**
 * 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';

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

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

429
430


431
/**
432
 * Replaces the statically cached item for a given path.
433
 *
434
 * @param $path
435
436
 *   The path.
 * @param $router_item
437
438
439
 *   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
440
 *   call.
441
 */
442
443
444
445
446
function menu_set_item($path, $router_item) {
  menu_get_item($path, $router_item);
}

/**
447
 * Gets a router item.
448
449
 *
 * @param $path
450
 *   The path; for example, 'node/5'. The function will find the corresponding
451
452
453
 *   node/% item and return that.
 * @param $router_item
 *   Internal use only.
454
 *
455
 * @return
456
457
458
459
460
461
462
 *   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.
463
464
 */
function menu_get_item($path = NULL, $router_item = NULL) {
465
  $router_items = &drupal_static(__FUNCTION__);
466
  if (!isset($path)) {
467
    $path = current_path();
468
  }
469
470
471
  if (isset($router_item)) {
    $router_items[$path] = $router_item;
  }
472
  if (!isset($router_items[$path])) {
473
474
    // 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.
475
    if (Drupal::state()->get('menu_rebuild_needed') || !Drupal::state()->get('menu.masks')) {
476
      menu_router_rebuild();
477
    }
478
    $original_map = arg(NULL, $path);
479

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

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

489
      $map = _menu_translate($router_item, $original_map);
490
      $router_item['original_map'] = $original_map;
491
      if ($map === FALSE) {
492
        $router_items[$path] = FALSE;
493
        return FALSE;
494
      }
495
496
497
      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']));
498
        $router_item['theme_arguments'] = array_merge(menu_unserialize($router_item['theme_arguments'], $map), array_slice($map, $router_item['number_parts']));
Dries Buytaert's avatar
   
Dries Buytaert committed
499
500
      }
    }
501
    $router_items[$path] = $router_item;
Dries Buytaert's avatar
   
Dries Buytaert committed
502
  }
503
  return $router_items[$path];
Dries Buytaert's avatar
   
Dries Buytaert 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 Buytaert's avatar
   
Dries Buytaert 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 Buytaert's avatar
   
Dries Buytaert 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
652
  // 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'])) {
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
756
757
    return FALSE;
  }

  // Generate the link path for the page request or local tasks.
758
  $link_map = explode('/', $router_item['path']);
759
760
761
762
763
764
  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']);
  }
765
  for ($i = 0; $i < $router_item['number_parts']; $i++) {
766
767
768
    if ($link_map[$i] == '%') {
      $link_map[$i] = $path_map[$i];
    }
769
770
771
772
773
774
    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];
    }
775
  }
776
  $router_item['href'] = implode('/', $link_map);
777
778
  $router_item['tab_root_href'] = implode('/', $tab_root_map);
  $router_item['tab_parent_href'] = implode('/', $tab_parent_map);
779
  $router_item['options'] = array();
780
  if (!empty($router_item['route_name'])) {
781
782
783
784
    // Route-provided menu items do not have menu loaders, so replace the map
    // with the link map.
    $map = $link_map;

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

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

  return $map;
}

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

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

833
/**
834
 * Loads the path as one string relative to the current index.
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
 *
 * 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;
}

850
/**
851
852
853
854
 * Provides menu link access control, translation, and argument handling.
 *
 * This function is similar to _menu_translate(), but it also does
 * link-specific preparation (such as always calling to_arg() functions).
855
856
 *
 * @param $item
857
858
859
860
861
 *   A menu link.
 * @param $translate
 *   (optional) Whether to try to translate a link containing dynamic path
 *   argument placeholders (%) based on the menu router item of the current
 *   path. Defaults to FALSE. Internally used for breadcrumbs.
862
 *
863
864
 * @return
 *   Returns the map of path arguments with objects loaded as defined in the
865
866
867
868
 *   $item['load_functions'].
 *   $item['access'] becomes TRUE if the item is accessible, FALSE otherwise.
 *   $item['href'] is generated from link_path, possibly by to_arg functions.
 *   $item['title'] is generated from link_title, and may be localized.
869
 *   $item['options'] is unserialized; it is also changed within the call here
870
 *   to $item['localized_options'] by _menu_item_localize().
871
 */
872
873
874
875
function _menu_link_translate(&$item, $translate = FALSE) {
  if (!is_array($item['options'])) {
    $item['options'] = unserialize($item['options']);
  }
876
877
  if ($item['external']) {
    $item['access'] = 1;
878
    $map = array();
879
880
    $item['href'] = $item['link_path'];
    $item['title'] = $item['link_title'];
881
    $item['localized_options'] = $item['options'];
882
883
  }
  else {
884
885
    // Complete the path of the menu link with elements from the current path,
    // if it contains dynamic placeholders (%).
886
    $map = explode('/', $item['link_path']);
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
    if (strpos($item['link_path'], '%') !== FALSE) {
      // Invoke registered to_arg callbacks.
      if (!empty($item['to_arg_functions'])) {
        _menu_link_map_translate($map, $item['to_arg_functions']);
      }
      // Or try to derive the path argument map from the current router item,
      // if this $item's path is within the router item's path. This means
      // that if we are on the current path 'foo/%/bar/%/baz', then
      // menu_get_item() will have translated the menu router item for the
      // current path, and we can take over the argument map for a link like
      // 'foo/%/bar'. This inheritance is only valid for breadcrumb links.
      // @see _menu_tree_check_access()
      // @see menu_get_active_breadcrumb()
      elseif ($translate && ($current_router_item = menu_get_item())) {
        // If $translate is TRUE, then this link is in the active trail.
        // Only translate paths within the current path.
        if (strpos($current_router_item['path'], $item['link_path']) === 0) {
          $count = count($map);
          $map = array_slice($current_router_item['original_map'], 0, $count);
          $item['original_map'] = $map;
          if (isset($current_router_item['map'])) {
            $item['map'] = array_slice($current_router_item['map'], 0, $count);
          }
          // Reset access to check it (for the first time).
          unset($item['access']);
        }
      }
914
    }
915
    $item['href'] = implode('/', $map);
916

917
    // Skip links containing untranslated arguments.
918
919
    if (strpos($item['href'], '%') !== FALSE) {
      $item['access'] = FALSE;
920
921
      return FALSE;
    }
922
    // menu_tree_check_access() may set this ahead of time for links to nodes.
923
    if (!isset($item['access'])) {
924
      if ($route = $item->getRoute()) {
925
        $item['access'] = menu_item_route_access($route, $item['href'], $map);
926
927
      }
      elseif (!empty($item['load_functions']) && !_menu_load_objects($item, $map)) {
928
        // An error occurred loading an object.
929
930
931
        $item['access'] = FALSE;
        return FALSE;
      }
932
933
934
935
936
      // Apply the access check defined in hook_menu() if there is not route
      // defined.
      else {
        _menu_check_access($item, $map);
      }
937
    }
938
939
940
941
    // For performance, don't localize a link the user can't access.
    if ($item['access']) {
      _menu_item_localize($item, $map, TRUE);
    }
942
  }
943

944
945
946
947
948
949
  // Allow other customizations - e.g. adding a page-specific query string to the
  // options array. For performance reasons we only invoke this hook if the link
  // has the 'alter' flag set in the options array.
  if (!empty($item['options']['alter'])) {
    drupal_alter('translated_menu_link', $item, $map);
  }
950

951
  return $map;
Dries Buytaert's avatar
   
Dries Buytaert committed
952
953
}

954
955
956
957
958
959
960
/**
 * Checks access to a menu item by mocking a request for a path.
 *
 * @param \Symfony\Component\Routing\Route $route
 *   Router for the given menu item.
 * @param string $href
 *   Menu path as returned by $item['href'] of menu_get_item().
961
 * @param array $map