Preprocessor Plugins

Note: With Preprocess Hook Attributes now being supported in Drupal 11.2, and the support of OOP hooks in themes in Drupal 11.3, this module is no longer recommended if you're developing in versions ahead of those versions. The module will be minimally maintained going forward. While it can still give you the ability to create plugin classes within your themes, it is recommended to use attributes within your modules in 11.2, or OOP theme hooks in 11.3.

This module grants developers the ability to create Plugins to preprocess template variables instead of traditional Preprocess Functions.

This module serves two main purposes:

• Align preprocessing with more modern Drupal practices, allowing a more OOP approach and granting the ability to use Dependency Injection and more.
• Prevent large .theme files that contain all preprocessing logic. Large files are easy to get lost in and are less organized.

Documentation

Refer to the documentation to get started, or read the quickstart section below to learn how to create a simple plugin in your themes.

Quickstart

Let's take a look at a quick comparison between a traditional preprocess function and a preprocess plugin.

Traditionally, you would preprocess a node template using the following code:

/**
 * Implements hook_preprocess_HOOK().
 */
function MY_THEME_preprocess_node(&$variables) {
  $variables['foo'] = 'bar';
}

To achieve the same functionality as above within your theme with a Plugin, you would do the following:

Plugins can only be discovered in themes via YAML discovery.
Create a MY_THEME.preprocessors.yml file at the root of your theme.

MY_THEME.preprocessor.node:
  class: '\Drupal\MY_THEME\Plugin\preprocessors\NodePreprocessor'
  hooks:
    - node
  weight: 0

And you can then create a class at MY_THEME/src/Plugin/preprocessors/NodePreprocessor.php with the following content.

namespace Drupal\MY_THEME\Plugin\preprocessors;

use Drupal\preprocessors\PreprocessorPluginBase;

/**
 * Provide plugin to preprocess variables for nodes.
 */
final class NodePreprocessor extends PreprocessorPluginBase {

  /**
   * Preprocess your variables.
   *
   * This function works just like a 'hook_preprocess_HOOK()' function.
   *
   * {@inheritdoc}
   */
  public function preprocess(array &$variables, string $hook, array $info) : void {
    $variables['foo'] = 'bar';
  }

}

Related Modules

Preprocess

The Preprocess module grants the same core feature, albeit with a little less customization options. It has had more community support and is actively used on many websites currently.

Under the hood, both modules work similarly, but Preprocessor Plugins integrates more deeply with the Theme Registry, inserting custom preprocess functions at precise locations within the existing list of preprocess functions provided by core and other contrib modules. This is done instead of calling its own hook_preprocess() hook.

This module now acts as a successor to Preprocess, with added features and customizations to fit more with how Drupal loads traditional hooks. This includes efforts to maintain proper loading order of hooks, base hooks and registering custom preprocess functions within the Theme Registry.

Preprocessor Files

For an alternative, more lightweight approach to preprocessing, refer to the Preprocessor Files module. This module allows you to create dedicated lightweight files instead of hook functions or plugins. Learn more on the module's page.