How to add redirects programmatically in Drupal

Last Updated: 16 Mar 2025

Redirects are essential for managing changes in URLs, especially when restructuring a site or removing pages. In this tutorial, we’ll walk through how to add redirects programmatically in Drupal using custom code.
In many cases, you will be able to do this via a well-known and a reliable contrib module called 'redirect', however, as a developer we run into situations where we want greater control over the things and contrib modules/plugins are not an option in different scenarios.

Why Add Programmatic Redirects?

  • Automating bulk redirects.
  • Simplifying workflows for dynamic redirects.
  • Providing greater flexibility compared to manual configuration.

Step 1 - Create and activate a custom module

You can skip this step if you want to use an existing custom module in your project. This code should work from any existing or new module. In this tutorial, we will be using custom_redirect as the module machine name. In your modules/custom folder, create a new folder called custom_redirect and create these files:
custom_redirect.info.yml:

name: 'Custom Redirect'
type: module
description: 'Programmatically add redirects in Drupal.'
package: Custom
core_version_requirement: ^9 || ^10

Go to /admin/modules page of your website and search for Custom Redirect module, select it and then click on install to activate your module. Alternatively, you can use drush pm:install custom_redirect (see this drush page) command if you have access to the terminal with Drush installed.

Step 2 - Create required files for adding redirects

Add the following PHP file in the module folder at src/EventSubscriber/MyCustomEventSubscriber.php:

<?php
namespace Drupal\custom_redirect\EventSubscriber;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\HttpKernel\Event\KernelEvent;
class MyCustomEventSubscriber implements EventSubscriberInterface {
   public function onRequest(KernelEvent $event) {
	  // This is where we will add our logic to redirect!
   }
   /**
    * {@inheritdoc}
    */
   public static function getSubscribedEvents() {
      $events[KernelEvents::REQUEST][] = ['onRequest', 28];
      return $events;
   }
}

Also, add this in custom_redirect.services.yml (create this file if it does not exists):

services:
 custom_redirect.event_subscriber:
   class: Drupal\custom_redirect\EventSubscriber\MyCustomEventSubscriber
   tags:
     - { name: event_subscriber }

Lets quickly understand what we just added into the both files.
The MyCustomEventSubscriber class is implementing EventSubscriberInterface which requires getSubscribedEvents method to be defined in this class. This method tells Drupal what methods should be called when our class is invoked. Think of MyCustomEventSubscriber as a subscriber class to different events happening during a request to a page. In custom_redirect.services.yml file, the tags object is important as it's name property tells Drupal that this service is an event_subscriber class and in return Drupal will execute methods (in same class) specified in the getSubscribedEvents method. This is a concept similar to 'lifecycle hooks' that is there in different frameworks.

In our example, we have specified onRequest in getSubscribedEvents method which means Drupal will execute onRequest method whenever a page is visited on the site. Within this method, we can add our checks and conditionally redirect requests to a different page.

Step 3 - Specify redirect in onRequest method

We have a page published at "/page-1' in our website and we want to redirect users visting this page to "/page-2". Our `onRequest` method will be like this:

public function onRequest(KernelEvent $event) {
   $current_path = \Drupal::request()->getPathInfo(); // This will return the current path
   if ($current_path == '/page-1') {
      $to_url = Url::fromUserInput('/page-2'); // We use Drupal core Url object
      $response = new RedirectResponse($to_url->toString(), 301);
      $event->setResponse($response);
   }
}

We get the current path in a variable called $current_path and then check if it matches our target page, and then uses an object of RedirectResponse and pass it as a response KernalEvent's setResponse method and that is the magic here!

Since we are using Url and RedirectResponse objects, please make sure to import them by using these two use statements in the file:

use Drupal\Core\Url;
use Symfony\Component\HttpFoundation\RedirectResponse;

That's it, we will be now redirected to "/page-2" if we try to visit "page-1".

Next step: Add redirect based on the user role

Stay tuned, coming soon

Tags: