Now that we have covered some theory about the menu system, it's time to get our hands dirty with some code. The first thing we will look at is how to work with menus programmatically in view of rendering them in our module. For this, we will work with the default Administration menu that comes with Drupal core and has many links in it, at various levels. Note that the code we write in this section will not be included in the code repository.

Drupal core provides a block called SystemMenuBlock, which can be used to render any menu inside a block. However, let's take a look at how we can do this ourselves instead.

The first thing we will need to do is get the MenuLinkTree service. We can inject it or,if that's not possible, get it statically via the helper \Drupal class:

$menu_link_tree = \Drupal::menuTree();

Next, we will need to create a MenuTreeParameters object so that we can use it to load our menu tree. There are two ways we can do this. We can either create it ourselves and set our own options on it or we can get a default one based on the current route:

$parameters = $menu_link_tree->getCurrentRouteMenuTreeParameters('admin');

Providing the name of a menu (in our case, "admin"), this method gives us a MenuTreeParameters instance with the following options set on it:

• The links in the active trail of the current route are marked as expanded, that is, they will show up in the resulting tree that we load
• The children of the links in the active trail that have the "expanded" property set are also included in the resulting tree

Essentially, this set of parameters gives us a tree within the context of the current route we are on. In other words, it will load all the root links in the menu and all the children of the root link that is in the active trail of the current route. It will leave out the children of the other root links.

You can, of course, further customize this set of parameters or create one from scratch. For example, if we want to load only the tree of a root link inside a menu, we could do it as follows:

$parameters = new MenuTreeParameters();
$parameters->setRoot($plugin_id);

In the preceding code, $plugin_id is the ID of the menu link that should be at the root of the tree (defined in the YAML file or derived from a derivative).

I encourage you to look inside the MenuTreeParameters class and take a look at the other options that you have to load a tree.

For our example, we want to work with the entire menu tree of the Administration menu, so just instantiating a new MenuTreeParameters object will be enough, as we want to load all links in the menu. We can do this as follows:

$tree = $menu_link_tree->load('admin', $parameters);

Now, we have an array of MenuLinkTreeElement objects inside $tree, including the following things:

• The link property, which is the menu link plugin
• The subtree property, which is an array of MenuLinkTreeElement objects going down the tree
• Various metadata about the link within the tree (depth, whether in the active trail, whether it has children, access, and so on)

However, it is an important thing to note that notwithstanding any MenuTreeParameters we may have had, we are now sitting on top of all menu links in that menu, regardless of any access check. It is our responsibility to make sure that we don't render links to pages the user has no access to (as they will get a 403 when they get there). To do this, we use the manipulators we discussed earlier, which are simple methods on a service.

The Drupal 8 menu system comes with a few default manipulators, which can be found inside the DefaultMenuLinkTreeManipulators service. Most of the times, they will be enough for you:

• Access (handled by the checkAccess() method): Checks whether the user has access to the links in the tree. If they don't, the link becomes an instance of InaccessibleMenuLink and any links in its subtree are cleared out
• Node Access (handled by the checkNodeAccess() method): Checks whether the user has access to the Node entity linked to by the menu link. If you know that the menu has links to Nodes, you can use this before the regular access check because it's a bit more performant.
• Index and Sort (handled by the generateIndexAndSort() method): Creates unique indexes in the tree and sorts it by them.
• Flatten (handled by the flatten() method): Flattens the menu tree to one level.

If these are not enough, you can add your own manipulators as needed. All you have to do is define a service as a public method and then reference it when transforming the tree. However, speaking of transforming, let's go ahead and use the access check manipulator to ensure that the current user has access to our tree links:

  $manipulators = [
    ['callable' => 'menu.default_tree_manipulators:checkAccess']
  ];
  $tree = $menu_link_tree->transform($tree, $manipulators);

As I said earlier, we will use the transform() method on the service and pass an array of callables. The latter are nothing more than the service name, followed by : and the method name to be used. So, if you create your own service, you can reference it the same way.

Now, each MenuLinkTreeElement that remains in the tree has its access property filled with an instance of AccessResultInterface (a system of denoting access that we will talk more about in a later chapter). If the link is not accessible, it becomes an instance of InaccessibleMenuLink, so we know that we cannot render it, and even if we did render it, it will go to the home page rather than the 403.

Now, all we have to do is turn this tree into a render array:

$menu = $menu_link_tree->build($tree);

Inside $menu, we now have a render array that uses the menu theme hook using a theme hook suggestion based on the menu name. So, in our case, it will be menu__admin. Remember what these are from the theming chapter?

The menu theme hook will use, by default, the menu.html.twig (or menu--admin.html.twig if it exists inside a theme) to render the menu links inside a simple, albeit hierarchical, HTML list.

As a quick recap from the theming chapter, at this point you have a few options to gain full control over the output of the menu:

• Creating a new theme hook and mimicking what the build() method does to build the render array
• Altering the theme registry to switch out the template with your own
• Overriding the template inside a theme
• Implementing a preprocessor for the theme hook and altering variables there

So, as you can see, you have many options. The choice you make depends on what you need to achieve, how happy you are with what the default markup is, and so on.