Overwriting Routes in Drupal 9 & 10 using Route Subscriber and Custom Controller

In this blog post, we'll walk you through the process of overwriting a route in Drupal using a route subscriber and a custom controller. This can be useful when you want to change the functionality or appearance of an existing route without modifying the core or contributed modules.

Step 1: Create a custom module

First, create a custom module if you don't have one already. For this example, we'll create a module called custom_route_overwrite. Make sure the module has the necessary .info.yml file. Here's an example of the file content:

name: Custom Route Overwrite
type: module
description: 'A custom module to overwrite the help.main route'
package: Custom
core_version_requirement: ^9.5

Step 2: Create a custom controller

In your custom module's src/Controller folder, create a new PHP file for your controller. In this example, we'll name it CustomMainController.php. Add the following code to the file:

<?php

namespace Drupal\custom_route_overwrite\Controller;

use Drupal\Core\Controller\ControllerBase;

class CustomMainController extends ControllerBase {

  public function customMainContent() {
    return [
      '#type' => 'markup',
      '#markup' => $this->t('This is the custom main content.'),
    ];
  }
}

Step 3: Create a route subscriber

In your custom module's src/EventSubscriber folder, create a new PHP file called CustomRouteSubscriber.php. Add the following code to the file:

<?php

namespace Drupal\custom_route_overwrite\EventSubscriber;

use Drupal\Core\Routing\RouteSubscriberBase;
use Drupal\Core\Routing\RoutingEvents;
use Symfony\Component\Routing\RouteCollection;

class CustomRouteSubscriber extends RouteSubscriberBase {

  protected function alterRoutes(RouteCollection $collection) {
    if ($route = $collection->get('help.main')) {
      $route->setDefault('_controller', 'Drupal\custom_route_overwrite\Controller\CustomMainController::customMainContent');
    }
  }

  public static function getSubscribedEvents() {
    $events[RoutingEvents::ALTER] = 'alterRoutes';
    return $events;
  }
}

Step 4: Register the route subscriber as a service

In your custom module's folder, create a new custom_route_overwrite.services.yml file if it doesn't already exist. Add the following code to the file:

services:
  custom_route_overwrite.route_subscriber:
    class: Drupal\custom_route_overwrite\EventSubscriber\CustomRouteSubscriber
    tags:
      - { name: event_subscriber }

Step 5: Clear the cache

To ensure that your changes are registered by Drupal, clear the cache. You can do this using Drupal's admin UI or using Drush with the command drush cr.

Step 6: Enable the custom module

Finally, enable the custom module to see your changes in action. You can do this through the Drupal admin UI or using Drush with the command drush en custom_route_overwrite -y.

Conclusion

After completing these steps, the help.main route will be overwritten by your custom controller, and the new content will be displayed on the help page. This solution is flexible and can be applied to other routes as well. Just replace the route name and create a custom controller with the desired output.

This method of overwriting routes using route subscribers and custom controllers is a clean and maintainable way to customize existing routes in Drupal. It follows best practices by keeping the code organized within a custom module and not modifying core or contributed modules.

Now you have the knowledge and tools to overwrite routes in Drupal 9.5 using route subscribers and custom controllers. Feel free to explore further and customize your Drupal application to fit your needs.