
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
labeld’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.
