Installer le plugin web sur une instance¶
Vous êtes développeur·se / opérateur·rice et vous voulez brancher le plugin web sur une instance Kirexo. À la fin de cette recette, le plugin web est actif, la résolution multi-tenant est en place et un site public répond sur un domaine mappé — sans avoir eu à lire le code source du bundle.
Cette recette suppose un plugin déjà écrit (ici le plugin web fourni). Pour écrire un plugin de zéro, voir le tutoriel Écrire un plugin de diffusion.
Ce que vous allez obtenir¶
- le plugin web enregistré et démarré ;
- les tables
web_plugin_*créées en base ; - un site public qui répond sur un domaine mappé à un
Site.
Comptez une dizaine de minutes. Le point clé : le seul point d'entrée obligatoire côté cœur est config/bundles.php. Tout le reste (Doctrine, cache, Messenger, TwigComponent) est auto-configuré par le bundle — vous n'avez pas à le recopier. Voir Référence : configuration du plugin web — Section B.
Prérequis¶
- La stack Kirexo démarrée en local (
castor docker:up). Si ce n'est pas le cas, suivez d'abord Premier démarrage pour développer. - Les commandes ci-dessous s'exécutent dans le conteneur
phpvia Castor.
Étape 1 — Enregistrer le bundle (une ligne)¶
Ajoutez le bundle à config/bundles.php :
C'est le seul point d'entrée obligatoire côté cœur. L'autoload PSR-4 Kirexo\Plugin\Web\ est déjà déclaré dans le composer.json racine (plugin de monorepo) — rien à faire côté autoload pour le plugin web fourni.
À l'enregistrement du bundle, sa méthode prependExtension câble automatiquement le mapping Doctrine, le namespace TwigComponent, le pool de cache et le transport Messenger plugin_web. Vous n'avez aucune de ces configurations à écrire côté application (détail : Section B de la référence).
Étape 2 — Câbler les routes et vérifier l'importmap¶
Deux choses ne sont pas portables par prependExtension (le routing et l'importmap ne sont pas des extensions de conteneur). Il n'y a pas de recipe Symfony Flex : ce sont deux manipulations manuelles, à reproduire telles quelles.
Import des routes (une ligne)¶
Le bundle possède sa propre ressource de routing src/Plugin/Web/config/routes.yaml : c'est elle qui scanne les controllers du bundle (type: attribute). Côté application, il suffit d'importer cette ressource depuis config/routes/kirexo_plugin_web.yaml :
L'application n'a jamais à scanner le dossier Controller/ du bundle : le scan est encapsulé dans la ressource du bundle. Le fichier côté app se borne à l'importer.
Entrée importmap¶
Vérifiez la présence de l'entrée site dans l'importmap.php racine :
C'est l'entrypoint du plugin web, chargé par importmap(['app', 'site']) dans le layout du site public. (CodeMirror n'est pas cette entrée : c'est une dépendance vendor tirée transitivement, pas l'entrypoint applicatif du plugin.)
Étape 3 — Renseigner les variables d'environnement¶
Le plugin déclare une variable d'environnement propre : MESSENGER_TRANSPORT_PLUGIN_WEB_DSN (le DSN de son transport Messenger). Elle porte un défaut AMQP qui fonctionne en dev tel quel — à surcharger en production avec vos credentials RabbitMQ réels.
La liste exhaustive (rôle, défaut, caractère requis) et les variables d'infrastructure consommées par le bundle sont dans Référence : configuration du plugin web — Section A. Ne les recopiez pas ici.
Filet : validation au boot
Si un plugin déclare une variable requise et sans défaut et que vous l'oubliez, le bundle échoue au démarrage avec un message clair nommant la variable manquante et son rôle. Le plugin web n'est pas dans ce cas — son unique variable a un défaut —, mais c'est le comportement à connaître pour les plugins qui exigent une valeur.
Étape 4 — Exécuter la migration¶
Les migrations sont fournies avec le plugin : vous n'écrivez rien. Créez les tables web_plugin_* (web_plugin_site, web_plugin_domain, web_plugin_special_page, web_plugin_theme) :
La cible applique les migrations en attente en mode --all-or-nothing (cf. castor doctrine:migrate).
Étape 5 — Vérifier¶
- Mappez un domaine à un
Site(procédure et règles d'unicité : Référence : domaines de site). - Ouvrez ce domaine dans un navigateur : le site public doit répondre.
Checklist « install simple »¶
Vérifiez que le seul câblage du plugin côté cœur tient à l'enregistrement du bundle et à l'import de routes — aucune configuration Doctrine / Messenger / cache manuelle :
Cette commande ne doit ressortir que :
- la ligne d'enregistrement dans
config/bundles.php; - l'import de routes dans
config/routes/kirexo_plugin_web.yaml(resource: '@KirexoPluginWebBundle/config/routes.yaml', plus son commentaire).
Aucune autre entrée : toute la config Doctrine / Messenger / cache est portée par le bundle (prependExtension), pas par le cœur.
Et ensuite ?¶
- Écrire un plugin de diffusion — l'autre bout de l'arc : écrire un plugin de zéro.
- Référence : configuration du plugin web — variables d'environnement et auto-configuration.
- Servir les domaines de site en HTTPS — servir les sites publics en HTTPS sur des domaines arbitraires.
- Pourquoi la configuration du plugin est portée par le bundle — la frontière entre
prependExtensionet le câblage app-level.