Drupal Routing and Controllers

When to use

• The user is writing a Drupal controller that returns a render array or a JSON/redirect response.
• The user wants to define a Drupal route in routing.yml that maps a path to a controller method.
• The user needs to restrict a Drupal route by permission, role, or a custom access check.

When NOT to use

• Do not hand-roll a controller route when JSON:API or the REST module already exposes the entity the client needs.
• Do not write a route and controller when editors only need a static content page that a node or Views can provide.

Core guidance

• Give each route a path, defaults._controller, and requirements — Each entry in MODULE.routing.yml needs a path, a defaults._controller pointing at \Drupal\MODULE\Controller\Class::method, a defaults._title, and a requirements block.

Quick recipe

1. Add a route to MODULE.routing.yml with path, defaults._controller, defaults._title, and a requirements access rule. (verify: The path resolves to the controller after drush cr.)
2. Create a controller under src/Controller/ extending ControllerBase, inject services in create(), and return a render array from the method. (verify: Visiting the path renders the expected markup.)
3. Run drush cr, then confirm an authorized user reaches the page and an unauthorized user gets 403. (verify: Access matches the declared requirements.)

Best practices

• Always set a requirements access rule (_permission, _role, _entity_access, or _custom_access) on each route; use _access: 'FALSE' for internal-only paths
• Extend ControllerBase and, when the controller needs services, implement create(ContainerInterface $container) to inject them rather than using the trait shortcuts
• Return a render array (['#markup' => ...] or ['#theme' => ...]) from controller methods so Drupal can attach cache metadata and libraries
• Declare dynamic path segments as {node} and type-hint the controller argument (NodeInterface $node) so Drupal upcasts the raw id into the loaded entity

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Route silently unreachable without a requirements block — A route with no requirements access rule is treated as inaccessible and returns 403 for everyone. Fix: Add an explicit _permission, _role, _access: 'TRUE', or _custom_access requirement to the route.
2. Returning raw HTML strips cache metadata — Returning a plain string or pre-rendered HTML from a controller drops cache tags and attached libraries. Fix: Return a render array and let Drupal render it; add #cache tags and contexts for correct invalidation.
3. New route returns 404 until the router is rebuilt — A newly added route in routing.yml returns 404 even though the YAML is correct. Fix: Run drush cr (or drush router:rebuild) after adding or editing routes.

Version notes

• Route match and request injection stable since Drupal 8 (PHP >=8.1) — Controllers can type-hint RouteMatchInterface and Request parameters for automatic injection; this Symfony-based dispatch has been stable since Drupal 8 and continues in 10/11.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/drupal/routing-controllers.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Prerequisites: drupal/module-development