Drupal Routing

I need to...	Guide	Summary
Fix a routing error causing site crashes	YAML Escaping Rules	Use single backslashes in single quotes for controller/form class references. This is CRITICAL - incorrect escaping causes fatal site crashes during cache rebuild.
Write a basic route definition	Basic Route Structure	Use when defining any new route in a *.routing.yml file. This is the foundation for all routing definitions.
Add access control to a route	Access Control Patterns	Use when restricting route access to specific users, roles, or custom conditions. Always define access requirements - never leave routes open.
Create routes with parameters	Route Parameters	Use when routes need dynamic segments (e.g., node IDs, user IDs, custom identifiers). Parameters enable reusable routes for multiple entities or contexts.
Configure admin routes with proper theme	Admin Route Configuration	Use when creating administrative interfaces that should use the admin theme and integrate with Drupal's admin UI patterns.
Build dynamic routes programmatically	Dynamic Routes	Use when routes need to be generated programmatically based on configuration, content, or runtime conditions. Prefer static YAML routes when possible - use dynamic routes only when necessary.
Alter existing routes	Route Subscribers	Use when you need to alter existing routes from core or contrib modules. Do NOT use to create routes - use route_callbacks or static YAML instead.
Create custom access checkers	Custom Access Checking	Use when built-in access checks (_permission, _role, _entity_access) are insufficient. Complex business logic, multi-factor checks, or context-dependent access require custom checkers.
Debug routing issues	Testing and Debugging	Always test routes after creation or modification. Routing errors can crash sites, so validation is critical before deployment.
Avoid common routing mistakes	Common Pitfalls	Reference this before committing routing YAML or when debugging routing issues. These are real-world errors that crash sites or create security vulnerabilities.
Ensure routing security	Security Best Practices	Use when designing any route - security must be considered from the start, not added later. Every route is a potential attack vector.
Optimize routing performance	Performance Best Practices	Use when routes are high-traffic, when using dynamic routes or custom access checkers, or when routes load significant data. Performance issues in routing affect every page load.