Décorer un service du cœur sans patcher

· 5 min de lecture

Tôt ou tard, un projet Drupal a besoin de modifier le comportement d’un service du cœur ou d’un module contrib : enrichir les résultats d’une autocomplétion, ajouter un log autour d’un appel HTTP, changer une règle de résolution de chemin… Les réflexes habituels sont le patch (fragile à chaque mise à jour) ou le remplacement de la classe (qui entre en conflit avec le premier module qui fait la même chose).

Drupal repose sur le conteneur de services de Symfony, qui propose une meilleure option : la décoration. Cet article montre comment l’utiliser proprement, et comment éviter ses pièges.

Le principe

Un décorateur est un service qui prend la place d’un autre service tout en recevant l’original en argument. Tous les consommateurs reçoivent le décorateur sans le savoir, et le décorateur délègue à l’original ce qu’il ne veut pas modifier.

Avant :   consommateur ──> service original
Après :   consommateur ──> décorateur ──> service original (.inner)

Contrairement au remplacement de classe, plusieurs décorateurs peuvent s’empiler sur le même service : chacun enveloppe le précédent.

Un cas réel : enrichir l’autocomplétion d’entités

Sur un site avec beaucoup de contenus homonymes, les contributeurs ne savent pas quel « Rapport annuel » choisir dans un champ de référence. On veut afficher le type de contenu à côté du titre, pour tous les champs de référence, sans toucher au widget.

Le service responsable est entity.autocomplete_matcher, qui implémente EntityAutocompleteMatcherInterface.

Déclarer le décorateur

# my_module.services.yml
services:
  my_module.entity_autocomplete_matcher:
    class: Drupal\my_module\Entity\BundleAwareAutocompleteMatcher
    decorates: entity.autocomplete_matcher
    arguments: ['@.inner', '@entity_type.manager']

@.inner désigne le service décoré (la syntaxe courte est disponible depuis Symfony 5.1, Drupal 10 tourne sur Symfony 6). Sur d’anciens projets, vous verrez la forme longue @my_module.entity_autocomplete_matcher.inner.

Implémenter le décorateur

<?php

namespace Drupal\my_module\Entity;

use Drupal\Component\Utility\Html;
use Drupal\Core\Entity\Element\EntityAutocomplete;
use Drupal\Core\Entity\EntityAutocompleteMatcherInterface;
use Drupal\Core\Entity\EntityTypeManagerInterface;

final class BundleAwareAutocompleteMatcher implements EntityAutocompleteMatcherInterface {

  public function __construct(
    private readonly EntityAutocompleteMatcherInterface $inner,
    private readonly EntityTypeManagerInterface $entityTypeManager,
  ) {}

  public function getMatches($target_type, $selection_handler, $selection_settings, $string = '') {
    $matches = $this->inner->getMatches($target_type, $selection_handler, $selection_settings, $string);
    if ($target_type !== 'node' || !$matches) {
      return $matches;
    }

    $ids = array_map(
      fn (array $match) => EntityAutocomplete::extractEntityIdFromAutocompleteInput($match['value']),
      $matches
    );
    $nodes = $this->entityTypeManager->getStorage('node')->loadMultiple(array_filter($ids));
    $bundles = $this->entityTypeManager->getStorage('node_type')->loadMultiple();

    foreach ($matches as $i => $match) {
      $node = $nodes[$ids[$i]] ?? NULL;
      if ($node && isset($bundles[$node->bundle()])) {
        $matches[$i]['label'] .= ' <small>(' . Html::escape($bundles[$node->bundle()]->label()) . ')</small>';
      }
    }
    return $matches;
  }

}

Un drush cr, et tous les champs de référence du site affichent le type de contenu. Aucune classe du cœur n’a été modifiée, et la prochaine mise à jour de Drupal n’y changera rien.

Le label d’un résultat d’autocomplétion est du HTML déjà échappé par le matcher d’origine : on échappe donc uniquement ce qu’on ajoute.

L’ordre des décorateurs : decoration_priority

Quand plusieurs modules décorent le même service, l’ordre se règle avec decoration_priority (0 par défaut). Plus la priorité est haute, plus le décorateur est appliqué tôt, donc plus il est proche du service original :

services:
  module_a.matcher:
    decorates: entity.autocomplete_matcher
    decoration_priority: 10
  module_b.matcher:
    decorates: entity.autocomplete_matcher
    decoration_priority: 1

Résultat : module_b.matcher(module_a.matcher(original)). Le consommateur appelle d’abord module_b.

Pour décorer un service qui n’existe que si un module optionnel est activé, ajoutez decoration_on_invalid: ignore : le décorateur est alors simplement retiré si le service décoré est absent, au lieu de faire planter la reconstruction du conteneur.

Les alternatives, et quand les préférer

ServiceProvider : modifier une définition

Une classe {NomDuModule}ServiceProvider (en CamelCase, à la racine du namespace du module) est découverte automatiquement. Sa méthode alter() permet de modifier n’importe quelle définition :

<?php

namespace Drupal\my_module;

use Drupal\Core\DependencyInjection\ContainerBuilder;
use Drupal\Core\DependencyInjection\ServiceProviderBase;

final class MyModuleServiceProvider extends ServiceProviderBase {

  public function alter(ContainerBuilder $container) {
    if ($container->hasDefinition('some.service')) {
      $container->getDefinition('some.service')
        ->setArgument(2, '%my_module.custom_ttl%');
    }
  }

}

C’est le bon outil pour changer un argument, un tag ou un paramètre. Utilisé pour faire un setClass(), il devient un remplacement de classe, avec le problème du « dernier module gagne » : si deux modules remplacent la même classe, l’un des deux est silencieusement ignoré.

La méthode register() du même provider permet d’enregistrer des services conditionnellement, par exemple seulement si un module est activé ($container->getParameter('container.modules')).

Compiler pass : agir sur tout le conteneur

Pour collecter tous les services portant un tag, ou transformer plusieurs définitions d’un coup, enregistrez un compiler pass depuis register() :

public function register(ContainerBuilder $container) {
  $container->addCompilerPass(new ReportGeneratorPass());
}

C’est puissant mais rarement nécessaire dans un module applicatif. Pour la simple collecte de services tagués, Drupal propose déjà le tag service_collector.

Le tableau de décision

Besoin Outil
Réagir à un événement, modifier des données Hook ou event subscriber
Remplacer un plugin hook_*_info_alter()
Changer un argument ou un paramètre d’un service ServiceProvider::alter()
Modifier le comportement d’un service, en restant compatible avec d’autres modules Décoration
Agir sur de nombreux services d’un coup Compiler pass

Les pièges

1. Le consommateur type sur la classe concrète

La décoration ne fonctionne que si tous les consommateurs dépendent de l’interface. Si un module type son constructeur sur la classe concrète (EntityAutocompleteMatcher $matcher), votre décorateur provoque une TypeError au premier appel. Vérifiez avant de décorer :

grep -rn "EntityAutocompleteMatcher \$" web/core web/modules/contrib

Si le service n’a pas d’interface, le seul recours est d’étendre la classe d’origine dans le décorateur, et vous perdez l’empilement propre.

2. Oublier une méthode de l’interface

Le décorateur doit implémenter toutes les méthodes de l’interface et déléguer celles qu’il ne modifie pas. Le jour où l’interface gagne une méthode (cela arrive entre versions mineures), votre décorateur doit suivre. Un test Kernel suffit à le détecter.

3. Les services avec état

Si le service d’origine expose des setters ou garde un état interne (setX() puis getY()), déléguez tous les appels à $this->inner. Un décorateur qui garde sa propre copie d’état produit des bugs très difficiles à suivre.

4. Le cache du conteneur

La définition des services est compilée et mise en cache. Après toute modification d’un services.yml ou d’un ServiceProvider, un drush cr est obligatoire. En déploiement, c’est déjà le cas avec drush deploy.

Tester le décorateur

Un test Kernel vérifie à la fois l’enregistrement et le comportement :

public function testDecoratorIsRegistered(): void {
  $matcher = $this->container->get('entity.autocomplete_matcher');
  $this->assertInstanceOf(BundleAwareAutocompleteMatcher::class, $matcher);
}

Si un autre module décore le même service avec une priorité plus basse, ce test échoue : c’est voulu, il documente l’ordre attendu.

Conclusion

La décoration est le moyen le plus propre de modifier le comportement d’un service dans Drupal : pas de patch à maintenir, pas de conflit avec les autres modules, et une intention lisible dans le services.yml. La règle à retenir : décorer pour changer le comportement, alter() pour changer la configuration, hooks et événements dès qu’ils existent.

Suite de la série →Inbound et outbound processing dans Drupal : principes et exemples