Drupal 8/9/10: Change Active Theme Programmatically

Hey Drupal developers! Ever found yourself needing to switch themes on your Drupal site programmatically? Maybe you're building a feature that requires a different look and feel under certain conditions, or perhaps you're crafting a multi-site setup with theme variations. Whatever the reason, knowing how to change the active theme through code is a super handy skill to have in your Drupal toolkit.

In this guide, we'll dive deep into the methods for programmatically changing themes in Drupal 8, 9, and 10. We'll cover the evolution from Drupal 6 and 7, highlight the best practices, and provide clear, practical examples to get you rolling. So, let's get started and make your theme-switching adventures a breeze!

From Drupal 6 & 7 to Drupal 8+: A Quick Recap

Before we jump into the Drupal 8+ way of doing things, let's take a quick look back at how we handled theme switching in earlier Drupal versions. This will give you some context and help you appreciate the improvements and changes in the newer versions.

The Drupal 6 Way: $custom_theme

In Drupal 6, things were pretty straightforward, albeit a bit… global. You could simply set the $custom_theme global variable to the machine name of your desired theme. Like this:

global $custom_theme;
$custom_theme = 'garland'; // Or any other theme machine name

While this method was simple, it had its drawbacks. Relying on global variables can lead to unpredictable behavior and make debugging a headache. Plus, it wasn't the most elegant solution from an architectural standpoint.

The Drupal 7 Way: hook_custom_theme()

Drupal 7 introduced a more structured approach with hook_custom_theme(). This hook allowed you to define your theme-switching logic within a dedicated function in your module. Here’s how it looked:

/**
 * Implements hook_custom_theme().
 */
function my_module_custom_theme($existing, $type, $theme, $path) {
  if (some_condition()) {
    return 'my_custom_theme';
  }
}

This was a step up from Drupal 6 as it provided a cleaner and more organized way to change themes. However, it still had limitations. For instance, it could only suggest a theme, and other modules could override your suggestion. It also lacked the flexibility to switch themes on a more granular level, such as for specific routes or controllers.

The Drupal 8+ Way: Services and Events

Drupal 8 and later versions (9 and 10) bring a much more robust and flexible system for theme switching. The core of this system revolves around services and events, which align with modern PHP and Symfony practices. This approach provides a cleaner, more predictable, and more extensible way to manage themes.

Now that we've covered the historical context, let's dive into the specifics of how to programmatically change themes in Drupal 8 and beyond.

Programmatically Changing Themes in Drupal 8/9/10: The Modern Approach

The recommended approach in Drupal 8, 9, and 10 involves leveraging the ThemeNegotiator service and the ThemeNegotiationEvent. This method gives you fine-grained control over theme selection, allowing you to switch themes based on various conditions such as routes, user roles, or custom logic. Let's break down the key components and how to use them.

Understanding the ThemeNegotiator Service

The ThemeNegotiator service is at the heart of Drupal's theme negotiation process. It's responsible for determining which theme should be used for a given request. Drupal provides a chain of theme negotiators, each of which has a chance to set the active theme. This chain allows for a flexible and extensible system where different modules can contribute to the theme selection process.

To programmatically change the theme, you'll need to create your own theme negotiator and inject it into the negotiation chain. Your negotiator will implement the ThemeNegotiatorInterface and define the logic for when to switch themes.

Creating a Custom Theme Negotiator

Let's walk through the steps to create a custom theme negotiator. We'll start by creating a new module (if you don't already have one) and then define our negotiator class.

1. Create a Custom Module

If you don't have a custom module yet, create one. Let's call ours custom_theme_switcher. Create the following files in your modules/custom directory:

• modules/custom/custom_theme_switcher/custom_theme_switcher.info.yml
• modules/custom/custom_theme_switcher/custom_theme_switcher.services.yml
• modules/custom/custom_theme_switcher/src/Theme/CustomThemeNegotiator.php

2. Define the Module Info File (custom_theme_switcher.info.yml)

Add the following to your custom_theme_switcher.info.yml file:

name: Custom Theme Switcher
type: module
description: Provides a custom theme negotiator.
core_version_requirement: ^8 || ^9 || ^10
package: Custom

This file tells Drupal about your module, its dependencies, and other metadata. Make sure to adjust the core_version_requirement if you're targeting a specific Drupal version.

3. Define the Services File (custom_theme_switcher.services.yml)

The custom_theme_switcher.services.yml file is where you define your custom service and tag it as a theme negotiator. Add the following:

services:
  custom_theme_switcher.theme_negotiator:
    class: Drupal\custom_theme_switcher\Theme\CustomThemeNegotiator
    tags:
      - { name: theme.negotiator, priority: 100 }

Here, we're defining a service named custom_theme_switcher.theme_negotiator and associating it with our CustomThemeNegotiator class. The tags section is crucial; it tells Drupal that this service is a theme negotiator and should be added to the negotiation chain. The priority value determines the order in which negotiators are invoked (higher values mean earlier invocation).

4. Create the Theme Negotiator Class (src/Theme/CustomThemeNegotiator.php)

Now, let's create the CustomThemeNegotiator class. This is where you'll define your theme-switching logic. Add the following code to src/Theme/CustomThemeNegotiator.php:

<?php

namespace Drupal\custom_theme_switcher\Theme;

use Drupal\Core\Routing\RouteMatchInterface;
use Drupal\Core\Theme\ThemeNegotiatorInterface;

class CustomThemeNegotiator implements ThemeNegotiatorInterface {

  /**
   * {@inheritdoc}
   */
  public function applies(RouteMatchInterface $route_match) {
    // Check if this negotiator should apply. For example, check the route name.
    $route = $route_match->getRouteName();
    if ($route == 'entity.node.canonical') {
      return TRUE;
    }
    return FALSE;
  }

  /**
   * {@inheritdoc}
   */
  public function determineActiveTheme(RouteMatchInterface $route_match, $theme) {
    // Determine the active theme based on your logic.
    $node = $route_match->getParameter('node');
    if ($node && $node->getType() == 'article') {
      return 'bartik'; // Switch to the Bartik theme for article nodes.
    }

    return NULL; // Use the default theme.
  }

}

Let's break down this class:

• Namespace: We define the namespace for our class.
• use Statements: We import the necessary interfaces and classes.
• applies() Method: This method determines whether our negotiator should be applied for the current request. It receives a RouteMatchInterface object, which allows us to inspect the current route. In this example, we're checking if the route name is entity.node.canonical, which corresponds to node view pages. If it is, we return TRUE, indicating that our negotiator should be applied.
• determineActiveTheme() Method: This is where the magic happens. This method is called if applies() returns TRUE. It also receives a RouteMatchInterface object and the current active theme. We can then implement our theme-switching logic. In this example, we're checking if the current node is of type 'article'. If it is, we return the machine name of the Bartik theme ('bartik'), which will switch the theme to Bartik for article nodes. If not, we return NULL, which means we don't want to change the theme, and the next negotiator in the chain will have a chance to set the theme.

5. Enable the Module

Finally, enable your custom_theme_switcher module in Drupal. You can do this via the Drupal UI (/admin/modules) or using Drush:

drush en custom_theme_switcher

Diving Deeper: Advanced Theme Switching Scenarios

Our example above demonstrates a simple scenario where we switch themes based on the node type. However, the beauty of this approach is its flexibility. You can implement much more complex logic to handle various scenarios.

Switching Themes Based on User Roles

Let's say you want to use a different theme for authenticated users. You can modify the determineActiveTheme() method like this:

  public function determineActiveTheme(RouteMatchInterface $route_match, $theme) {
    $current_user = \Drupal::currentUser();
    if ($current_user->isAuthenticated()) {
      return 'my_authenticated_theme'; // Replace with your theme machine name
    }

    return NULL;
  }

Here, we're using \Drupal::currentUser() to get the current user and checking if they are authenticated. If so, we return the machine name of the theme we want to use for authenticated users.

Switching Themes Based on Custom Conditions

You can also implement custom logic based on your specific requirements. For instance, you might want to switch themes based on a URL parameter, a cookie, or a setting in your module's configuration. The possibilities are endless.

Best Practices for Programmatically Changing Themes

Before we wrap up, let's cover some best practices to keep in mind when programmatically changing themes:

• Keep it Modular: Always implement your theme-switching logic within a custom module. This keeps your code organized and makes it easier to maintain and update.
• Use the ThemeNegotiator: As we've discussed, the ThemeNegotiator service is the recommended way to change themes programmatically in Drupal 8+. Avoid using older methods or directly manipulating theme settings.
• Prioritize Clarity: Write your theme-switching logic in a clear and understandable way. Use comments to explain your code and make it easy for others (and your future self) to understand what's going on.
• Consider Performance: Complex theme-switching logic can impact performance. Be mindful of the conditions you're using and try to optimize your code as much as possible. Caching can also help improve performance.
• Test Thoroughly: Always test your theme-switching logic thoroughly to ensure it works as expected in different scenarios. Use automated tests where possible to catch regressions.

Conclusion

And there you have it! You now have a solid understanding of how to programmatically change themes in Drupal 8, 9, and 10. We've covered the evolution from Drupal 6 and 7, dived deep into the ThemeNegotiator service, and explored various scenarios and best practices.

By using the ThemeNegotiator service, you can create flexible and maintainable theme-switching logic that adapts to your specific needs. Whether you're building a multi-site setup, implementing A/B testing, or simply want to provide a different look and feel for certain sections of your site, this approach gives you the power and control you need.

So go ahead, experiment with different conditions and themes, and create amazing user experiences with your Drupal sites! Happy theming, guys! If you have questions, drop them in the comments below – I’m always excited to help out.