Architecture des plugins de diffusion¶
Cette page explique pourquoi les plugins de diffusion de Kirexo sont conçus ainsi — pas comment en écrire un (voir le tutoriel Écrire un plugin de diffusion), ni la liste des signatures (voir les références contrat et bus). Elle approfondit la section « Pourquoi les plugins sont des Symfony Bundles isolés » d'Architecture, sans la répéter.
Un plugin de diffusion est une destination vers laquelle un article publié est poussé : le web, RSS, ActivityPub/Mastodon, une API, et demain Telegram, LinkedIn, Discord. Le fil conducteur de toutes les décisions ci-dessous est une seule contrainte : on doit pouvoir ajouter ou supprimer une destination sans toucher au cœur.
Pourquoi un plugin est un bundle Symfony isolé¶
Chaque plugin est un Symfony Bundle autonome, avec son propre composer.json interne, son namespace propre (Kirexo\Plugin\<Nom>\) et ses services tagués. Cette autonomie n'est pas cosmétique : elle prépare un futur composer require kirexo/plugin-<nom> (via un path repository), où un plugin deviendra un paquet installable indépendamment. Tant que le plugin vit dans le monorepo, l'autoload passe par le composer.json racine ; le composer.json interne documente déjà le paquet pour cette bascule.
La contrainte forte — le supprimer ne casse rien — est ce qui force le découplage. Retirer un plugin, c'est retirer une ligne de config/bundles.php et un préfixe PSR-4 : la plateforme doit rebooter comme si le plugin n'avait jamais existé. Cela n'est possible que si aucune ligne du cœur ne référence le plugin par son nom. Le prix à payer est une surface de contrat un peu plus large ; le bénéfice est qu'ajouter une destination ne demande jamais de modifier le cœur.
Le bundle utilise la structure moderne (extends AbstractBundle, classe dans src/, loadExtension()), gabarit posé par src/Plugin/Web/src/KirexoPluginWebBundle.php.
Pourquoi un contrat dans un namespace neutre¶
Le contrat commun (DiffusionPluginInterface et ses types satellites) vit dans Kirexo\Plugin\Contracts\, pas dans App\. La raison est directe : un plugin destiné à un futur composer require ne peut pas dépendre de App\, le namespace de l'application. Si le contrat vivait dans App\, extraire un plugin le forcerait à tirer tout le cœur avec lui.
Le contrat est donc le seul pont partagé entre le cœur et les plugins. C'est aussi ce qui explique ses types :
publish(Uuid $articleId)reçoit un identifiant, jamais l'entitéApp\Entity\Article— que le plugin ne peut pas connaître, et qui serait de toute façon détachée après un aller-retour RabbitMQ. Le plugin recharge ce dont il a besoin via son propre read-side.isEnabledFor(UserInterface $user)type-hinteSymfony\Component\Security\Core\User\UserInterface, pasApp\Entity\User. L'entité du cœur implémente déjà cette interface : l'appelant est compatible, le contrat reste neutre.
Pourquoi un registre par tag plutôt qu'un tagged_locator¶
Les plugins sont agrégés dans App\Plugin\PluginRegistry, qui construit au constructeur une map clé → plugin en itérant les services tagués kirexo.plugin. On aurait pu utiliser un tagged_locator indexé par clé ; on ne l'a pas fait, et c'est délibéré.
La clé d'un plugin provient d'une méthode d'instance, key(). Un tagged_locator { index_by: 'key' } attendrait soit un attribut de tag key — que le cœur ne peut pas alimenter automatiquement, puisque le tag kirexo.plugin est posé génériquement, sans connaître l'implémenteur — soit une méthode statique getDefaultKeyName(), qui forcerait chaque plugin à dupliquer sa clé, source de désynchronisation.
Le point d'accroche du tag mérite d'ailleurs sa propre note, parce que la solution intuitive ne marche pas : un #[AutoconfigureTag] posé sur DiffusionPluginInterface ne se propage pas aux implémenteurs qui vivent dans un bundle, et le registre du cœur restait alors vide. Le tag est donc posé par un point d'autoconfiguration central, App\Kernel::build() → registerForAutoconfiguration() (src/Kernel.php). C'est ce qui évite de recopier un _instanceof dans le services.yaml de chaque plugin — une ligne de configuration à ne pas oublier étant exactement le genre de couplage que l'isolation cherche à supprimer.
La map construite au constructeur lit la clé depuis l'unique source de vérité ($plugin->key()), détecte les collisions au boot (deux plugins, même clé → \LogicException), et reste trivialement testable. Ce registre remplace l'ancien enum DiffusionPlatform : les destinations ne sont plus une énumération figée du cœur, mais l'ensemble ouvert des plugins enregistrés.
Pourquoi un transport Messenger par plugin¶
À la publication, le cœur ne fait pas d'appel direct aux plugins : il dispatche le message ArticlePublished, ciblé sur le ou les transports Messenger des plugins concernés. Chaque plugin a son propre transport plugin_<clé> (exchange et queue dédiés). Deux raisons :
- Isolation d'échec. Une file qui tombe — un plugin réseau lent, une API tierce en panne — n'affecte ni les autres plugins ni le cœur. Un échec côté Mastodon ne fait pas tomber la diffusion RSS.
- Ciblage dynamique. On n'ajoute aucune entrée
routingstatique pourArticlePublished: un routing figé enverrait le message à tous les plugins. À la place, le dispatcher pose unTransportNamesStampavec exactement les transports dont la destination est cochée sur l'article et dont le plugin est activé pour l'auteur. Le stamp prime sur le routing statique.
Ce découplage asynchrone n'est mobilisé que là où il compte : une diffusion réseau qu'on ne veut pas voir bloquer la requête de publication. Pour les contributions in-request (options d'écriture, etc.), le canal reste un événement Symfony synchrone (PluginContributionEvent), plus simple à raisonner. C'est la déclinaison, côté plugins, du principe « synchrone par défaut, Messenger pour l'asynchrone réel » d'Architecture.
Un plugin doit rester stateless en worker mode FrankenPHP¶
Kirexo tourne en worker mode FrankenPHP : l'interpréteur PHP reste chargé entre les requêtes. Le registre en tire parti — c'est un service partagé, instancié une seule fois, en lecture seule après construction : aucun état par requête, donc sûr en worker mode sans reset.
Cette propriété est aussi une contrainte pour vous : un plugin doit rester stateless entre les requêtes. Ne stockez pas d'état requête-spécifique dans une propriété d'un service partagé du plugin ; il serait vu par la requête suivante. Le raisonnement sur le worker mode est détaillé dans Architecture.
La frontière de sécurité du rendu personnalisé¶
Le plugin web va plus loin que les autres : il sert un site public dont tout l'habillage — en-tête, corps, pied de page, style — vient d'un thème, et le modèle prévoit des thèmes écrits par les utilisateurs. Or un site public est du contenu écrit par une personne et exécuté dans le navigateur d'une autre — la porte d'entrée classique du stored XSS.
C'est pourquoi le plugin web pousse toute personnalisation derrière une défense en profondeur : sandbox Twig, sanitizer HTML, CSS filtré, et CSP. Le principe est une liste blanche — autoriser explicitement ce qui est sûr, retirer tout le reste — plutôt que de tenter de deviner ce qui est dangereux. Cette frontière est propre au plugin web parce qu'il est le seul à exposer du rendu public arbitraire ; un plugin qui pousse vers une API n'a pas ce problème.
Le pourquoi détaillé de ces limites, côté utilisateur, est dans Ce que vous pouvez personnaliser sur votre site (et pourquoi ces limites) ; le modèle de thème lui-même dans Modèle de thème et catalogue fourni ; le détail technique des barrières dans Sécurité du rendu personnalisé des sites ; le comment faire dans le guide Personnaliser son site.
Voir aussi¶
- Architecture — les choix structurants de la plateforme (worker mode, services synchrones, Messenger).
- Référence : contrat de plugin — les signatures du contrat et du registre.
- Référence : bus d'événements des plugins —
ArticlePublished, transport par plugin, ciblage dynamique. - Pourquoi l'activation des plugins est asymétrique — verrou global côté admin, désactivation toujours possible côté utilisateur.
- Rendu public d'un site (plugin web) et Résolution multi-tenant : du domaine au site — le fonctionnement du plugin web.
- Pages spéciales du plugin web — un exemple d'extension propre à un plugin.
- Comment un plugin s'intègre à l'éditeur : destinations et aperçu — la capability d'aperçu, détectée sans toucher le cœur.