Aller au contenu

Écrire un plugin de diffusion

Vous êtes développeur·se backend et vous voulez ajouter une nouvelle destination de diffusion à Kirexo — un canal vers lequel les articles publiés seront poussés. À la fin de ce tutoriel, vous aurez écrit, de zéro, un plugin demo minimal mais fonctionnel : un bundle isolé, enregistré automatiquement dans le registre des plugins, qui réagit à la publication d'un article via son propre transport Messenger.

Nous calquons pas à pas la structure du plugin web, le plugin de référence livré avec Kirexo. Comptez une trentaine de minutes. Le chemin est linéaire : suivez-le dans l'ordre.

Ce tutoriel montre un chemin qui marche. Pour l'inventaire complet des signatures, consultez au fil de l'eau la référence du contrat et la référence du bus ; pour comprendre pourquoi l'architecture est ainsi, voir Architecture des plugins de diffusion.

Ce que vous allez construire

Un plugin de diffusion demo (clé fictive), composé de :

  • un bundle Symfony isolé sous src/Plugin/Demo/, autonome et sans dépendance au cœur ;
  • une classe qui implémente le contrat DiffusionPluginInterface et s'enregistre toute seule dans le registre ;
  • un transport Messenger dédié plugin_demo et un handler qui réagit à la publication d'un article.

La règle d'or, valable pour tous les plugins : on doit pouvoir supprimer le plugin sans rien casser d'autre. Le seul pont entre votre plugin et le cœur est le contrat Kirexo\Plugin\Contracts\ et les événements — jamais un use App\.

Prérequis

  • La stack Kirexo démarrée en local. Si ce n'est pas le cas, suivez d'abord Premier démarrage pour développer, puis revenez ici.
  • Les commandes ci-dessous s'exécutent dans le conteneur php via Castor (castor composer …) ou directement bin/console … depuis le conteneur.

Étape 1 — Créer le bundle isolé

Un plugin est un Symfony Bundle moderne. Créez l'arborescence suivante :

src/Plugin/Demo/
├── composer.json
├── config/
│   └── services.yaml
├── src/
│   └── KirexoPluginDemoBundle.php
└── templates/         # facultatif, si votre plugin rend du HTML

La classe du bundle étend AbstractBundle (jamais l'ancienne base Bundle) et vit dans src/Plugin/Demo/src/. Gabarit : src/Plugin/Web/src/KirexoPluginWebBundle.php.

<?php

declare(strict_types=1);

namespace Kirexo\Plugin\Demo;

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symfony\Component\HttpKernel\Bundle\AbstractBundle;

/**
 * Bundle du plugin de diffusion « demo ». Isolé du cœur : aucune classe du
 * bundle n'importe App\ ; le couplage passe par le contrat
 * Kirexo\Plugin\Contracts\ et par les événements.
 */
final class KirexoPluginDemoBundle extends AbstractBundle
{
    public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void
    {
        // Chemin relatif au fichier (src/Plugin/Demo/src/) →
        // ../config/services.yaml = src/Plugin/Demo/config/services.yaml.
        $container->import('../config/services.yaml');
    }
}

Structure moderne obligatoire

La classe du bundle réside dans src/Plugin/Demo/src/. AbstractBundle::getPath() détecte le suffixe /src et retourne le dossier parent (src/Plugin/Demo) comme racine du bundle. C'est ce qui permet à config/ et templates/ d'être des frères de src/, sans avoir à surcharger getPath(). Ne remettez pas la classe bundle à la racine du dossier.

Le services.yaml du bundle enregistre vos services (chemins relatifs au fichier, donc ../src/) :

# src/Plugin/Demo/config/services.yaml
services:
    _defaults:
        autowire: true
        autoconfigure: true

    Kirexo\Plugin\Demo\:
        resource: '../src/'
        exclude:
            - '../src/KirexoPluginDemoBundle.php'

Le composer.json interne documente le package (préparation d'un futur composer require) ; il ne dépend jamais du cœur :

{
    "name": "kirexo/plugin-demo",
    "description": "Plugin de diffusion « demo » de Kirexo.",
    "type": "symfony-bundle",
    "license": "AGPL-3.0-or-later",
    "autoload": {
        "psr-4": {
            "Kirexo\\Plugin\\Demo\\": "src/"
        }
    },
    "extra": {
        "kirexo": {
            "plugin-key": "demo"
        }
    }
}

Kirexo est distribué sous AGPL-3.0-or-later. Un plugin est chargé dans le même processus que le cœur et s'appuie sur ses contrats : distribuez-le sous une licence compatible avec l'AGPL v3. Le plus simple est de reprendre AGPL-3.0-or-later, comme dans l'exemple. Le champ license attend un identifiant SPDX.

Étape 2 — Déclarer l'autoload et enregistrer le bundle

Tant que le plugin vit dans le monorepo, l'autoload effectif passe par le composer.json racine. Ajoutez-y le préfixe PSR-4 du plugin, à côté de ceux déjà présents :

"autoload": {
    "psr-4": {
        "App\\": "src/",
        "Kirexo\\Plugin\\Contracts\\": "src/Plugin/Contracts/",
        "Kirexo\\Plugin\\Web\\": "src/Plugin/Web/src/",
        "Kirexo\\Plugin\\Demo\\": "src/Plugin/Demo/src/"
    }
}

Régénérez l'autoloader :

castor composer dump-autoload

Puis enregistrez le bundle dans config/bundles.php :

Kirexo\Plugin\Demo\KirexoPluginDemoBundle::class => ['all' => true],

Étape 3 — Implémenter le contrat

Créez la classe du plugin — c'est elle qui implémente DiffusionPluginInterface. Toutes ses méthodes sont détaillées dans la référence du contrat ; on donne ici une implémentation minimale.

<?php

declare(strict_types=1);

namespace Kirexo\Plugin\Demo;

use Kirexo\Plugin\Contracts\DiffusionPluginInterface;
use Kirexo\Plugin\Contracts\PluginSettingDescriptor;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Uid\Uuid;

final class DemoDiffusionPlugin implements DiffusionPluginInterface
{
    public function key(): string
    {
        return 'demo';
    }

    public function label(): string
    {
        return 'Demo';
    }

    public function colorKey(): string
    {
        return 'demo';
    }

    public function publish(Uuid $articleId): void
    {
        // Diffusion réelle vers votre destination. Rechargez l'article
        // dont vous avez besoin via votre propre read-side, à partir de l'id.
    }

    /** @return list<PluginSettingDescriptor> */
    public function globalSettings(): array
    {
        return [];
    }

    /** @return list<PluginSettingDescriptor> */
    public function userSettings(): array
    {
        return [];
    }

    public function isEnabledFor(UserInterface $user): bool
    {
        return true;
    }
}

Le plugin ne connaît jamais App\

Le namespace du plugin n'importe jamais App\. Les seuls types partagés avec le cœur viennent de Kirexo\Plugin\Contracts\ (le contrat, PluginSettingDescriptor, …) et de composants Symfony neutres (UserInterface, Uuid). C'est ce découplage qui garantit qu'un plugin est amovible et, à terme, extractible en composer require. publish() reçoit un Uuid, pas l'entité Article : voir le pourquoi.

Étape 4 — S'auto-enregistrer par tag

Il n'y a rien à configurer, ni côté cœur, ni dans le services.yaml de votre bundle. Le kernel du cœur déclare un point d'autoconfiguration central (registerForAutoconfiguration(DiffusionPluginInterface::class)->addTag('kirexo.plugin'), dans App\Kernel::build()) : dès que votre classe implémente l'interface et est autoconfigurée — c'est le cas grâce au _defaults: autoconfigure: true de l'étape 1 —, elle est taguée kirexo.plugin et agrégée par le registre.

N'essayez pas de poser le tag depuis votre bundle

Un #[AutoconfigureTag('kirexo.plugin')] sur l'interface ne se propage pas aux implémenteurs qui vivent dans un bundle : le registre resterait vide, sans le moindre message. C'est la raison d'être du point d'autoconfiguration central — il évite aussi de recopier un _instanceof dans le services.yaml de chaque plugin.

Vérifiez que votre plugin est bien vu :

bin/console debug:container --tag=kirexo.plugin

Kirexo\Plugin\Demo\DemoDiffusionPlugin doit apparaître dans la liste.

Étape 5 — Réagir à la publication (transport dédié)

Quand un article est publié vers votre destination, le cœur dispatche le message ArticlePublished sur le transport plugin_demo. La mécanique complète (ciblage, fromTransport) est dans la référence du bus ; voici le câblage minimal.

Le transport se déclare depuis votre bundle, jamais dans config/packages/messenger.yaml. Le point d'accroche est prependExtension(), qui s'exécute avant le chargement des extensions et peut donc écrire dans la configuration de framework. Gabarit : src/Plugin/Web/src/KirexoPluginWebBundle.php.

C'est ce qui rend le plugin réellement amovible : retirer sa ligne de config/bundles.php retire aussi son transport, sans laisser derrière lui une entrée orpheline dans la configuration du cœur qui ferait échouer le boot.

Ajoutez donc cette méthode à KirexoPluginDemoBundle, en suivant la convention plugin_<clé> (exchange et queue dédiés) :

public function prependExtension(ContainerConfigurator $container, ContainerBuilder $builder): void
{
    // Défaut d'env : un paramètre `env(NOM)` sert de repli quand la variable
    // réelle est absente. Ne touche pas au .env de l'application.
    $builder->setParameter(
        'env(MESSENGER_TRANSPORT_PLUGIN_DEMO_DSN)',
        'amqp://guest:guest@rabbitmq:5672/%2f/plugin_demo',
    );

    // La variation `test` est décidée ici : kernel.environment est lisible à ce stade.
    $isTest = 'test' === $builder->getParameter('kernel.environment');

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

En test, le transport garde son nom

En environnement de test, plugin_demo vaut sync:// — mais il s'appelle toujours plugin_demo. C'est ce qui permet à votre handler fromTransport: 'plugin_demo' de se déclencher sans RabbitMQ. Le renommer en sync le rendrait muet en test, sans erreur.

Écrivez le handler, annoté avec votre transport. Le plugin web place le sien sous MessageHandler/ (src/Plugin/Web/src/MessageHandler/WebArticlePublishedHandler.php) :

<?php

declare(strict_types=1);

namespace Kirexo\Plugin\Demo\MessageHandler;

use App\Message\ArticlePublished;
use Kirexo\Plugin\Demo\DemoDiffusionPlugin;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler(fromTransport: 'plugin_demo')]
final readonly class DemoArticlePublishedHandler
{
    public function __construct(
        private DemoDiffusionPlugin $plugin,
    ) {
    }

    public function __invoke(ArticlePublished $message): void
    {
        // Ne se déclenche QUE pour les messages reçus du transport plugin_demo.
        $this->plugin->publish($message->articleId);
    }
}

Publiez un article en ciblant la destination demo : votre handler est appelé.

Étape 6 — Déclarer des réglages

Un plugin peut exposer des réglages, rendus en formulaire et listés dans le panneau des capacités. Retournez des PluginSettingDescriptor depuis globalSettings() (portée administrateur) et userSettings() (par utilisateur). Chaque descripteur porte une clé, un label et un type (PluginSettingType) — voir la référence du contrat.

use Kirexo\Plugin\Contracts\PluginSettingDescriptor;
use Kirexo\Plugin\Contracts\PluginSettingType;

/** @return list<PluginSettingDescriptor> */
public function userSettings(): array
{
    return [
        new PluginSettingDescriptor(
            key: 'webhook_url',
            label: 'URL du webhook',
            type: PluginSettingType::Text,
            required: true,
            help: 'Adresse appelée à chaque publication.',
        ),
    ];
}

Vérifier votre plugin

Passez cette checklist depuis le conteneur php :

# Le plugin est-il tagué et vu par le registre ?
bin/console debug:container --tag=kirexo.plugin

# Le handler est-il bien lié au transport plugin_demo ?
# (la sortie mentionne le transport de réception à côté du handler)
bin/console debug:messenger

Puis publiez un article de test ciblant demo et vérifiez que le handler s'exécute.

Supprimer le plugin ne doit rien casser

Retirez la ligne de config/bundles.php et le préfixe PSR-4 du composer.json racine, régénérez l'autoload : la plateforme doit rebooter sans erreur, comme si le plugin n'avait jamais existé. Si ce n'est pas le cas, c'est qu'une dépendance au cœur a fuité quelque part — corrigez-la.

Et ensuite ?