Aller au contenu

Référence : bus d'événements des plugins

Cette page décrit les deux canaux par lesquels le cœur communique avec les plugins de diffusion : le message Messenger asynchrone ArticlePublished (un transport par plugin) et les événements Symfony synchrones in-request. Elle est neutre et exhaustive ; pour le pourquoi de ces choix, voir Architecture des plugins de diffusion. Pour le contrat implémenté par un plugin, voir Référence : contrat de plugin.

Message ArticlePublished

App\Message\ArticlePublished — src/Message/ArticlePublished.php.

Élément Valeur
Classe final readonly class ArticlePublished
Constructeur public function __construct(public Uuid $articleId)
Propriété public Uuid $articleId (Symfony\Component\Uid\Uuid)
  • Le message transporte l'identifiant de l'article, jamais l'entité Article : le message est sérialisé et traverse RabbitMQ, ce qui détacherait une entité Doctrine. Le handler du plugin recharge l'article via son propre repository.
  • Pas de pluginKey dans le message : chaque handler sait à quel plugin il appartient grâce à son fromTransport (voir plus bas).

Transport par plugin

Chaque plugin possède son propre transport Messenger, nommé par convention plugin_<clé> (ex. plugin_web), avec exchange et queue dédiés. Une file qui tombe n'affecte pas les autres plugins ni le cœur (isolation d'échec).

Le cœur ne déclare aucun transport de plugin. config/packages/messenger.yaml ne connaît que async, failed et sync : chaque plugin déclare le sien depuis son bundle, dans prependExtension(), qui s'exécute avant le chargement des extensions et peut donc écrire dans la configuration de framework.

Déclaration du transport du plugin web (src/Plugin/Web/src/KirexoPluginWebBundle.php), référence pour tout nouveau plugin :

$isTest = 'test' === $builder->getParameter('kernel.environment');

$container->extension('framework', [
    'messenger' => [
        'transports' => [
            'plugin_web' => $isTest ? 'sync://' : [
                'dsn' => '%env(MESSENGER_TRANSPORT_PLUGIN_WEB_DSN)%',
                'options' => [
                    'exchange' => ['name' => 'plugin_web', 'type' => 'fanout'],
                    'queues' => ['plugin_web' => null],
                ],
                'retry_strategy' => ['max_retries' => 3, 'multiplier' => 2],
            ],
        ],
    ],
], prepend: true);

Le DSN vit dans une variable d'environnement dédiée (MESSENGER_TRANSPORT_PLUGIN_WEB_DSN), dont le défaut est posé par le bundle lui-même ($builder->setParameter('env(NOM)', …), via EnvVarManifest) — le .env de l'application n'a rien à déclarer pour qu'un plugin fonctionne. Cf. la référence des variables d'environnement.

Pourquoi la déclaration vit dans le bundle

C'est ce qui rend un plugin réellement amovible : retirer sa ligne de config/bundles.php retire aussi son transport, son défaut d'env et son mapping. Une entrée laissée dans la configuration du cœur ferait échouer le boot sur une variable d'environnement que plus personne ne définit.

En test, le transport reste nommé mais passe en sync://

La variation est décidée dans le même prependExtension(), à partir de kernel.environment : en test, plugin_web vaut sync:// — mais il s'appelle toujours plugin_web.

En sync://, le senderAlias transmis vaut le nom du transport. Un handler déclaré fromTransport: 'plugin_web' matche donc quand même : les tests d'intégration des handlers de plugin fonctionnent sans RabbitMQ. Renommer le transport en sync le rendrait muet en test, sans erreur.

Ciblage au dispatch : TransportNamesStamp

Le message n'a aucune entrée routing statique. Le ciblage est dynamique, décidé au dispatch via Symfony\Component\Messenger\Stamp\TransportNamesStamp, dont le constructeur prend le tableau des transports concernés. Le stamp prime sur le routing statique.

$this->bus->dispatch(
    new ArticlePublished($article->getId()),
    [new TransportNamesStamp($transports)],
);

Un seul dispatch porte l'array de tous les transports concernés : identité de message unique, isolation d'échec préservée (chaque file est consommée indépendamment).

Condition d'inclusion d'un transport plugin_<clé> dans le stamp :

Condition Détail
Destination cochée <clé> ∈ clés de destination de l'article (Article::$platforms).
Plugin actif pour l'auteur plugin->isEnabledFor($article->getAuthor()) renvoie true.

Si aucun transport n'est retenu (aucune destination cochée et activée, ou registre vide), aucun dispatch n'a lieu.

Réception : #[AsMessageHandler(fromTransport: ...)]

Un plugin consomme son message via un handler annoté avec son transport :

#[AsMessageHandler(fromTransport: 'plugin_web')]

Symfony\Component\Messenger\Attribute\AsMessageHandler : le handler ne se déclenche que pour les messages reçus du transport nommé. Un même ArticlePublished consommé sur une autre file ne réveille pas ce handler — c'est l'isolation par plugin.

Déclencheur : transition workflow

ArticlePublished est dispatché depuis App\EventSubscriber\ArticlePublishedSubscriber (src/EventSubscriber/ArticlePublishedSubscriber.php), abonné aux événements de complétion des transitions du workflow article :

Événement Méthode
workflow.article.completed.publish onPublished
workflow.article.completed.republish onPublished

Point d'ancrage unique : aucun dispatch éparpillé dans les controllers ou Live Components. Le subscriber vérifie que le sujet est un Article, puis délègue au dispatcher App\Plugin\Event\ArticlePublishDispatcherInterface (src/Plugin/Event/ArticlePublishDispatcher.php), qui applique le ciblage décrit plus haut.

Événements Symfony synchrones : PluginContributionEvent

App\Plugin\Event\PluginContributionEvent — src/Plugin/Event/PluginContributionEvent.php. Canal synchrone in-process (pas Messenger) pour les contributions in-request des plugins (ex. options d'écriture). C'est un accumulateur, donc final class ... extends Event non readonly.

Membre Signature Rôle
Constructeur __construct(public readonly string $slot) $slot identifie le point d'extension in-request (ex. 'article.write_options').
addContribution addContribution(string $contribution): void Ajoute une contribution.
getContributions getContributions(): array list<string> des contributions accumulées, dans l'ordre d'ajout (bag vide au départ).

Événements de domaine de l'état d'un compte

Deux événements Symfony synchrones signalent aux plugins qu'un compte perd ou retrouve sa présence publique. Le pourquoi est discuté dans Cycle de vie d'un compte.

Classe Fichier Sens
App\Plugin\Event\UserAccessRevoked src/Plugin/Event/UserAccessRevoked.php Le compte perd toute présence publique.
App\Plugin\Event\UserAccessRestored src/Plugin/Event/UserAccessRestored.php Le compte redevient actif et retrouve sa présence publique.

Forme

Les deux classes ont la même forme :

Élément Valeur
Classe final readonly class, sans héritage de Symfony\Contracts\EventDispatcher\Event
Constructeur public function __construct(public Uuid $userId)
Propriété public Uuid $userId (Symfony\Component\Uid\Uuid), identifiant du compte
Nom d'écoute FQCN de la classe (dispatch sans nom explicite)
  • L'événement porte l'identifiant du compte, jamais l'entité App\Entity\User : un plugin n'a pas à connaître l'entité du cœur pour réagir.
  • Pas d'héritage d'Event, donc pas de stopPropagation() : tous les abonnés reçoivent l'événement.

Émission

Émis par App\Service\User\AccountStateManager (src/Service/User/AccountStateManager.php), via Symfony\Contracts\EventDispatcher\EventDispatcherInterface :

Événement Méthode émettrice Condition
UserAccessRevoked disable() Désactivation effective d'un compte actif.
UserAccessRevoked delete() Suppression logique effective d'un compte, y compris s'il était déjà désactivé.
UserAccessRestored enable() Réactivation effective d'un compte désactivé et non supprimé.

restore() (réintégration d'un compte supprimé) n'émet aucun événement : le compte revient désactivé, il reste donc sans présence publique.

Aucun événement n'est émis sur un refus : invariant administrateur (selfRevocation, lastActiveAdmin), compte disparu (accountGone), déjà dans l'état visé (accountStateChanged) ou non supprimé (notDeleted). Les refus sont levés avant le dispatch.

Ordre et transaction

Le dispatch est la dernière instruction de la closure passée à UserRepositoryInterface::transactional(), après save() avec flush du compte relu sous verrou :

  1. écriture de l'état (et, pour disable() et delete(), de la note de modération éventuelle) puis flush ;
  2. dispatch synchrone de l'événement : les abonnés s'exécutent dans la transaction et voient l'état écrit ;
  3. commit ;
  4. après le commit : entrée d'audit, puis e-mail de justification pour disable() et delete().

Un abonné qui lève une exception fait échouer l'opération entière : rollback de l'état et de la note de modération, EntityManager fermé, exception relancée. Aucune entrée d'audit de réussite n'est écrite et aucun e-mail de justification ne part.

Un effet de bord non transactionnel n'est pas annulé

Le rollback annule les écritures en base, pas ce qu'un abonné a fait ailleurs. Une invalidation de cache effectuée avant l'exception d'un autre abonné reste acquise ; le cache se reconstruit à la requête suivante.

Abonné du plugin Web : UserAccessCacheSubscriber

Kirexo\Plugin\Web\EventSubscriber\UserAccessCacheSubscriber — src/Plugin/Web/src/EventSubscriber/UserAccessCacheSubscriber.php.

Événement Méthode Effet
UserAccessRevoked onUserAccessRevoked Invalide le cache de rendu de chaque site du compte.
UserAccessRestored onUserAccessRestored Idem.
  • Les sites sont lus par SiteRepositoryInterface::findByUserId(Uuid $userId): array (list<Site>, un site par carnet configuré, toutes clés de thème). Chaque site est passé à SiteCacheInterface::invalidateSite(), qui invalide le tag du site dans le pool Redis tag-aware.
  • Compte sans site : aucune invalidation.
  • Enregistré par autoconfiguration (EventSubscriberInterface), sans ligne dans src/Plugin/Web/config/services.yaml.
  • Révocation et restauration ont le même effet : c'est le gate SitePublicAccessCheckerInterface qui décide du 404, pas le cache.

Événement de suppression définitive : UserPurged

App\Plugin\Event\UserPurged — src/Plugin/Event/UserPurged.php. Événement Symfony synchrone qui demande aux plugins de détruire les données qu'ils tiennent pour un compte sur le point d'être effacé. Le pourquoi est discuté dans Cycle de vie d'un compte.

Forme

Élément Valeur
Classe final readonly class UserPurged, sans héritage de Symfony\Contracts\EventDispatcher\Event
Constructeur public function __construct(public Uuid $userId)
Propriété public Uuid $userId (Symfony\Component\Uid\Uuid), identifiant du compte effacé
Nom d'écoute FQCN de la classe (dispatch sans nom explicite)

L'événement porte l'identifiant, jamais l'entité App\Entity\User : la ligne du compte est supprimée dans la même transaction, juste après le dispatch.

Émission

Émis uniquement par App\Service\User\AccountPurger::purge() (src/Service/User/AccountPurger.php), via Symfony\Contracts\EventDispatcher\EventDispatcherInterface, dans la closure passée à UserRepositoryInterface::transactional() :

  1. relecture verrouillée du compte (findForUpdate()) ;
  2. refus alreadyPurged si la ligne n'existe plus, refus notDeleted si deletedAt est null : aucun événement n'est émis sur un refus ;
  3. dispatch synchrone de UserPurged ;
  4. UserRepositoryInterface::remove($compte, true) : un seul flush envoie les suppressions programmées par les abonnés, puis le DELETE du compte ; la base applique ensuite ses clés étrangères (ON DELETE CASCADE / SET NULL) ;
  5. commit.

Contrat imposé à un abonné

Règle Détail
Synchrone, dans la transaction L'abonné s'exécute avant le DELETE du compte, sur la même connexion. Les lignes du compte sont encore lisibles.
Détruire, pas masquer L'abonné supprime toutes les données qu'il rattache à $userId. Ce que le plugin ne supprime pas lui-même, seule une clé étrangère vers "user" peut l'emporter ; une référence faible (colonne UUID sans clé étrangère) resterait orpheline.
Sans condition d'activation L'abonné agit même si le plugin n'est pas, ou plus, activé pour ce compte : ses données restent en base après une désactivation du plugin et doivent disparaître quand même.
flush: false L'abonné programme ses suppressions (remove() sans flush). C'est AccountPurger qui flushe, dans la transaction.
Une exception annule tout Toute exception levée par un abonné remonte : rollback complet (rien n'est supprimé, ni côté plugin ni côté cœur), EntityManager fermé, audit account.purge_failed au niveau error, puis AccountPurgeException::failed(). Voir Journal d'audit.
Aucune donnée personnelle dans une exception L'entrée account.purge_failed porte l'exception complète dans la clé exception de son contexte, et le journal audit est la seule trace qui survit à l'effacement. Le message d'une exception levée par un abonné, comme les exceptions qu'elle chaîne, ne contient donc jamais de donnée personnelle (adresse e-mail, prénom, nom de domaine, titre…) : uniquement des identifiants (Uuid).
Pas de stopPropagation() Classe sans héritage d'Event : tous les abonnés reçoivent l'événement.

Un effet de bord non transactionnel n'est pas annulé

Comme pour UserAccessRevoked, le rollback n'annule que les écritures en base. Une invalidation de cache faite par un abonné avant l'échec d'un autre reste acquise ; le compte étant déjà non actif, le gate public répond 404 et rien n'est remis en cache entre-temps.

Abonné du plugin Web : UserPurgedSubscriber

Kirexo\Plugin\Web\EventSubscriber\UserPurgedSubscriber — src/Plugin/Web/src/EventSubscriber/UserPurgedSubscriber.php.

Événement Méthode
UserPurged onUserPurged

Effets, dans l'ordre :

Données Lecture Traitement Données entraînées
Sites SiteRepositoryInterface::findByUserId($event->userId) Pour chaque site : SiteCacheInterface::invalidateSite($site), puis SiteRepositoryInterface::remove($site, false). Domaines et pages spéciales du site, par ON DELETE CASCADE en base.
Thèmes personnels ThemeRepositoryInterface::findByUserId($event->userId) Pour chaque thème : ThemeRepositoryInterface::remove($theme, false). —
  • Aucune condition sur l'activation du plugin Web pour le compte.
  • Compte sans site ni thème : aucun appel.
  • Aucune invalidation propre aux thèmes.
  • Enregistré par autoconfiguration (EventSubscriberInterface), sans ligne dans src/Plugin/Web/config/services.yaml.

Voir aussi