Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Concepts and Installation

Routing and the Request Lifecycle

Follow a Drupal request from index.php through the kernel, routing, access checks, controllers and render arrays to the final HTML response.

When someone visits a Drupal page, a surprisingly orderly sequence of steps runs. Knowing it turns debugging from guesswork into reading a map: Is the route missing? Is access denied? Did the controller return the wrong thing? Is a cache serving an old page?

Modern Drupal is built on Symfony components, so its request handling will feel familiar if you have used Laravel or Symfony. This lesson walks the path, then shows routes and controllers in real code.

The path of a request

sequenceDiagram
    participant B as Browser
    participant I as index.php
    participant K as DrupalKernel
    participant R as Router
    participant A as Access check
    participant C as Controller
    participant T as Renderer and theme
    B->>I: GET /hello
    I->>K: handle(request)
    K->>R: match path to route
    R->>A: check permission
    A->>C: call controller
    C->>T: return render array
    T->>B: HTML response

Each step can be extended by modules through events and hooks.

  1. web/index.php creates a request and hands it to the kernel.
  2. The kernel boots: loads configuration, services and enabled modules.
  3. Routing matches the URL to a route definition.
  4. Access checks decide whether the current user may see it.
  5. A controller (or entity page, form or View) produces a result.
  6. If the result is a render array, the renderer turns it into HTML using the theme.
  7. The response is sent and may be stored in the page cache.

Defining a route

Modules declare routes in a *.routing.yml file:

YAML
# greetings.routing.yml
greetings.hello:
  path: '/greetings/{name}'
  defaults:
    _controller: '\Drupal\greetings\Controller\GreetingController::hello'
    _title: 'Greeting'
  requirements:
    _permission: 'access content'
    name: '[A-Za-z]+'

Parts of this definition:

  • Route name: greetings.hello, used to generate links in code.
  • path with a parameter.
  • defaults: the controller, and a page title.
  • requirements: access rules (_permission, _role, _access) and regex validation for parameters.

The controller

PHP
<?php

namespace Drupal\greetings\Controller;

use Drupal\Core\Controller\ControllerBase;

class GreetingController extends ControllerBase {

  public function hello(string $name): array {
    return [
      '#markup' => $this->t('Hello, @name!', ['@name' => $name]),
    ];
  }

}

@name is a placeholder that escapes the value, so a visitor cannot inject HTML. A controller can return a render array, a Response object, or throw an exception that Drupal converts into a 403 or 404.

Generating URLs

Never hard-code paths. Ask the router:

PHP
use Drupal\Core\Url;

$url = Url::fromRoute('greetings.hello', ['name' => 'Ana']);
$link = \Drupal\Core\Link::fromTextAndUrl('Say hello', $url);

If you later change the path in the YAML, every link updates automatically.

Events and middleware

The kernel is a stack of HTTP middleware (page cache, session, reverse proxy handling) wrapped around a Symfony event dispatcher. Modules subscribe to events such as kernel.request or kernel.response to modify the request or response. This is the modern alternative to many old hooks, and you will see it again in Modules and Hooks.

Not everything is a controller route

Many pages are created for you:

  • Entity pages: /node/1 is a route that loads the node and shows it with a view mode.
  • Forms: routes using _form instead of _controller.
  • Views pages: a View display with a path registers a route.
  • Path aliases: friendly URLs such as /about-us map to internal paths (/node/5).

A tiny router you can run

This stand-in imitates route matching, parameters, requirements and access checks. It has nothing to do with Drupal's real router code except the idea.

JS Stand-in: a miniature router

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that Ana42 returns 404: the regex requirement made the route not match.

Render arrays in one picture

A controller usually returns an array like ['#markup' => ...]. Drupal calls this a render array. Keys starting with # are properties; other keys are children. Rendering is a tree walk that turns each element into HTML and collects cache information on the way. This second stand-in shows the tree walk.

JS Stand-in: rendering a tree of elements

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Debugging the lifecycle

  • 404 for a path you defined: clear caches (drush cache:rebuild) so the router rebuilds; check the YAML indentation.
  • 403: check the permission and your role in /admin/people/permissions.
  • Wrong output: dump the render array in the controller, or enable Twig debug while theming.
  • Stale page: check caching; the Performance chapter explains cache tags and contexts.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where are routes declared in a module?

    A module's routing YAML maps paths to controllers, forms and access requirements.
  2. 2. What does a controller usually return?

    Render arrays let Drupal's renderer, theme and cache system finish the job.
  3. 3. Why use Url::fromRoute() instead of a hard-coded path?

    Route names are stable; paths may change in YAML without breaking links.
  4. 4. What happens in the router stand-in when the parameter does not match the requirement?

    A failing requirement means the route is not a match, so no route is found.

Summary

  • A request flows from index.php to the kernel, router, access check, controller, renderer and response.
  • Routes in *.routing.yml map paths to controllers with requirements for access and parameters.
  • Controllers return render arrays; Drupal's renderer and theme produce the HTML.
  • Use route names to build URLs, and clear caches when routes seem missing.

Next: Configuration Management Basics