Module Development

How to Find a Route in Drupal for Drupal 8, 9, and 10

Before you can create a path or link to another page on your site, you'll need to know the route (unless there is already a variable available for the URL you need). Finding a route can be a tricky task unless you have the right tools. In this tutorial, we'll show how tools like Webprofiler, Drush, and Grep can be used to get route information for a page, so that you can use functions that need a route as a function parameter.

In this tutorial we'll:

  • Learn how to determine the route or path of an internal page.

Goal

Find the route of an internal page.

Prerequisites

Check for a helper variable first

If you're editing the template for a specific entity type, example node.html.twig, there will almost always be a {{ url }} or similar variable that you can use to link to the entity in question. Make sure you check for an existing variable with the URL either in the documentation or using Twig's dump() function.

Example from node.html.twig:

<h2{{ title attributes }}>
  <a href="{{ url }}" rel="bookmark">{{ label }}</a>
</h2>

For the cases where that doesn't work, or for anyone that wants to understand the details of routes and links, the rest of this tutorial covers how they work.

Routes

Before you can make links to internal Drupal pages you need to be familiar with routes.

If you want to link to an internal Drupal page you need to know the name of the route used to define that page, and what parameters to pass to it. If possible you should not hard-code paths like /node/42 or /about because this might make it impossible for the path to be changed by a content editor.

Learn more about what routes are in Overview: Routes, Controllers, and Responses.

Finding the route for a page

When you navigate to a page in your browser and view the URL in the address bar (http://example.com/node/42), and remove the TLD portion of the URL, you're left with what is called a path (node/42 in this case). Rather than just link to the path node/42 we need to figure out what route this refers to and use the route to generate a path.

Here are a couple of ways you can figure out the route.

Some routes are really common, and can be inferred from following a pattern. Routes to any full page view of a piece of content always follow the pattern entity.ENTITY_TYPE.canonical. Examples include entity.node.canonical or entity.user.canonical. You can also substitute .canonical for some other common routes. All entities have an edit form, which can be accessed via the entity.ENTITY_TYPE.edit_form route. If you want to display the form for editing a user's profile the route is entity.user.edit_form.

Linking to the home page of your site or "/" is really common. But since the route used to render the home page is a setting that can be changed, you can always use the special <front> route as an alias.

You can look at the MODULENAME.routing.yml file for any module to discover available routes. The core/modules/contact.routing.yml file defines this route:

contact.site_page:
  path: '/contact'
  defaults:
    _title: 'Contact'
    _controller: '\Drupal\contact\Controller\ContactController::contactSitePage'
    contact_form: NULL
  requirements:
    _permission: 'access site-wide contact form'

So, if I want to link someone to the system-wide contact form at the path /contact, I would want to use the route named contact.site_page.

Not all routes are statically defined, so sometimes it's easier to use a tool that can give you a list of available routes on your specific site.

Webprofiler

The Webprofiler module makes it easier to find the route for any page on your site. This module is a standalone project that requires Devel. After you download and install Devel and Webprofiler, you will be able to view a toolbar with helpful information at the bottom of every page. Navigate to any page on your site and you can find the route associated with that page from the info provided. This is a tool that should only be used in a local development environment.

Image

Webprofiler can be used to view a list of all available routes by enabling the Routing toolbar item in the module's settings at Configuration > Devel settings > Webprofiler (admin/config/development/devel/webprofiler).

List routes with Drush

Drush has a core:route command that can be used to generate a list of all available routes.

List all routes

drush core:route

Use grep to find specific routes

drush core:route | grep node

See also: Using the Grep Command.

Converting routes to paths

Now that you know what route you want to link to, you're ready to create links.

Recap

In this tutorial we learned what routes are, and how to determine the route name and parameters that represent a given page.

Further your understanding

  • What is the name of the route used to display an individual comment?

Additional resources

Theming Drupal Sites