Aller au contenu

Référence : configuration du plugin web

Cette page décrit la surface de configuration du bundle KirexoPluginWebBundle (src/Plugin/Web/src/KirexoPluginWebBundle.php) :

  • Section A — les variables d'environnement que le plugin déclare ;
  • Section B — ce que le bundle auto-configure de lui-même (donc ce que l'opérateur n'a pas à câbler).

Pour la marche à suivre pas à pas, voir le guide Installer le plugin web sur une instance. Pour le pourquoi de cette répartition, voir Pourquoi la configuration du plugin est portée par le bundle.

Section A — Variables d'environnement du plugin web

Le bundle déclare ses variables dans la constante KirexoPluginWebBundle::ENV_VARS. La classe Kirexo\Plugin\Web\DependencyInjection\EnvVarManifest (src/Plugin/Web/src/DependencyInjection/EnvVarManifest.php) lit cette constante pour poser les défauts au prependExtension et valider les variables requises au boot.

Source de vérité

Le tableau ci-dessous est la transcription du manifeste KirexoPluginWebBundle::ENV_VARS. Toute évolution du manifeste doit être répercutée ici ; en cas de doute, le manifeste fait foi.

Nom Rôle Défaut Requis
MESSENGER_TRANSPORT_PLUGIN_WEB_DSN DSN du transport Messenger dédié à la diffusion web (isolation d'échec par plugin). amqp://guest:guest@rabbitmq:5672/%2f/plugin_web Oui

Une variable requise mais toujours défaultée

MESSENGER_TRANSPORT_PLUGIN_WEB_DSN est marquée required, mais elle porte un défaut (le DSN AMQP ci-dessus). Le prependExtension pose ce défaut comme paramètre env(MESSENGER_TRANSPORT_PLUGIN_WEB_DSN) : la variable ne peut donc jamais être « absente » à l'exécution, même si vous ne la déclarez pas dans votre environnement. En dev, elle fonctionne telle quelle. À surcharger en production avec les credentials RabbitMQ réels — voir l'angle exploitation dans Variables d'environnement — Messenger / RabbitMQ.

Validation au boot : filet pour les variables requises sans défaut

Au boot, le bundle appelle EnvVarManifest::assertRequiredPresent() : il lève une \RuntimeException claire (nom de la variable + son rôle) si une variable requise et sans défaut est absente de l'environnement. Ce filet ne se déclenche donc pas pour MESSENGER_TRANSPORT_PLUGIN_WEB_DSN (qui a un défaut) ; il protège d'éventuelles variables requises sans défaut qu'un futur plugin déclarerait dans son propre manifeste.

Voir aussi — variables d'infrastructure consommées par le bundle

Ces variables ne figurent pas dans ENV_VARS (ce ne sont pas des variables que le plugin doit défaulter), mais le bundle les consomme réellement. Elles sont décrites, sous l'angle exploitation / déploiement, dans Variables d'environnement — ne pas les redéfinir ici :

  • KIREXO_ONDEMAND_TLS_ENABLED — lue côté Symfony par WebPluginTlsAskController (src/Plugin/Web/src/Controller/WebPluginTlsAskController.php), injectée via %env(bool:KIREXO_ONDEMAND_TLS_ENABLED)% (cf. src/Plugin/Web/config/services.yaml). L'endpoint ask reste inerte (403) tant que le flag vaut 0.
  • KIREXO_RESERVED_DOMAINS — injectée dans le résolveur Host → Site via le paramètre %kirexo.reserved_domains% (défini dans config/packages/kirexo.yaml à partir de %env(csv:KIREXO_RESERVED_DOMAINS)%, consommé dans src/Plugin/Web/config/services.yaml).

Section B — Ce que le bundle auto-configure (prependExtension)

La méthode prependExtension() de KirexoPluginWebBundle porte toute la configuration de conteneur du plugin, avant le chargement des extensions. Le cœur n'a donc rien à déclarer pour les points suivants — l'opérateur n'a pas à les câbler à la main :

Ce que le bundle auto-configure Détail
Défauts d'environnement Pose un paramètre env(<NOM>) = valeur par défaut pour chaque variable défaultée de ENV_VARS (mécanisme officiel Symfony ; ne touche pas au .env de l'app). Aujourd'hui : MESSENGER_TRANSPORT_PLUGIN_WEB_DSN.
Mapping Doctrine Enregistre le mapping KirexoPluginWeb (type: attribute, préfixe Kirexo\Plugin\Web\Entity) sur le dossier src/Plugin/Web/src/Entity/ — entités Site, SiteDomain, SpecialPage, Theme. Le dossier est calculé depuis le bundle (survit à un futur déplacement sous vendor/), jamais via %kernel.project_dir%.
Namespace TwigComponent Mappe le namespace Kirexo\Plugin\Web\Twig\Component\ vers les templates @KirexoPluginWeb/components/.
Pool de cache dédié Déclare le pool web.public_site.cache (adapter cache.adapter.redis_tag_aware), utilisé par le rendu du site public.
Transport Messenger Déclare le transport plugin_web sur %env(MESSENGER_TRANSPORT_PLUGIN_WEB_DSN)% (exchange fanout plugin_web, retry_strategy 3 essais). En environnement test, le transport est routé sur sync:// (décidé depuis kernel.environment).

Conséquence : rien à répéter côté cœur

Parce que ces cinq points sont portés par le bundle, brancher le plugin ne demande aucune configuration Doctrine, Messenger ou cache dans config/ côté application. Les seuls points de câblage restant au niveau app sont l'enregistrement du bundle (config/bundles.php), l'import des routes et la vérification de l'entrée importmap — tous décrits dans le guide Installer le plugin web sur une instance, et justifiés dans Pourquoi la configuration du plugin est portée par le bundle.

Voir aussi