Aller au contenu

Référence : contrat de plugin (DiffusionPluginInterface)

Cette page décrit le contrat que tout plugin de diffusion Kirexo doit implémenter, ainsi que les types satellites (enums, descripteur de réglage) et le registre côté cœur. Elle est exhaustive et neutre : pour apprendre à écrire un plugin pas à pas, voir le tutoriel Écrire un plugin de diffusion ; pour le pourquoi de ces choix, voir Architecture des plugins de diffusion.

Le contrat vit dans le namespace neutre Kirexo\Plugin\Contracts\ (src/Plugin/Contracts/), volontairement découplé de App\ : un plugin n'importe jamais le cœur. Le registre, lui, reste côté cœur dans App\Plugin\ (src/Plugin/PluginRegistry.php).

DiffusionPluginInterface

Kirexo\Plugin\Contracts\DiffusionPluginInterface — src/Plugin/Contracts/DiffusionPluginInterface.php.

Toute classe qui implémente cette interface et qui est autoconfigurée est taguée kirexo.plugin et agrégée par le registre, sans aucune ligne de configuration à écrire — ni côté cœur, ni dans le services.yaml du plugin. Le tag est posé par un point d'autoconfiguration central : registerForAutoconfiguration(DiffusionPluginInterface::class)->addTag('kirexo.plugin'), dans App\Kernel::build() (src/Kernel.php).

Ce n'est pas un #[AutoconfigureTag] sur l'interface

Cet attribut y a figuré, et il ne fonctionnait pas : il ne se propage pas aux implémenteurs qui vivent dans un bundle — le registre restait vide, sans le moindre message. Il a été retiré au profit du point d'autoconfiguration central, qui évite en outre de recopier un _instanceof dans le services.yaml de chaque plugin.

Méthode Signature Retour Rôle
key key(): string string Clé technique unique du plugin (ex. 'web'). Sert de valeur de destination dans Article::$platforms et de clé d'indexation dans le registre.
label label(): string string Libellé d'affichage FR (ex. 'Web').
colorKey colorKey(): string string Clé de couleur de canal du design system (variable CSS --ch-<key>), pour les pastilles de la frise et les badges de destination (ex. 'web', 'rss', 'ap', 'api').
publish publish(Uuid $articleId): void void Diffuse l'article vers cette destination. Reçoit l'identifiant de l'article, jamais l'entité (voir ci-dessous).
globalSettings globalSettings(): array list<PluginSettingDescriptor> Réglages globaux du plugin (portée administrateur).
userSettings userSettings(): array list<PluginSettingDescriptor> Réglages par utilisateur.
isEnabledFor isEnabledFor(UserInterface $user): bool bool Le plugin se considère-t-il actif pour cet utilisateur ? Décision propre au plugin.

Types découplés : UserInterface et Uuid, jamais les entités App\

  • $user est typé Symfony\Component\Security\Core\User\UserInterface, pas App\Entity\User. La classe App\Entity\User implémente déjà UserInterface, donc l'appelant est compatible sans couplage côté contrat.
  • publish() reçoit un Symfony\Component\Uid\Uuid (l'identifiant de l'article), jamais l'entité App\Entity\Article. Le plugin recharge les données dont il a besoin via son propre read-side. Ce choix reflète ArticlePublished, qui transporte lui aussi l'Uuid seul (voir Référence : bus d'événements des plugins).

Types importés par le contrat (aucune dépendance à App\) :

  • Symfony\Component\Uid\Uuid
  • Symfony\Component\Security\Core\User\UserInterface

ArticlePreviewablePluginInterface (capability optionnelle)

Kirexo\Plugin\Contracts\ArticlePreviewablePluginInterface — src/Plugin/Contracts/ArticlePreviewablePluginInterface.php.

Capability optionnelle (ségrégation d'interface) : un plugin de diffusion qui sait produire un aperçu d'un article dans son cadre l'implémente en plus de DiffusionPluginInterface ; les autres ne la déclarent pas. Un plugin sans cette capability n'expose aucun bouton d'aperçu dans l'éditeur.

Méthode Signature Retour Rôle
previewRouteName previewRouteName(): string string Nom de la route d'aperçu de l'article dans le cadre du plugin.

Contrat de route : le paramètre {id}

La route désignée par previewRouteName() doit accepter le paramètre {id} = UUID rfc4122 de l'article. C'est la convention partagée par tout plugin prévisualisable ; elle permet au cœur de générer l'URL uniformément ($urls->generate($plugin->previewRouteName(), ['id' => $article->getId()->toRfc4122()])) sans connaître la route.

Détection : le Live Component App\Twig\Components\ArticleDestinations (src/Twig/Components/ArticleDestinations.php) teste instanceof ArticlePreviewablePluginInterface au rendu (pas d'autoconfiguration) et n'ajoute un previewUrl à la ligne de destination que pour les plugins capables. Exemple : Kirexo\Plugin\Web\WebDiffusionPlugin::previewRouteName() retourne 'web_plugin_article_preview'.

Le pourquoi de cette capability séparée est détaillé dans Comment un plugin s'intègre à l'éditeur : destinations et aperçu.

NotebookConfigurablePluginInterface (capability optionnelle)

Kirexo\Plugin\Contracts\NotebookConfigurablePluginInterface — src/Plugin/Contracts/NotebookConfigurablePluginInterface.php.

Capability optionnelle (ségrégation d'interface) : un plugin de diffusion configurable carnet par carnet l'implémente en plus de DiffusionPluginInterface ; les autres ne la déclarent pas. Un plugin sans cette capability n'expose aucun lien de configuration dans le menu ⋯ d'un carnet.

Méthode Signature Retour Rôle
notebookSettingsRouteName notebookSettingsRouteName(): string string Nom de la route de configuration du plugin pour un carnet donné.

Contrat de route : le paramètre {notebookId}

La route désignée par notebookSettingsRouteName() doit accepter le paramètre {notebookId} = UUID rfc4122 du carnet. C'est la convention partagée par tout plugin configurable par carnet ; elle permet au cœur de générer l'URL uniformément ($urls->generate($plugin->notebookSettingsRouteName(), ['notebookId' => $notebook->getId()->toRfc4122()])) sans connaître la route.

Détection : le composant Twig App\Twig\Components\NotebookConfigLinks (src/Twig/Components/NotebookConfigLinks.php) teste instanceof NotebookConfigurablePluginInterface au rendu (pas d'autoconfiguration) et n'ajoute un lien « Configurer … » que pour les plugins capables et actifs pour le propriétaire du carnet. Exemple : Kirexo\Plugin\Web\WebDiffusionPlugin::notebookSettingsRouteName() retourne 'web_plugin_site_settings'.

Le pourquoi de cette capability et son extensibilité sont détaillés dans Configuration par carnet et extensibilité des plugins.

UserMenuContributorInterface (capability optionnelle)

Kirexo\Plugin\Contracts\UserMenuContributorInterface — src/Plugin/Contracts/UserMenuContributorInterface.php.

Capability optionnelle (ségrégation d'interface) : un plugin de diffusion qui veut ajouter une entrée au menu de l'espace utilisateur l'implémente en plus de DiffusionPluginInterface ; les autres ne la déclarent pas. Un plugin sans cette capability ne contribue aucune entrée au menu.

Méthode Signature Retour Rôle
userMenuLabel userMenuLabel(): string string Libellé de l'entrée de menu (ex. 'Mes thèmes').
userMenuRouteName userMenuRouteName(): string string Nom de la route cible de l'entrée.

Contrat de route : aucun paramètre

Contrairement à NotebookConfigurablePluginInterface (dont la route attend {notebookId}), la route désignée par userMenuRouteName() ne doit prendre aucun paramètre. Sa portée est le compte de l'utilisateur connecté, pas un carnet ni un site : le cœur génère l'URL sans contexte ($urls->generate($plugin->userMenuRouteName())). C'est ce qui rend l'écran cible joignable sans carnet ni domaine configuré. Exemple : Kirexo\Plugin\Web\WebDiffusionPlugin::userMenuRouteName() retourne 'web_plugin_theme_index' (la bibliothèque de thèmes).

Détection et gating : le composant Twig App\Twig\Components\UserMenuPluginLinks (src/Twig/Components/UserMenuPluginLinks.php), rendu par le header via <twig:UserMenuPluginLinks />, itère le registre et teste instanceof UserMenuContributorInterface au rendu (pas d'autoconfiguration). Il n'ajoute une entrée que pour les plugins capables et actifs pour l'utilisateur courant — l'activation est résolue par App\Service\Plugin\PluginStateResolverInterface::resolve() puis PluginState::isActive(). Une fonctionnalité inaccessible n'est donc jamais révélée dans le menu.

Comme pour notebookSettingsRouteName(), le cœur ne cite aucune route de plugin en dur : c'est le même principe d'extensibilité que NotebookConfigurablePluginInterface (pattern 3, aucune dépendance cœur → plugin). Un plugin retiré ne laisse aucun résidu dans le menu ; un futur plugin (RSS, API, Mastodon…) qui déclare cette capability voit son entrée apparaître automatiquement, sans modification du cœur.

La place de cette entrée dans le menu du compte et son ordre sont décrits dans Header et menu utilisateur. Le parcours utilisateur correspondant est Accéder à mes thèmes.

PublicPresenceInventoryInterface (capability optionnelle)

Kirexo\Plugin\Contracts\PublicPresenceInventoryInterface — src/Plugin/Contracts/PublicPresenceInventoryInterface.php.

Capability optionnelle (ségrégation d'interface) : un plugin de diffusion qui donne à un compte une présence publique (domaines servis, identifiants sur un réseau, …) l'implémente en plus de DiffusionPluginInterface, pour que l'administration sache ce qui cessera d'être servi avant de supprimer ce compte. Un plugin sans cette capability ne contribue rien.

Méthode Signature Retour Rôle
publicPresenceLabels publicPresenceLabels(Uuid $ownerId): array list<string> Libellés lisibles de la présence publique du propriétaire identifié par $ownerId, dans un ordre stable. Liste vide si le propriétaire n'a aucune présence dans ce plugin.
  • Un libellé est une chaîne affichée telle quelle à l'administrateur, sans interprétation par le cœur. Le contrat est volontairement générique : un nom de domaine pour le plugin Web, un handle pour un plugin de fédération.
  • Le contrat ne dépend que de Symfony\Component\Uid\Uuid : l'identifiant du propriétaire, jamais l'entité App\Entity\User.
  • Aucun tag supplémentaire : le plugin est déjà tagué kirexo.plugin par DiffusionPluginInterface.

Agrégation : App\Service\User\PublicPresenceInventory (src/Service/User/PublicPresenceInventory.php), service du cœur qui n'implémente pas le contrat.

Méthode Signature Retour Comportement
labelsFor labelsFor(User $owner): array list<string> Itère PluginRegistryInterface::all(), ignore les plugins qui ne sont pas instanceof PublicPresenceInventoryInterface, concatène les libellés dans l'ordre des plugins puis des libellés, et retire les doublons (array_unique). Aucun plugin contributeur : liste vide, sans exception.

Le cœur ne cite aucune classe ni route de plugin : même principe d'extensibilité que UserMenuContributorInterface. Consommateurs : App\Controller\AppAdminUserDeleteController et App\Controller\AppAdminUserPurgeController, qui affichent les libellés dans l'écran d'avertissement de suppression d'un compte et dans celui de sa suppression définitive (rubrique « Présence publique » de templates/admin/users/_inventory.html.twig). Voir Gestion des comptes — référence.

Implémentation du plugin Web : Kirexo\Plugin\Web\WebDiffusionPlugin::publicPresenceLabels() renvoie SiteDomainRepositoryInterface::findHostsByUserId($ownerId) (src/Plugin/Web/src/Repository/SiteDomainRepository.php) :

  • les hôtes, normalisés en ASCII (punycode), de tous les domaines rattachés aux sites du propriétaire, quel que soit leur état ;
  • sans filtre sur l'activation du plugin pour le propriétaire : la capability décrit la présence configurée, pas ce qui est servi à l'instant ;
  • triés par hôte croissant, en une requête DQL, sans hydratation d'entité ni jointure vers la table "user" du cœur.

ServedHostsProviderInterface (capability optionnelle)

Kirexo\Plugin\Contracts\ServedHostsProviderInterface — src/Plugin/Contracts/ServedHostsProviderInterface.php.

Capability optionnelle : un plugin de diffusion qui sert des contenus sur ses propres noms d'hôte (domaines de site, …) l'implémente en plus de DiffusionPluginInterface, pour que le diagnostic d'installation vérifie que ces hôtes passent TRUSTED_HOSTS. Un plugin sans cette capability ne contribue aucun hôte.

Méthode Signature Retour Rôle
servedHosts servedHosts(): array list<string> Noms d'hôte servis publiquement par le plugin, normalisés (minuscules, ASCII/punycode), sans doublon. Liste vide si le plugin ne sert aucun hôte.
  • Le contrat ne dépend d'aucune classe App\.
  • Aucun tag supplémentaire : la capability est détectée par instanceof sur les plugins déjà présents dans PluginRegistryInterface (même mécanisme que PublicPresenceInventoryInterface).

Consommateur : App\Service\Install\Check\HostsCheck (src/Service/Install/Check/HostsCheck.php), contrôle Hôtes de la commande app:install:check. Il itère PluginRegistryInterface::all(), ignore les plugins qui ne sont pas instanceof ServedHostsProviderInterface, et ajoute leurs hôtes aux candidats du verdict TRUSTED_HOSTS compatible. Il n'est interrogé que si TRUSTED_HOSTS est défini. Voir Commande app:install:check — Hôtes.

Implémentation du plugin Web : Kirexo\Plugin\Web\WebDiffusionPlugin::servedHosts() rend les hôtes (SiteDomain::getHost()) de SiteDomainRepositoryInterface::findAll() (src/Plugin/Web/src/Repository/SiteDomainRepositoryInterface.php), dédoublonnés et réindexés :

  • tous les domaines de site, quel que soit leur état : un domaine en attente doit déjà passer TRUSTED_HOSTS pour être résolu puis validé ;
  • tous propriétaires confondus, sans filtre sur l'activation du plugin ;
  • findAll() est hérité de ServiceEntityRepository par SiteDomainRepository : il hydrate les entités SiteDomain.

PluginActivationCheckerInterface

Kirexo\Plugin\Contracts\PluginActivationCheckerInterface — src/Plugin/Contracts/PluginActivationCheckerInterface.php.

Abstraction découplée de l'état d'activation persistant d'un plugin, qu'un plugin peut injecter pour répondre à isEnabledFor() sans coupler au cœur. Dépend uniquement de UserInterface.

Méthode Signature Retour Rôle
isEnabledFor isEnabledFor(string $pluginKey, UserInterface $user): bool bool Le plugin identifié par $pluginKey est-il activé pour cet utilisateur, d'après l'état persistant du cœur ?

Deux isEnabledFor() de rôles inverses

  • DiffusionPluginInterface::isEnabledFor(UserInterface): bool — le plugin répond : « moi, plugin, suis-je actif pour cet utilisateur ? »
  • PluginActivationCheckerInterface::isEnabledFor(string $pluginKey, UserInterface): bool — service externe qu'un plugin interroge (indexé par $pluginKey, il sert tous les plugins). L'implémentation cœur résout l'état d'activation persistant.

SitePublicAccessCheckerInterface

Kirexo\Plugin\Contracts\SitePublicAccessCheckerInterface — src/Plugin/Contracts/SitePublicAccessCheckerInterface.php.

Abstraction découplée du gating d'un site public. Un plugin qui rend des pages publiques interroge ce service pour savoir si son plugin est activé — globalement et pour le propriétaire du site — sans connaître la logique d'activation du cœur.

Méthode Signature Retour Rôle
isPluginEnabledForOwner isPluginEnabledForOwner(string $pluginKey, Uuid $ownerId): bool bool Le site du propriétaire identifié par cet UUID est-il consultable ? true seulement si le propriétaire existe, est actif, et que le plugin est activé pour lui.

L'implémentation cœur App\Service\Plugin\SitePublicAccessChecker (src/Service/Plugin/SitePublicAccessChecker.php) évalue, dans cet ordre, en s'arrêtant au premier échec :

Étape Condition Échec
1 Le propriétaire existe (UserRepositoryInterface::findById()). false
2 Le propriétaire est actif : User::isActive(), vrai si disabledAt et deletedAt valent null. false, sans interroger l'activation
3 Le plugin est activé globalement et pour le propriétaire : PluginActivationCheckerInterface::isEnabledFor(). false

Le nom de la méthode est inchangé : seule sa sémantique inclut désormais l'état du compte. Le compte est relu à chaque appel ; aucun état n'est retenu entre deux requêtes.

Consommateur : Kirexo\Plugin\Web\EventSubscriber\HostResolutionSubscriber (src/Plugin/Web/src/EventSubscriber/HostResolutionSubscriber.php), sur kernel.request (priorité 33). Un retour false lève un 404 avant l'estampillage du domaine et avant la pose des attributs _kirexo_site et _kirexo_public_site. Toutes les routes publiques du bundle Web exigent _kirexo_public_site ; aucune ne répond donc, et aucun cache de rendu n'est lu :

Route publique Chemin
Accueil du site /
Article /{slug}/{id}
Page spéciale /{slug}
Feuille de style /site.css
Sonde /.kirexo/health

Le 404 est identique à celui d'un plugin non activé ou d'un domaine non mappé : il ne révèle pas que le compte est désactivé.

Résiduel : la feuille de style en cache côté client

WebPluginPublicStylesheetController (src/Plugin/Web/src/Controller/WebPluginPublicStylesheetController.php) sert /site.css avec Cache-Control: public, max-age=300. Après une désactivation, un navigateur ou un proxy intermédiaire peut encore servir sa copie pendant 5 minutes au plus. Il s'agit de CSS, pas de contenu ; toute requête qui atteint le serveur reçoit le 404.

Ce contrat ne dépend que de Symfony\Component\Uid\Uuid — l'identifiant, jamais l'entité, comme publish(). Pour le raisonnement complet, voir Cycle de vie d'un compte.

PluginState (enum backed string)

Kirexo\Plugin\Contracts\PluginState — src/Plugin/Contracts/PluginState.php. Les quatre états UI d'un plugin.

Case Valeur label() isActive() isLocked()
Unavailable 'unavailable' Indisponible false false
Available 'available' Disponible false false
Enabled 'enabled' Activé true false
EnabledLocked 'enabled_locked' Activé (verrouillé) true true

Méthodes :

Méthode Signature Rôle
label label(): string Libellé FR de l'état (match exhaustif).
isLocked isLocked(): bool true uniquement pour EnabledLocked.
isActive isActive(): bool true pour Enabled et EnabledLocked.

PluginSettingType (enum backed string)

Kirexo\Plugin\Contracts\PluginSettingType — src/Plugin/Contracts/PluginSettingType.php. Type d'un réglage déclaré par un plugin, pour le rendu de formulaire et le panneau des capacités.

Case Valeur
Text 'text'
Textarea 'textarea'
Boolean 'boolean'
Choice 'choice'

PluginSettingDescriptor (final readonly)

Kirexo\Plugin\Contracts\PluginSettingDescriptor — src/Plugin/Contracts/PluginSettingDescriptor.php. Descripteur immuable d'un réglage, retourné dans les list<> de globalSettings() / userSettings().

Propriété Type Défaut Rôle
key string — Clé technique du réglage.
label string — Libellé d'affichage.
type PluginSettingType — Type de champ.
required bool false Réglage obligatoire ?
help ?string null Texte d'aide facultatif.

Signature du constructeur :

public function __construct(
    public string $key,
    public string $label,
    public PluginSettingType $type,
    public bool $required = false,
    public ?string $help = null,
) {
}

PluginRegistryInterface

App\Plugin\PluginRegistryInterface — src/Plugin/PluginRegistryInterface.php. Contrat du registre côté cœur. C'est cette interface que les handlers, controllers et services d'activation injectent — jamais l'implémentation final App\Plugin\PluginRegistry, non mockable. L'interface étend \IteratorAggregate pour le foreach ergonomique.

Méthode Signature Retour Rôle
getIterator getIterator(): \Traversable \Traversable<string, DiffusionPluginInterface> Itère les plugins indexés par clé.
has has(string $key): bool bool Un plugin existe-t-il pour cette clé ?
get get(string $key): DiffusionPluginInterface DiffusionPluginInterface Plugin par clé. @throws UnknownPluginException si la clé est inconnue.
all all(): array array<string, DiffusionPluginInterface> Tous les plugins, indexés par clé.
keys keys(): array list<string> Clés connues, dans l'ordre d'enregistrement.

La clé d'indexation provient de DiffusionPluginInterface::key(). Deux plugins déclarant la même clé provoquent une \LogicException au boot du conteneur (collision détectée à la construction du registre). Une clé inconnue passée à get() lève App\Plugin\Exception\UnknownPluginException (src/Plugin/Exception/UnknownPluginException.php, extends \OutOfBoundsException).

Convention de nommage

Pour éviter les collisions entre plugins, tout ce qu'un plugin expose est préfixé par sa clé :

Élément Convention Exemple (plugin web)
Clé du plugin key() web
Transport Messenger plugin_<clé> plugin_web
Tables Doctrine <clé>_plugin_* web_plugin_site, web_plugin_domain
Routes / noms de route <clé>_plugin_* web_plugin_*

Voir aussi