Aller au contenu

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 php via Castor.

Étape 1 — Enregistrer le bundle (une ligne)

Ajoutez le bundle à config/bundles.php :

Kirexo\Plugin\Web\KirexoPluginWebBundle::class => ['all' => true],

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 :

_kirexo_plugin_web:
    resource: '@KirexoPluginWebBundle/config/routes.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 :

'site' => ['path' => './assets/site.js', 'entrypoint' => true],

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) :

castor doctrine:migrate

La cible applique les migrations en attente en mode --all-or-nothing (cf. castor doctrine:migrate).

Étape 5 — Vérifier

  1. Mappez un domaine à un Site (procédure et règles d'unicité : Référence : domaines de site).
  2. 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 :

grep -R "KirexoPluginWeb" config/

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 ?