Plugin API de Drupal : comprendre, utiliser et créer ses propres plugins

· 13 min de lecture

Si vous avez déjà créé un bloc personnalisé dans Drupal, vous avez écrit un plugin. Si vous avez écrit un formateur de champ, un filtre de texte, un process plugin de migration ou un handler Views : encore des plugins. C’est probablement le mécanisme d’extension le plus utilisé du cœur, et pourtant beaucoup de développeurs l’utilisent par copier-coller sans vraiment savoir ce qui se passe.

Cet article part de zéro : à quoi sert le système de plugins, comment Drupal trouve vos classes, comment créer un plugin d’un type existant, puis comment définir votre propre type de plugin. Tous les exemples utilisent la syntaxe actuelle de Drupal 11 (attributs PHP) et ont été vérifiés dans le code du cœur 11.3.

Le problème que résout la Plugin API

Imaginons un module qui doit envoyer des notifications : par e-mail aujourd’hui, sur Slack demain, par SMS peut-être plus tard. Trois besoins apparaissent :

  1. Plusieurs implémentations interchangeables d’un même contrat (« envoyer une notification »).
  2. Découverte automatique : un autre module doit pouvoir ajouter un canal (Teams, webhook…) sans modifier le vôtre.
  3. Des métadonnées exploitables sans instancier la classe : un libellé pour une liste déroulante, une description pour l’interface d’administration.

Un simple service ne coche pas ces cases : il n’existe qu’une implémentation active à la fois. Un hook non plus : il n’offre ni contrat d’interface, ni configuration par instance. C’est exactement ce que fournit la Plugin API.

Un plugin, c’est une petite classe interchangeable, qui implémente une interface commune, découverte automatiquement par Drupal et décrite par des métadonnées.

Le vocabulaire

Cinq notions suffisent pour tout comprendre.

Notion Rôle Exemple pour les blocs
Type de plugin Le contrat : une interface et une convention de dossier Les blocs : BlockPluginInterface, dossier src/Plugin/Block
Définition Les métadonnées d’un plugin, lues sans l’instancier id, admin_label, category
Découverte Le mécanisme qui trouve les définitions Lecture des attributs #[Block(...)]
Plugin manager Le service qui découvre, met en cache et instancie plugin.manager.block
Instance Un objet plugin avec sa configuration Le bloc « Derniers articles » placé dans la sidebar, configuré pour 5 éléments

Le point essentiel : une même classe peut donner plusieurs instances, chacune avec sa configuration. Placez deux fois le même bloc dans deux régions, avec des réglages différents : c’est une classe, deux instances.

Comment Drupal trouve vos plugins

Quand on appelle getDefinitions() sur un plugin manager :

  1. Le manager parcourt le sous-dossier convenu (src/Plugin/Block pour les blocs) dans chaque module activé, en se basant sur les namespaces PSR-4.
  2. Il lit l’attribut PHP de chaque classe trouvée (#[Block(...)]) et en tire la définition.
  3. Il passe les derivers (on y vient plus bas), qui peuvent générer plusieurs définitions à partir d’une seule.
  4. Il invoque un hook d’alter (hook_block_alter()) qui permet à d’autres modules de modifier les définitions.
  5. Il met le résultat en cache dans le bin cache.discovery.

Puis, createInstance($plugin_id, $configuration) instancie la classe correspondante.

Cette mise en cache explique le réflexe numéro un quand un plugin n’apparaît pas : drush cr. Tant que le cache de découverte n’est pas vidé, Drupal ne voit pas votre nouvelle classe.

Attributs PHP ou annotations ?

Jusqu’à Drupal 10.1, les définitions s’écrivaient dans des annotations Doctrine (commentaires @Block(...)). Depuis Drupal 10.2, le cœur utilise les attributs PHP 8 :

// Ancienne syntaxe (annotation)
/**
 * @Block(
 *   id = "my_block",
 *   admin_label = @Translation("My block"),
 * )
 */

// Syntaxe actuelle (attribut)
#[Block(
  id: 'my_block',
  admin_label: new TranslatableMarkup('My block'),
)]

Les annotations fonctionnent encore pour les types de plugins qui proposent un attribut, mais elles déclenchent une dépréciation et seront supprimées dans Drupal 13. Tout nouveau code doit utiliser les attributs ; tout code existant peut migrer dès maintenant.

Étape 1 : créer un plugin d’un type existant

Commençons par le cas le plus courant : un bloc qui affiche les derniers articles publiés, avec un nombre d’éléments configurable.

Fichier src/Plugin/Block/LatestArticlesBlock.php du module my_module :

<?php

declare(strict_types=1);

namespace Drupal\my_module\Plugin\Block;

use Drupal\Core\Block\Attribute\Block;
use Drupal\Core\Block\BlockBase;
use Drupal\Core\Entity\EntityTypeManagerInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
use Drupal\Core\StringTranslation\TranslatableMarkup;

#[Block(
  id: 'my_module_latest_articles',
  admin_label: new TranslatableMarkup('Derniers articles'),
  category: new TranslatableMarkup('Mon module'),
)]
final class LatestArticlesBlock extends BlockBase implements ContainerFactoryPluginInterface {

  public function __construct(
    array $configuration,
    $plugin_id,
    $plugin_definition,
    private readonly EntityTypeManagerInterface $entityTypeManager,
  ) {
    parent::__construct($configuration, $plugin_id, $plugin_definition);
  }

  public function defaultConfiguration(): array {
    return ['count' => 5];
  }

  public function blockForm($form, FormStateInterface $form_state): array {
    $form['count'] = [
      '#type' => 'number',
      '#title' => $this->t('Nombre d’articles'),
      '#min' => 1,
      '#max' => 20,
      '#default_value' => $this->configuration['count'],
    ];
    return $form;
  }

  public function blockSubmit($form, FormStateInterface $form_state): void {
    $this->configuration['count'] = (int) $form_state->getValue('count');
  }

  public function build(): array {
    $storage = $this->entityTypeManager->getStorage('node');
    $ids = $storage->getQuery()
      ->accessCheck(TRUE)
      ->condition('type', 'article')
      ->condition('status', 1)
      ->sort('created', 'DESC')
      ->range(0, $this->configuration['count'])
      ->execute();

    $items = [];
    foreach ($storage->loadMultiple($ids) as $node) {
      $items[] = $node->toLink()->toRenderable();
    }

    return [
      '#theme' => 'item_list',
      '#items' => $items,
      // Le bloc doit être invalidé dès qu'un nœud est créé, modifié ou supprimé.
      '#cache' => ['tags' => ['node_list']],
    ];
  }

}

Ce qu’il faut retenir :

  • L’emplacement est imposé : src/Plugin/Block, namespace Drupal\my_module\Plugin\Block. Un dossier mal nommé et le plugin est invisible, sans aucune erreur.
  • L’attribut se trouve dans Drupal\Core\Block\Attribute\Block. Attention à l’import automatique de votre IDE, qui propose parfois l’ancienne classe d’annotation Drupal\Core\Block\Annotation\Block.
  • $this->configuration contient la configuration de cette instance. defaultConfiguration() en fournit les valeurs par défaut, blockForm() et blockSubmit() gèrent le formulaire.
  • Les métadonnées de cache sont de votre responsabilité : sans le tag node_list, le bloc afficherait la même liste jusqu’au prochain vidage de cache. Voir l’article sur la Cache API.

L’injection de dépendances, avec ou sans create()

Le plugin implémente ContainerFactoryPluginInterface : c’est le signal qui dit au manager « passe-moi le conteneur de services ». Historiquement, il fallait écrire une méthode create() pour aller chercher chaque service :

public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition): static {
  return new static(
    $configuration,
    $plugin_id,
    $plugin_definition,
    $container->get('entity_type.manager'),
  );
}

Avec Drupal 11.3, ce n’est plus nécessaire : Drupal\Core\Plugin\PluginBase fournit une méthode create() qui autowire les arguments du constructeur à partir de leur type (EntityTypeManagerInterface est un alias du service entity_type.manager). C’est ce qui permet à l’exemple ci-dessus de s’en passer. Si votre module doit rester compatible avec des versions antérieures, gardez la méthode create() explicite.

Quand le type ne suffit pas à identifier le service (plusieurs services implémentent la même interface), l’attribut Symfony #[Autowire] précise le service voulu :

use Symfony\Component\DependencyInjection\Attribute\Autowire;

public function __construct(
  array $configuration,
  $plugin_id,
  $plugin_definition,
  #[Autowire(service: 'cache.data')]
  private readonly CacheBackendInterface $cache,
) {

Le schéma de configuration

La configuration d’un bloc placé est exportée avec drush cex. Déclarez son schéma dans config/schema/my_module.schema.yml, sinon la validation de la configuration et les tests vous le rappelleront :

block.settings.my_module_latest_articles:
  type: block_settings
  label: 'Derniers articles'
  mapping:
    count:
      type: integer
      label: 'Nombre d’articles'

Étape 2 : créer son propre type de plugin

C’est là que la Plugin API devient vraiment puissante. Reprenons le module de notifications : nous voulons que n’importe quel module puisse ajouter un canal de notification.

Il faut cinq éléments :

notifier/
├── notifier.services.yml               # le service plugin manager
└── src/
    ├── Attribute/Notifier.php          # l'attribut qui décrit un plugin
    ├── NotifierInterface.php           # le contrat
    ├── NotifierPluginBase.php          # une classe de base pratique
    ├── NotifierPluginManager.php       # le manager
    └── Plugin/Notifier/EmailNotifier.php   # un premier plugin

1. L’attribut : ce qui décrit un plugin

<?php

declare(strict_types=1);

namespace Drupal\notifier\Attribute;

use Drupal\Component\Plugin\Attribute\Plugin;
use Drupal\Core\StringTranslation\TranslatableMarkup;

/**
 * Defines a Notifier plugin.
 */
#[\Attribute(\Attribute::TARGET_CLASS)]
final class Notifier extends Plugin {

  public function __construct(
    public readonly string $id,
    public readonly TranslatableMarkup $label,
    public readonly ?TranslatableMarkup $description = NULL,
    public readonly ?string $deriver = NULL,
  ) {}

}

Chaque propriété publique devient une clé de la définition : $definition['label'], $definition['description']. La propriété deriver est facultative, mais la prévoir dès maintenant ne coûte rien.

2. Le contrat

<?php

declare(strict_types=1);

namespace Drupal\notifier;

use Drupal\Component\Plugin\PluginInspectionInterface;

interface NotifierInterface extends PluginInspectionInterface {

  /**
   * The human-readable name of the channel.
   */
  public function label(): string;

  /**
   * Sends a notification. Returns TRUE on success.
   */
  public function send(string $subject, string $message): bool;

}

PluginInspectionInterface apporte getPluginId() et getPluginDefinition(), que tout plugin devrait exposer.

3. La classe de base

<?php

declare(strict_types=1);

namespace Drupal\notifier;

use Drupal\Core\Plugin\PluginBase;

abstract class NotifierPluginBase extends PluginBase implements NotifierInterface {

  public function label(): string {
    return (string) $this->pluginDefinition['label'];
  }

}

Elle factorise ce qui est commun à tous les canaux. Les autres modules hériteront de cette classe plutôt que de réimplémenter l’interface de zéro.

4. Le plugin manager

<?php

declare(strict_types=1);

namespace Drupal\notifier;

use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\Extension\ModuleHandlerInterface;
use Drupal\Core\Plugin\DefaultPluginManager;
use Drupal\notifier\Attribute\Notifier;

final class NotifierPluginManager extends DefaultPluginManager {

  public function __construct(
    \Traversable $namespaces,
    CacheBackendInterface $cache_backend,
    ModuleHandlerInterface $module_handler,
  ) {
    parent::__construct(
      'Plugin/Notifier',          // Sous-dossier scanné dans chaque module.
      $namespaces,
      $module_handler,
      NotifierInterface::class,   // Interface que chaque plugin doit implémenter.
      Notifier::class,            // Attribut qui porte la définition.
    );
    // Permet aux autres modules d'implémenter hook_notifier_info_alter().
    $this->alterInfo('notifier_info');
    // Met les définitions en cache dans cache.discovery.
    $this->setCacheBackend($cache_backend, 'notifier_plugins');
  }

}

DefaultPluginManager fait tout le travail : découverte par attributs, derivers, hook d’alter, cache et instanciation (y compris l’appel à create()).

5. Le service

# notifier.services.yml
services:
  plugin.manager.notifier:
    class: Drupal\notifier\NotifierPluginManager
    parent: default_plugin_manager

Le service parent default_plugin_manager fournit les trois arguments du constructeur : les namespaces des modules, le cache cache.discovery et le module handler.

Un premier plugin

<?php

declare(strict_types=1);

namespace Drupal\notifier\Plugin\Notifier;

use Drupal\Core\Mail\MailManagerInterface;
use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
use Drupal\Core\StringTranslation\TranslatableMarkup;
use Drupal\notifier\Attribute\Notifier;
use Drupal\notifier\NotifierPluginBase;

#[Notifier(
  id: 'email',
  label: new TranslatableMarkup('E-mail'),
  description: new TranslatableMarkup('Envoie la notification par e-mail.'),
)]
final class EmailNotifier extends NotifierPluginBase implements ContainerFactoryPluginInterface {

  public function __construct(
    array $configuration,
    $plugin_id,
    $plugin_definition,
    private readonly MailManagerInterface $mailManager,
  ) {
    parent::__construct($configuration, $plugin_id, $plugin_definition);
  }

  public function send(string $subject, string $message): bool {
    // Le message est construit dans hook_mail(), non montré ici.
    $result = $this->mailManager->mail(
      'notifier',
      'notification',
      $this->configuration['to'],
      'fr',
      ['subject' => $subject, 'message' => $message],
    );
    return (bool) $result['result'];
  }

}

Utiliser le type de plugin

/** @var \Drupal\notifier\NotifierPluginManager $manager */
$manager = \Drupal::service('plugin.manager.notifier');

// Lister les canaux disponibles, sans instancier aucune classe.
$options = [];
foreach ($manager->getDefinitions() as $id => $definition) {
  $options[$id] = $definition['label'];
}

// Instancier un canal avec sa configuration, puis l'utiliser.
$notifier = $manager->createInstance('email', ['to' => 'ops@example.com']);
$notifier->send('Import terminé', '1 234 produits importés.');

Dans une classe (contrôleur, service, formulaire), injectez plugin.manager.notifier plutôt que d’appeler \Drupal::service().

Désormais, un module tiers n’a qu’à déposer une classe dans son dossier src/Plugin/Notifier avec l’attribut #[Notifier] : après un drush cr, son canal apparaît dans $options, sans une ligne de modification dans votre module.

Étape 3 : les derivers, un plugin qui en génère plusieurs

Nouveau besoin : un canal Slack par salon configuré. Les salons sont définis dans la configuration du site (#alertes, #mises-en-prod…) et l’administrateur doit voir un canal par salon dans la liste.

Écrire une classe par salon n’a pas de sens : la liste change sans déploiement. C’est le rôle d’un deriver : une classe qui, à partir d’une définition de base, génère autant de définitions que nécessaire.

#[Notifier(
  id: 'slack',
  label: new TranslatableMarkup('Slack'),
  deriver: SlackChannelDeriver::class,
)]
final class SlackNotifier extends NotifierPluginBase implements ContainerFactoryPluginInterface {

  public function __construct(
    array $configuration,
    $plugin_id,
    $plugin_definition,
    private readonly ClientInterface $httpClient,
    private readonly ConfigFactoryInterface $configFactory,
  ) {
    parent::__construct($configuration, $plugin_id, $plugin_definition);
  }

  public function send(string $subject, string $message): bool {
    // getDerivativeId() renvoie la partie après les deux-points : "alertes" pour "slack:alertes".
    $channel = $this->getDerivativeId();
    $webhook = $this->configFactory->get('notifier.settings')->get("slack_channels.$channel.webhook");
    $response = $this->httpClient->request('POST', $webhook, [
      'json' => ['text' => "*$subject*\n$message"],
    ]);
    return $response->getStatusCode() === 200;
  }

}

Le deriver, dans src/Plugin/Derivative/SlackChannelDeriver.php :

<?php

declare(strict_types=1);

namespace Drupal\notifier\Plugin\Derivative;

use Drupal\Component\Plugin\Derivative\DeriverBase;
use Drupal\Core\Config\ConfigFactoryInterface;
use Drupal\Core\Plugin\Discovery\ContainerDeriverInterface;
use Drupal\Core\StringTranslation\TranslatableMarkup;
use Symfony\Component\DependencyInjection\ContainerInterface;

final class SlackChannelDeriver extends DeriverBase implements ContainerDeriverInterface {

  public function __construct(
    private readonly ConfigFactoryInterface $configFactory,
  ) {}

  public static function create(ContainerInterface $container, $base_plugin_id): static {
    return new static($container->get('config.factory'));
  }

  public function getDerivativeDefinitions($base_plugin_definition): array {
    $channels = $this->configFactory->get('notifier.settings')->get('slack_channels') ?? [];
    foreach ($channels as $key => $channel) {
      $this->derivatives[$key] = [
        'label' => new TranslatableMarkup('Slack : @name', ['@name' => $channel['name']]),
      ] + $base_plugin_definition;
    }
    return $this->derivatives;
  }

}

Avec deux salons configurés, getDefinitions() renvoie maintenant email, slack:alertes et slack:mises-en-prod. L’identifiant d’un plugin dérivé suit toujours la forme base:dérivé, et le plugin connaît les deux parties via getBaseId() et getDerivativeId().

Les derivers sont partout dans le cœur : un bloc de menu par menu (system_menu_block:main), un bloc par vue et par display (views_block:…), un lien local par type d’entité…

Deux règles importantes :

  • Les définitions dérivées sont mises en cache. Quand la liste des salons change, videz le cache des définitions, par exemple dans le submitForm() du formulaire de réglages : $this->notifierManager->clearCachedDefinitions();.
  • Ne mettez pas de secret dans une définition. Les définitions sont stockées dans cache.discovery et exposées à tous les modules via le hook d’alter. C’est pour cette raison que l’URL du webhook est lue dans la configuration au moment de l’envoi, et non stockée dans la définition.

Laisser les autres modules modifier les définitions

Grâce à alterInfo('notifier_info'), n’importe quel module peut modifier les définitions avant leur mise en cache. Avec les hooks orientés objet de Drupal 11 :

<?php

declare(strict_types=1);

namespace Drupal\my_module\Hook;

use Drupal\Core\Hook\Attribute\Hook;
use Drupal\my_module\Notifier\AuditedEmailNotifier;

final class NotifierHooks {

  #[Hook('notifier_info_alter')]
  public function notifierInfoAlter(array &$definitions): void {
    // Remplacer la classe du canal e-mail par une version qui journalise chaque envoi.
    $definitions['email']['class'] = AuditedEmailNotifier::class;
  }

}

C’est le moyen propre de remplacer l’implémentation d’un plugin fourni par un autre module, sans patch.

Plugin, service, service taggé ou événement ?

La Plugin API n’est pas la réponse à tout. Voici comment choisir.

Besoin Outil Exemple
Une seule implémentation, remplaçable globalement Service (éventuellement décoré) Le générateur d’URL
Plusieurs implémentations, toutes appelées, dans un ordre de priorité Services taggés (collecteurs) Les path processors, les breadcrumb builders
Réagir à quelque chose qui se produit Événement (Event API) ou hook Une réponse HTTP qui part, une entité enregistrée
Plusieurs implémentations au choix, avec un libellé pour l’interface et une configuration par instance Plugin Blocs, formateurs de champ, canaux de notification

Le signal le plus fiable : si l’administrateur ou le code appelant choisit une implémentation parmi plusieurs et lui donne des réglages, c’est un plugin.

Déboguer

Lister les plugins connus d’un manager :

drush php:eval 'print_r(array_keys(\Drupal::service("plugin.manager.notifier")->getDefinitions()));'

Inspecter une définition précise, par exemple pour vérifier la classe utilisée après un hook d’alter :

drush php:eval 'print_r(\Drupal::service("plugin.manager.block")->getDefinition("system_branding_block"));'

Et, toujours, après avoir ajouté ou déplacé une classe de plugin :

drush cr

Les pièges classiques

1. Le plugin n’apparaît pas. Dans l’ordre : cache non vidé, dossier ou namespace qui ne correspond pas (src/Plugin/Notifier ↔ Drupal\mon_module\Plugin\Notifier), attribut importé depuis le mauvais namespace, module non activé. Aucun de ces cas ne produit d’erreur : le plugin est simplement ignoré.

2. Deux plugins avec le même identifiant. Le dernier découvert l’emporte, sans avertissement. Préfixez vos identifiants avec le nom du module (my_module_latest_articles).

3. Des objets dans la configuration. La configuration d’une instance est souvent exportée en YAML (blocs, formateurs). Elle ne doit contenir que des valeurs scalaires et des tableaux, et doit être décrite par un schéma.

4. Un deriver trop coûteux. Le deriver s’exécute à chaque reconstruction du cache de découverte. Charger des milliers d’entités pour générer des définitions ralentit chaque drush cr et chaque premier accès après un vidage de cache.

5. Oublier les métadonnées de cache dans les plugins de rendu. Un bloc qui affiche des données sans tags ni contextes de cache affichera des données périmées, ou pire, celles d’un autre utilisateur. Voir l’article sur le contrôle d’accès et la cacheabilité.

6. Continuer à écrire des annotations. Elles fonctionnent encore, mais sont dépréciées et disparaîtront avec Drupal 13. Autant écrire du code qui n’aura pas à être migré.

Checklist

  • Le besoin justifie un plugin : plusieurs implémentations au choix, avec métadonnées et configuration par instance.
  • L’attribut décrit tout ce dont l’interface d’administration a besoin, sans avoir à instancier la classe.
  • L’interface étend PluginInspectionInterface, et une classe de base factorise le code commun.
  • Le manager étend DefaultPluginManager, appelle alterInfo() et setCacheBackend().
  • Le service hérite de default_plugin_manager.
  • Les plugins reçoivent leurs dépendances par injection, jamais par \Drupal::service().
  • La configuration des instances a un schéma.
  • Les derivers sont légers, et le cache des définitions est vidé quand leur source change.
  • Aucune donnée sensible dans les définitions.

La Plugin API demande un peu de structure au départ : un attribut, une interface, un manager, un service. En échange, votre module devient extensible par n’importe quel autre module, exactement comme le cœur de Drupal.