/Drupal 8

function hook_menu_links_discovered_alter


Alters all the menu links discovered by the menu link plugin manager.


array $links: The link definitions to be altered.

Return value

array An array of discovered menu links. Each link has a key that is the machine name, which must be unique. By default, use the route name as the machine name. In cases where multiple links use the same route name, such as two links to the same page in different menus, or two links using the same route name but different route parameters, the suggested machine name patten is the route name followed by a dot and a unique suffix. For example, an additional logout link might have a machine name of user.logout.navigation, and default links provided to edit the article and page content types could use machine names entity.node_type.edit_form.article and entity.node_type.edit_form.page. Since the machine name may be arbitrary, you should never write code that assumes it is identical to the route name.

The value corresponding to each machine name key is an associative array that may contain the following key-value pairs:

  • title: (required) The title of the menu link. If this should be translated, create a \Drupal\Core\StringTranslation\TranslatableMarkup object.
  • description: The description of the link. If this should be translated, create a \Drupal\Core\StringTranslation\TranslatableMarkup object.
  • route_name: (optional) The route name to be used to build the path. Either the route_name or url element must be provided.
  • route_parameters: (optional) The route parameters to build the path.
  • url: (optional) If you have an external link use this element instead of providing route_name.
  • parent: (optional) The machine name of the link that is this link's menu parent.
  • weight: (optional) An integer that determines the relative position of items in the menu; higher-weighted items sink. Defaults to 0. Menu items with the same weight are ordered alphabetically.
  • menu_name: (optional) The machine name of a menu to put the link in, if not the default Tools menu.
  • expanded: (optional) If set to TRUE, and if a menu link is provided for this menu item (as a result of other properties), then the menu link is always expanded, equivalent to its 'always expanded' checkbox being set in the UI.
  • options: (optional) An array of options to be passed to \Drupal\Core\Utility\LinkGeneratorInterface::generate() when generating a link from this menu item.

Related topics

Define functions that alter the behavior of Drupal core.
Menu system
Define the navigation menus, local actions and tasks, and contextual links.


core/lib/Drupal/Core/Menu/menu.api.php, line 265
Hooks and documentation related to the menu system and links.


function hook_menu_links_discovered_alter(&$links) {
  // Change the weight and title of the user.logout link.
  $links['user.logout']['weight'] = -10;
  $links['user.logout']['title'] = new \Drupal\Core\StringTranslation\TranslatableMarkup('Logout');
  // Conditionally add an additional link with a title that's not translated.
  if (\Drupal::moduleHandler()->moduleExists('search')) {
    $links['menu.api.search'] = array(
      'title' => \Drupal::config('system.site')->get('name'),
      'route_name' => 'menu.api.search',
      'description' => new \Drupal\Core\StringTranslation\TranslatableMarkup('View popular search phrases for this site.'),
      'parent' => 'system.admin_reports',

© 2001–2016 by the original authors
Licensed under the GNU General Public License, version 2 and later.
Drupal is a registered trademark of Dries Buytaert.