DEV Community: DamienGR

Drupal Service Decorators : L'art de modifier l'existant sans tout casser

DamienGR — Fri, 19 Dec 2025 08:52:04 +0000

On a tous connu ce moment de solitude face à une demande client un peu trop spécifique.

Vous savez, ce moment où le service par défaut du cœur de Drupal fait 95% du travail, mais qu'il manque ce petit détail crucial pour le projet. La tentation est grande, surtout quand on débute, de copier-coller la classe entière dans un module custom, ou pire (ne mentez pas, on a les noms), de patcher directement le fichier source en se disant "je ferai ça proprement plus tard".

Soyons clairs : c'est la meilleure recette pour transformer une maintenance de routine en cauchemar lors de la prochaine mise à jour de sécurité.

Heureusement, si vous cherchez à surcharger un service Drupal proprement, l'architecture du CMS nous offre une solution élégante issue des design patterns orientés objet : le Drupal Service Decorator.

Au lieu de remplacer brutalement une classe ou de bidouiller des hooks à n'en plus finir, le décorateur nous permet d'envelopper un service existant pour en modifier la logique métier sans toucher à son intégrité. C’est propre, c’est pérenne, et c’est totalement intégré au conteneur de Drupal Dependency Injection.

Dans cet article, on va voir ensemble comment implémenter ce pattern pour altérer le comportement natif de Drupal sans jamais compromettre la stabilité de votre application. Vous allez voir, une fois qu'on a compris la mécanique du fichier services.yml, c'est un outil dont on ne peut plus se passer.

Partie 1 : Le concept (Promis, on fait court)

Avant d'ouvrir votre IDE, il faut bien visualiser ce que nous allons construire. Le Decorator Pattern n'est pas une invention spécifique à Drupal ; c'est un grand classique des Design Patterns (merci le Gang of Four) utilisé massivement dans le développement logiciel moderne.

Pour faire simple : imaginez des poupées russes.

Le service original de Drupal (celui que vous voulez modifier) est la petite poupée au centre. Votre Service Decorator, c'est la poupée plus grande qui vient englober la première.

De l'extérieur, pour le reste de l'application, rien ne change. Votre décorateur "ressemble" au service original car il implémente exactement la même Interface. Mais techniquement, c'est votre classe qui intercepte les appels en premier.

Pourquoi ne pas simplement faire un `extends` ?

C'est la question que tout développeur PHP se pose au début. "Pourquoi s'embêter avec un décorateur alors que je pourrais juste étendre la classe originale et surcharger la méthode ?"

La réponse tient en un principe clé : Composition over Inheritance (La composition plutôt que l'héritage).

Si vous étendez directement une classe du cœur de Drupal (extends CoreClass), vous créez un couplage fort. Le jour où une mise à jour mineure de Drupal modifie le constructeur de cette classe parente ou marque une méthode comme final, votre site plante (WSOD).

Avec un Décorateur, c'est différent :

Isolation : Vous injectez le service original à l'intérieur de votre service (Composition).
Sécurité : Si le code interne du service original change, votre décorateur continue souvent de fonctionner tant que l'Interface (le contrat) est respectée.
Cumulable : Le plus beau ? On peut empiler plusieurs décorateurs sur un même service. Module A décore le service, puis Module B décore le résultat du Module A. C'est infiniment plus souple que l'héritage linéaire.

En résumé, décorer un service, c'est appliquer une couche de vernis custom sur une logique existante, sans jamais rayer la peinture d'origine.

Partie 2 : La mise en place technique (Le "Hard" Skill)

La beauté du décorateur sous Drupal, c'est qu'il ne nécessite aucune librairie externe ou hack obscur. Tout se passe entre votre déclaration de service (YAML) et votre classe (PHP).

1. La déclaration : `services.yml`

C'est ici que tout se joue. Pour dire à Drupal "Hé, n'utilise pas le service standard, utilise le mien à la place", nous allons utiliser la propriété magique decorates.

Voici à quoi ressemble une déclaration typique dans votre fichier mon_module.services.yml :

services:
  mon_module.mon_super_decorator:
    class: Drupal\mon_module\MyServiceDecorator
    # C'est cette ligne qui fait le lien
    decorates: system.service_original
    # La priorité définit l'ordre d'exécution si plusieurs décorateurs existent
    decoration_priority: 10
    # On masque ce service car il n'a pas vocation à être appelé directement
    public: false
    arguments:
      # L'argument magique : on injecte le service qu'on est en train de remplacer !
      - '@mon_module.mon_super_decorator.inner'
      - '@current_user' # On peut aussi injecter d'autres services si besoin

Les points clés pour le SEO technique (et pour que ça marche) :

decorates : L'ID du service que vous voulez surcharger (ex: entity_type.manager ou logger.factory).
.inner : Remarquez l'argument '@mon_module.mon_super_decorator.inner'. Drupal renomme automatiquement l'ancien service en lui ajoutant le suffixe .inner. C'est crucial : c'est ce qui nous permettra d'appeler la méthode originale à la fin de notre traitement.
decoration_priority : Plus le chiffre est élevé, plus votre décorateur sera exécuté "tôt" (c'est-à-dire qu'il sera la couche la plus externe de l'oignon).

2. La Classe PHP : L'art de la délégation

Maintenant, créons notre classe. La règle d'or ici est le Type Hinting. Votre classe doit implémenter la même Interface que le service original. Sinon, Drupal rejettera votre décorateur lors de la compilation du conteneur.

Voici une structure robuste que j'utilise sur mes projets :

namespace Drupal\mon_module;

// On importe l'interface du service original
use Drupal\Core\SomeComponent\OriginalServiceInterface;

class MyServiceDecorator implements OriginalServiceInterface {

  /**
   * Le service original décoré (la poupée interne).
   *
   * @var \Drupal\Core\SomeComponent\OriginalServiceInterface
   */
  protected $innerService;

  /**
   * Constructeur.
   *
   * @param \Drupal\Core\SomeComponent\OriginalServiceInterface $inner_service
   * Le service original renommé.
   */
  public function __construct(OriginalServiceInterface $inner_service) {
    $this->innerService = $inner_service;
  }

  /**
   * Méthode que l'on souhaite modifier.
   */
  public function laMethodeCible($arg1) {
    // 1. Logique AVANT (Ex: Vérification de permission, Log)
    // ... votre code custom ...

    // 2. Appel du service original (Délégation)
    $result = $this->innerService->laMethodeCible($arg1);

    // 3. Logique APRÈS (Ex: Modification du résultat)
    return $result;
  }

  /**
   * L'astuce de Senior : La méthode magique __call.
   *
   * Elle permet de déléguer automatiquement toutes les autres méthodes
   * de l'interface sans avoir à les réécrire une par une.
   */
  public function __call($method, $args) {
    return call_user_func_array([$this->innerService, $method], $args);
  }
}

L'astuce __call :
C'est souvent ce qui différencie un code verbeux d'un code maintenable. Si l'interface du service original contient 20 méthodes et que vous ne voulez en modifier qu'une seule, utiliser __call vous évite d'écrire 19 méthodes "passe-plats" inutiles.

Partie 3 : Cas concret – "Le Gardien des Emails"

Passons à la pratique. Imaginons que le cahier des charges impose une restriction métier stricte : aucun email provenant du domaine @spambot.com ne doit être considéré comme valide par Drupal.

Si vous étiez un développeur junior, vous auriez probablement cherché à utiliser un hook_form_alter sur le formulaire d'inscription. Mais que se passe-t-il si l'utilisateur est créé via une API REST ? Ou via une commande Drush ? Votre hook est contourné.

C'est là que le Service Decorator brille. En surchargeant le validateur d'email au niveau le plus bas, on sécurise toutes les portes d'entrée simultanément.

1. Le fichier `my_security.services.yml`

On cible le service core email.validator.

services:
  my_security.email_validator_decorator:
    class: Drupal\my_security\EmailValidatorDecorator
    # On cible le service qui gère la validation des emails dans le Core
    decorates: email.validator
    # Une priorité haute pour passer avant d'autres potentiels validateurs
    decoration_priority: 10
    public: false
    arguments:
      # Injection de l'instance originale (le service natif)
      - '@my_security.email_validator_decorator.inner'

2. La Classe `EmailValidatorDecorator.php`

C'est ici qu'on implémente notre logique métier. Notez l'importance de respecter l'interface EmailValidatorInterface.

namespace Drupal\my_security;

use Drupal\Component\Utility\EmailValidatorInterface;

/**
 * Décore le validateur d'email pour bloquer les domaines interdits.
 */
class EmailValidatorDecorator implements EmailValidatorInterface {

  /**
   * Le service original (le coeur de Drupal).
   *
   * @var \Drupal\Component\Utility\EmailValidatorInterface
   */
  protected $innerService;

  /**
   * Liste des domaines blacklistés (pourrait venir de la config).
   */
  protected $blacklistedDomains = ['spambot.com', 'evil-corp.com'];

  /**
   * Constructeur.
   */
  public function __construct(EmailValidatorInterface $inner_service) {
    $this->innerService = $inner_service;
  }

  /**
   * {@inheritdoc}
   */
  public function isValid($email, $checkDNS = FALSE) {
    // 1. Notre logique custom "AVANT"
    // On extrait le domaine de l'email
    $parts = explode('@', $email);
    $domain = array_pop($parts);

    if (in_array($domain, $this->blacklistedDomains)) {
      // Si le domaine est interdit, on refuse immédiatement
      // sans même déranger le service parent.
      return FALSE;
    }

    // 2. Délégation "PENDANT"
    // Si notre check passe, on laisse le service natif faire son travail
    // (vérifier la syntaxe RFC, le DNS, etc.)
    return $this->innerService->isValid($email, $checkDNS);
  }
}

Pourquoi c'est élégant ?

Regardez bien ce qui se passe dans la méthode isValid.
Si le domaine est interdit, je retourne FALSE directement. Je n'appelle même pas $this->innerService->isValid(). J'ai court-circuité la logique standard pour imposer ma règle métier, économisant au passage des ressources (pourquoi faire une vérification DNS coûteuse sur un domaine qu'on sait interdit ?).

À l'inverse, si le domaine est autorisé, je rends la main au Core. Je ne réinvente pas la roue de la validation RFC des emails (ce qui serait complexe et source d'erreurs), je me contente d'ajouter ma petite couche de sécurité par-dessus.

C'est ça, la puissance du décorateur : Intercepter, Filtrer, Déléguer.

Partie 4 : Les pièges à éviter (Parce qu'on est entre pros)

C'est bien beau de tout décorer, mais comme tout outil puissant, il est possible de se tirer une balle dans le pied si on manque de rigueur. Voici trois points de vigilance que j'ai relevés au fil de mes projets.

1. La guerre des priorités (`decoration_priority`)

Si vous utilisez plusieurs modules contribs qui décorent tous le même service (par exemple entity_type.manager), l'ordre d'exécution devient capital.
Rappelez-vous de l'image de l'oignon ou des poupées russes :

Priorité haute = Couche extérieure (s'exécute en premier).
Priorité basse = Couche intérieure (s'exécute juste avant le service original).

Si votre décorateur doit absolument passer avant un autre (pour bloquer une action par exemple), assurez-vous de définir une priorité supérieure dans votre YAML.

2. Le débogage peut devenir... intéressant

Quand vous débuggez un service décoré, get_class($service) ne va plus vous retourner Drupal\Core\...\OriginalClass, mais Drupal\mon_module\MonDecorateur.
Si vous avez empilé 3 décorateurs, la stack trace peut devenir intimidante.

Mon conseil : Utilisez la commande Drush pour inspecter votre conteneur et vérifier qui décore quoi :
drush devel:services | grep mon_service (si vous avez le module Devel) ou vérifiez simplement votre compilation dans le dossier sites/default/files/php.

3. Ne faites pas de la "Sur-ingénierie"

Le décorateur est l'outil ultime quand on doit remplacer ou bloquer une logique.
Cependant, si Drupal propose déjà un Event (via EventSubscriber) ou un Hook pour faire ce que vous voulez, utilisez-les.

Besoin d'agir après qu'une entité soit sauvée ? -> hook_entity_insert.
Besoin de changer la façon dont l'entité est sauvée ? -> Decorateur.

Choisir le bon outil, c'est ce qui différencie le senior du bricoleur.

Conclusion

Le Drupal Service Decorator est probablement l'un des patterns les plus sous-estimés par les développeurs intermédiaires. Il offre une propreté de code et une stabilité face aux mises à jour que les "hacks" à l'ancienne ne pourront jamais égaler.

En maîtrisant ce concept, vous ne subissez plus l'architecture de Drupal : vous la pliez à vos besoins, proprement. C'est exactement le genre de dette technique négative (ou d'investissement technique) qui fait la différence sur la longévité d'un projet complexe.

Alors la prochaine fois que vous vous apprêtez à dire à votre client "Ce n'est pas possible, c'est le fonctionnement natif de Drupal", relisez votre fichier services.yml. Il y a sûrement un décorateur pour ça.

🚀 Besoin d'une architecture Drupal sur-mesure ?

Vous avez un projet complexe qui nécessite de sortir des sentiers battus sans casser le Core ? Je suis développeur Drupal spécialisé dans les architectures techniques avancées et le développement de modules custom.

Contactez-moi pour discuter de votre projet

Retrouvez mes autres articles sur dg-tech.dev

Au-delà du Code Coverage : Guide pratique du Mutation Testing pour des applications robustes

DamienGR — Sun, 07 Dec 2025 09:36:38 +0000

On connaît tous ce petit shot de dopamine.

Vous poussez votre code, la pipeline CI/CD se lance, et quelques minutes plus tard... c'est le "Green Build". Toutes les lumières sont au vert, et votre dashboard affiche fièrement un Code Coverage de 90% (voire 100% pour les plus zélés).

Sur le papier, la qualité logicielle semble irréprochable. Vous dormez sur vos deux oreilles.

Pourtant, deux jours plus tard, un bug critique explose en production sur une fonctionnalité que vous pensiez blindée. Comment est-ce possible ? Vos tests automatisés sont passés, non ?

C’est ici qu’il faut se dire une vérité qui dérange : avoir une couverture de code élevée ne garantit absolument pas que votre application fonctionne. Cela garantit seulement que votre code a été exécuté, pas qu'il a été vérifié.

Si vous voulez vraiment dormir tranquille et assurer la fiabilité des tests unitaires, il faut arrêter de se fier uniquement à la couverture et passer à l'étape supérieure : le Mutation Testing.

Dans cet article, nous allons voir pourquoi vos tests actuels vous donnent peut-être une fausse impression de sécurité, et comment l'approche "Code Coverage vs Mutation Testing" peut transformer la robustesse de vos projets web.

I. Le Code Coverage : Un indicateur utile, mais dangereux

Avant de tirer à boulets rouges sur la couverture de code, soyons justes : c'est un indicateur nécessaire.

Concrètement, le Code Coverage mesure le pourcentage de lignes de votre code source qui ont été parcourues lors de l'exécution de vos tests unitaires.

Si vous avez 10% de couverture, vous avez un problème évident : votre application est une boîte noire et chaque mise en production est un pari risqué. C’est un excellent outil pour repérer le "code mort" ou les branches logiques que vous avez totalement oublié de traiter (comme ce fameux else dans votre condition qui ne se déclenche qu'une fois par an).

Le piège de la "Vanity Metric"

Le problème survient quand on transforme cet indicateur en objectif absolu.

En tant que développeur, je peux très facilement vous écrire une suite de tests qui affiche 100% de coverage mais qui ne teste... absolument rien.

Comment ? C'est simple : il suffit d'exécuter le code sans faire d'assertions (sans vérifier le résultat).

Le Code Coverage garantit que le code a été exécuté. Il ne garantit pas qu'il a fonctionné correctement.

L'analogie du gardien de sécurité

Pour expliquer ça à mes clients, j'utilise souvent cette image :

Imaginez que vous embauchiez un agent de sécurité pour surveiller votre maison. Sa mission est de vérifier toutes les pièces (le coverage).
L'agent entre dans le salon, va dans la cuisine, monte dans les chambres, et ressort.

A-t-il visité 100% des pièces ? Oui.
A-t-il vérifié que les fenêtres étaient fermées ? Non.
A-t-il vérifié que le gaz était coupé ? Non.
A-t-il vu le cambrioleur caché derrière les rideaux ? Non.

Il est juste "passé par là". C'est exactement ce que font beaucoup de tests automatisés : ils passent dans les fonctions pour faire monter le compteur de couverture, mais ils ne vérifient pas assez strictement les règles métier.

C'est là que nous avons besoin d'un agent de sécurité plus paranoïaque. C'est là qu'intervient le Mutation Testing.

II. Le Mutation Testing : Qui surveille les surveillants ?

Si le Code Coverage vérifie si votre code est exécuté, le Mutation Testing (ou tests de mutation) vérifie si vos tests sont utiles.

La philosophie est radicalement différente. Au lieu de regarder le code, on va tester... les tests.

Le principe est un peu contre-intuitif au premier abord, mais génialement efficace : pour s'assurer que vos tests sont capables de détecter des bugs, nous allons volontairement introduire des bugs dans votre application.

Comment ça marche concrètement ?

Le processus est entièrement automatisé par des outils de mutation testing (comme Stryker, Infection ou PITest). Voici ce qui se passe dans votre pipeline :

L'outil prend votre code source sain.
Il crée une copie modifiée (un "Mutant") en changeant une toute petite règle logique.
- Exemple : Il change un + en -.
- Exemple : Il remplace un return true par return false.
- Exemple : Il supprime un appel de fonction.
Il lance votre suite de tests face à ce Mutant.

C'est là que tout se joue.

"Mutant Killed" vs "Mutant Survived"

C'est le seul moment dans votre vie de développeur où vous allez espérer que vos tests échouent.

Scénario 1 : Le test passe (C'est VERT 🟢) → C'est MAUVAIS.
Le code a été saboté, mais votre test ne s'en est pas rendu compte. Il continue de dire "Tout va bien".
Le mutant a survécu (Mutant Survived). Cela prouve que votre test est inefficace ou incomplet sur cette partie du code.
Scénario 2 : Le test échoue (C'est ROUGE 🔴) → C'est BON.
Le test a détecté que le code avait changé et a levé une alerte.
Le mutant a été tué (Mutant Killed). Votre test est robuste : il joue bien son rôle de gardien.

Le MSI : La seule métrique de confiance

À la fin de l'analyse, l'outil vous donne un score : le MSI (Mutation Score Indicator).

C'est le pourcentage de mutants que vos tests ont réussi à tuer.
Avoir 100% de Code Coverage avec un MSI de 50% signifie qu'une ligne de code sur deux peut être cassée sans que personne ne s'en aperçoive avant la mise en production.

C'est cette métrique qui sépare les suites de tests "pour faire joli" des véritables filets de sécurité qui garantissent la qualité du code sur le long terme.

III. Exemple Concret : Quand le mutant survit

La théorie est belle, mais voyons comment cela se traduit dans votre IDE. Prenons un cas classique de logique métier : une règle d'éligibilité.

Pour que tout le monde comprenne, je vais utiliser une syntaxe très simple.

L'erreur de frontière (Le classique)

Imaginons une fonction simple qui détermine si un utilisateur a droit à une promotion. La règle est : "Dépenser strictement plus de 100€".

Le Code Source :

function isEligibleForDiscount(amount) {
    if (amount > 100) {
        return true;
    }
    return false;
}

Vos Tests Unitaires (Coverage 100%) :
Vous écrivez deux tests logiques :

J'envoie 50 -> Je m'attends à false. (OK)
J'envoie 150 -> Je m'attends à true. (OK)

Votre suite de tests est verte. Votre coverage est à 100%. Vous êtes content.

L'attaque du Mutant :
L'outil de mutation testing va générer un mutant en modifiant l'opérateur de comparaison. Il change > (supérieur) par >= (supérieur ou égal).

// Code Muté par l'outil
function isEligibleForDiscount(amount) {
    if (amount >= 100) { // Le mutant est ici !
        return true;
    }
    return false;
}

Le Résultat :
Vos tests actuels (50 et 150) donnent exactement le même résultat avec le code original ET avec le code muté.

50 est toujours < 100 (False).
150 est toujours > 100 (True).

Verdict : Mutant Survived.
Le changement de code n'a pas été détecté. Cela signifie que si un développeur change par erreur la condition demain, ou si la règle métier change pour inclure 100€, vos tests ne vous alerteront pas. Pour tuer ce mutant, il manquait un cas limite : un test avec la valeur 100 exactement.

Les outils pour votre stack

Peu importe votre langage de prédilection, il existe un outil mature pour implémenter cette stratégie :

JavaScript / TypeScript : StrykerJS est la référence absolue.
PHP (Symfony/Laravel) : L'excellent Infection PHP est un must-have pour les applications critiques.
Java : PITest est le standard dans le monde Enterprise.
C# / .NET : Stryker.NET.

IV. Pourquoi investir là-dedans ?

C'est souvent ici que les managers tiquent. "Attends, tu veux lancer un outil qui va ralentir notre pipeline de déploiement pour tester des tests ?"

Oui. Et voici pourquoi c'est rentable.

1. Réduire la dette technique (pour de vrai)

On parle souvent de dette technique, mais rarement de comment la rembourser efficacement. Une suite de tests validée par du mutation testing est un filet de sécurité en béton. Elle permet de refactoriser du code legacy complexe sans la peur au ventre de tout casser.

2. La confiance au déploiement

Combien coûte une heure de bug critique en production ? Combien coûte l'image de marque d'un site e-commerce qui plante pendant les soldes ?
Le Mutation Testing demande plus de ressources CPU (c'est vrai, c'est un processus lent), mais ce coût est dérisoire comparé au coût d'un hotfix en urgence le week-end.

Astuce Pro : On ne lance pas forcément le mutation testing à chaque commit. On le lance sur les Pull Requests critiques ou dans une "Nightly Build" (la nuit).

3. Élever le niveau de l'équipe

L'effet secondaire génial du mutation testing, c'est qu'il force les développeurs à écrire de meilleurs tests dès le départ. On arrête de tester pour le coverage, on teste pour la robustesse. C'est une montée en compétence garantie pour toute l'équipe.

Conclusion : La Qualité est un choix

Le Code Coverage, c'est bien. C'est le minimum syndical. Mais si votre objectif est de construire des applications web durables, maintenables et fiables, il ne suffit pas.

Le Mutation Testing est l'étape qui sépare les amateurs des professionnels soucieux de la qualité réelle. Il enlève le doute. Il remplace la confiance aveugle par la certitude mathématique.

Vous préférez des lumières vertes qui vous mentent, ou des lumières rouges qui vous permettent de corriger les problèmes avant vos clients ?

👋 Besoin d'y voir plus clair ?

Vous avez un doute sur la fiabilité de vos tests actuels ? Vous avez 80% de coverage mais toujours des régressions en prod ?

Contactez-moi pour un audit rapide de votre stratégie de tests. Ensemble, on peut transformer votre CI/CD en véritable forteresse.