Chapter 3: Routes and Controllers

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.

Drupal uses PSR-4 namespaces to autoload the correct PHP class from a file, accommodating variations in site structures. As a module developer, it's important to understand PSR-4, as it dictates the location within your module directory for most of your custom code.

In this tutorial, we'll:

• Define the PSR-4 namespace standard.
• Explore its use in Drupal.
• Learn to read a namespace and locate the corresponding PHP file.

By the end of this tutorial, you should be able to recognize a PSR-4 namespace, determine the related fully-qualified class name, and the location of the corresponding PHP file.

Controllers are where you place the custom logic to dynamically generate the content of a page that a visitor sees when they visit a URL. When Drupal receives an incoming request, the HttpKernel identifies the appropriate route for the requested path, and the routing system matches this route with a controller. Controllers generate responses to these requests.

In this tutorial, we'll:

• Understand what a controller is in PHP and in the context of a Drupal module.
• Learn how to identify and interpret the role of a controller class.

By the end of this tutorial, you should be able to identify a controller class in a Drupal module and understand its role in generating responses.

Routes map URLs to the code that generates the content for display. As module developers, we create routes whenever we want to add a new URL with code. Our task is to create a route for a page displaying the weekend weather forecast. We start by defining the route, then add the corresponding controller.

In this tutorial, we'll:

• Create a routing YAML file for a custom weather page.
• Define a route instructing Drupal to point the path /weather to our custom code.

By the end of this tutorial, you will have defined a route for your weather page, including the path and a reference to the controller managing the content.

We need a place to put the custom PHP code for our /weather page. In Drupal, controllers encapsulate the custom PHP logic that generates the content of a page. A basic controller might output a hard-coded response, or perform a simple calculation in PHP. Complex controllers make database requests, query third-party APIs, and format complex data using injected services and custom PHP logic.

In this tutorial, we'll:

• Create a new controller class following the PSR-4 standard.
• Define the Drupal\anytown\Controller\WeatherPage class with a build() method that returns the page's content.
• Verify that our route and controller are working.

By the end of this tutorial, you should be able to navigate to /weather in your browser and see the output from our custom controller.

Route parameters enable a single route and controller to handle multiple URLs by passing dynamic values from the URL to the controller. This allows for more versatile and responsive page content generation.

In this tutorial, we'll:

• Understand the function of route parameters.
• Update the anytown.weather_page route to include parameters.
• Modify the WeatherPage controller to use these parameters.

By the end of this tutorial, you'll know how to use route parameters to pass dynamic values to controllers.

Drupal offers module developers several methods for creating different types of links, all defined by module configuration. This tutorial explores these types of links, how they relate to each other, and when to use them.

In this tutorial, we'll learn:

• The nature of menu items, action links, and local task links.
• Examples of each link type in Drupal's UI and their application in our scenario.
• Criteria for selecting the appropriate link type for adding the weather page to site navigation.

By the end of this tutorial, you'll understand the different types of links in Drupal and how they apply to adding navigational elements for custom module pages.

Drupal's Menu system allows module developers to define navigational links, offering flexibility to site builders for configuration and arrangement. By linking to routes rather than URLs, these links remain functional, even when route definitions change.

In this tutorial, we'll:

• Create a MODULE_NAME.links.menu.yml file.
• Define a new menu item link for the /weather page in our anytown module.
• Configure Drupal to display the link in the primary navigation.

By the end of this tutorial, you'll be able to define new menu item links and integrate them into your site's configuration.

Permissions in Drupal control access to features and functions. Modules define permissions, which allow site administrators to grant or restrict access based on user roles. As a module developer, you'll create new permissions to restrict access to your module's custom features, independent of existing permissions defined by other modules.

In this tutorial, we'll:

• Explore how and where permissions are defined within a module.
• Discuss the concept of static and dynamic permissions in Drupal.

By the end of this tutorial, you'll have a clear understanding of how permissions function in Drupal and their implementation in modules.

Modules can define custom permissions to restrict access to specific routes or page sections. This control allows module developers to provide granular access while enabling site administrators to manage user privileges. We'll add a view weekly weather permission via the anytown module to limit access to the weather page.

In this tutorial, we'll:

• Create an MODULE_NAME.permissions.yml file.
• Define a new permission.
• Use the new permission to restrict access to a route.

By the end of this tutorial, you should be able to define a new permission in a module and use it to control access to a route.