Module Development

Concept: Routes for Drupal 8, 9, 10, and 11

As a module developer, you use routes defined in a module to add new URLs and tell Drupal which code to execute to build content for the page at those URLs. Central to this process is Drupal's routing system, built upon Symfony's Routing component.

In this tutorial, we'll:

  • Introduce Drupal's routing system.
  • Learn how modules can define new routes.
  • Describe the roles that routes serve in a module.

By the end of this tutorial, you should understand each parameter of a route definition in a module's MODULE_NAME.routing.yml file.

Goal

Understand the role of Drupal's routing system plays in enabling developers to create custom pages within a module.

Prerequisites

Adding a custom URL with a module

In your work on the Anytown Farmer's Market site, you have been tasked with creating a new page at the path, /weather. Visitors will use this page to view the weather forecast for the upcoming weekend, helping them decide whether to attend the market.

One option is to add a new Basic page node and set the URL alias to /weather, allowing an editor to update the page. However, this approach requires frequent data updates. A more efficient solution is to use a third-party weather API to provide an up-to-date forecast.

To implement this, you need to inform Drupal that your module will handle the /weather page and instruct it to call your custom code, which will retrieve and display the weather forecast.

Understanding Drupal's routing system

Defining new URLs (or paths) with a module involves creating a route. Drupal uses a routing system based on Symfony's Routing component to match URLs with corresponding response-generating code. Drupal's routing system includes specific features that enhance Symfony's component. (You don't need experience with routing in Symfony to set up a route in Drupal.)

Routes define a path. A path is the portion of the URL after the TLD (Top-Level Domain). For example, in the URL, https://drupal.org/weather, the /weather portion is the path. A route's definition includes handling route parameters, access control, and specifying which code (known as a controller) to execute. We'll discuss controllers, responsible for returning page content, in Concept: Controllers.

Anatomy of a route

Routes are typically defined using YAML in a module’s MODULE_NAME.routing.yml file. It's also possible to define dynamic routes with PHP classes. In this guide, we'll use a routing file to define a route.

A route definition includes:

  • Path: The URL the route responds to, possibly containing placeholders or wildcards passed as arguments to the controller.
  • Defaults: Default values for the route, such as a _controller or _form for the response, a _title for the page, and optional arguments for the called code.
  • Requirements: Conditions for route accessibility, often including permission checks.

A single routing YAML file can contain multiple route definitions.

In Create a Route for the Weather Page, we'll add a route for the /weather URL to the anytown module. And we'll get hands-on practice defining a route in Create a Route and Controller.

Recap

This tutorial introduced the basics of Drupal's routing system. We learned about route components and how Drupal uses Symfony's routing component to manage HTTP requests and create dynamic content.

Further your understanding

  • What role do routes play in custom modules?
  • How do permissions affect route access?

Additional resources

On this page

Drupal Module Developer Guide