Creating a Basic Route

Objectives
  • Learn about routing syntax.
  • Create the my_route_demo module to experiment with routes.
  • Create a new route by defining a route in a new routing file, and defining a new controller class + method in a new controller file.

Defining a route in a routing file

All the routes your module provides must be defined in your module's routing file, named MY_MODULE.routing.yml, replacing 'MY_MODULE' with the name of your module.

Here's an example of a routing file that specifies one single route:

# File: /modules/custom/MY_MODULE/MY_MODULE.routing.yml

MY_MODULE.SOME_ROUTE_NAME:
  path: '/hello/world'
  defaults:
    _controller: '\Drupal\MY_MODULE\Controller\MyController::sayHello'
    _title: 'Hello World'
  requirements:
    _permission: 'access content'

The above route definition specifies:

  • A route for /hello/world with the friendly name 'SOME_ROUTE_NAME'.
  • The title of the displayed page will be 'Hello World'.
  • Only users who have role with the permission 'access content' are allowed access to this page.
  • The code to be executed is the sayHello() method in the MyController class that's part of the MY_MODULE module.

Activity

  • Create a new module named 'my_route_demo'.
  • Make sure it has a valid info file.
  • Enable (install) the module.
  • Refer to Creating a module if you're unsure of which steps to follow.

If you completed the task correctly, you now have an installed (active) module with the following structure:

/modules/custom/my_route_demo
└── my_route_demo.info.yml
Hide hints
show hints

Create a route

You want to be able to browse to /hello and see a page titled 'Hello World', showing the text "Today is a fine day indeed!".

To make this happen, you need to:

  • Create a routing file with a new route for /hello.
  • Create a controller class with a method that generates "Today is a fine day indeed!"

What is a Controller?

A PHP class that responds to (HTTP) requests is usually called a 'controller class' or just 'controller' for short. Controllers can be used for other things than responding to requests, but we won't go into that here.

Creating your first routing file

Activity

  • Create a routing file for your module. Make sure it is named correctly and placed in the correct folder.
  • Add the route info below. Make sure to preserve the indentation (2 spaces for each indentation level)
my_route_demo.hello:
 path: '/hello'
 defaults:
   _controller: '\Drupal\my_route_demo\Controller\HelloController::hello'
   _title: 'Hello'
 requirements:
   _permission: 'access content'

If you completed the task correctly, your module should now have the following structure:

/modules/custom/my_route_demo
├── my_route_demo.routing.yml
└── my_route_demo.info.yml

Don't browse to /hello just yet.
You will get an error page because the controller class and method in the routing file ('\Drupal\my_route_demo\Controller\HelloController::hello') don't exist yet.

Hide hints
show hints

Creating your first controller

Activity

  • In your module directory, create a folder named src.
  • Inside the src folder, create a folder called Controller.
  • Inside the new src/Controller folder, create a file named HelloController.php.

Pay attention to the lowercase src, uppercase 'C' in Controller, and uppercase 'H' and 'C' in HelloController. It matters!

If you completed the task correctly, your module should now have the following structure:

/modules/custom/my_route_demo
├── src
│    └── Controller
│           └── HelloController.php
├── my_route_demo.routing.yml
└── my_route_demo.info.yml
Hide hints
show hints

Let's add the controller class code to HelloController.php.

Activity

  • Add the following code to /my_route_demo/src/Controller/HelloController.php and save the file:
<?php
namespace Drupal\my_route_demo\Controller;
use Drupal\Core\Controller\ControllerBase;
class HelloController extends ControllerBase {
 public function hello() {
   return [
     '#markup' => 'Hello. It is a fine day indeed!',
   ];
 }
}

If you completed the task correctly, clear your Drupal cache and browse to /hello. You should now see a page titled 'Hello World', showing the text 'Hello. It is a fine day indeed!'.

Congratulations! Creating routes is a very common part of creating custom modules. You'll be doing this often!

Don't worry about the controller class syntax yet, every line of code will become clear as you progress through this course. The most important thing to note is that this controller class prints a line of text on screen, and gets called when a route is requested.

We will introduce some good practices in our sample code later on; for now we're keeping it as basic as we can to avoid confusion.

Hide hints
show hints

Troubleshooting

If you get an error message or a different result:

  • Clear your Drupal cache.
  • Ensure your new Demo module is really installed.
  • Ensure you're trying to browse to /hello.
  • Ensure the name, contents, and indentation of /my_route_demo/my_route_demo.routing.yml are correct.
  • Ensure the name, location, and contents of /my_route_demo/src/Controller/HelloController.php are correct.
  • Ensure the first line of HelloController is <?php.

General tip:

  • After every change you make to your routing or controller file, be sure to clear your Drupal cache

Summary

  • Routes connect paths to callback methods.
  • Routes are defined in a module's routing file.
  • Routing files follow a filename convention: MY_MODULE.routing.yml.
  • Routing callback functions are usually methods of a controller class.
  • Controller class files need to be placed within a module's /src/Controller/ directory.
  • The name of the controller file (HelloController minus the '.php' must match the class name inside (HelloController) exactly.
  • If you rename your controller class, you must also rename your class filename accordingly.