Modèle de thème et catalogue fourni¶
Cette page explique pourquoi l'apparence d'un site du plugin web est devenue un thème que l'on choisit, plutôt que des zones de HTML et une feuille de style attachées au site ; pourquoi les trois thèmes livrés vivent en fichiers versionnés plutôt qu'en base ; et pourquoi un site dont le thème est introuvable retombe silencieusement sur « Par défaut ».
Elle s'adresse aux personnes qui font évoluer Kirexo. Pour le contrat précis d'un thème (variables, classes CSS, limites), voir Référence — Thèmes de site ; pour les barrières de sécurité que traversent ses sources, voir Sécurité du rendu personnalisé des sites ; pour la version destinée aux auteur·ices, voir Ce que vous pouvez personnaliser sur votre site.
Le problème : une apparence éparpillée entre le site et le layout¶
Le modèle précédent attachait l'apparence au site : trois zones de HTML libre (en-tête, corps, pied de page) et une feuille de style, plus une « clé de thème » qui ne faisait que poser une classe sur le <body>. Deux défauts, tous deux visibles à l'usage, ont conduit à l'abandonner.
L'en-tête personnalisé faisait disparaître le menu par omission. Le layout traitait la zone d'en-tête comme un remplacement : tant qu'elle était vide, il affichait la marque du site et la navigation des pages spéciales ; dès qu'un fragment y était déposé, les deux disparaissaient. Un auteur qui voulait simplement ajouter un logo perdait, sans le vouloir, tout son menu — et donc tout le travail d'ordonnancement des pages. Le remplacement était un choix défendable (éviter une double marque et un double landmark de navigation), mais son effet de bord était invisible depuis l'écran d'édition.
Changer de thème ne changeait rien. La « clé de thème » ne pilotait que quelques règles CSS qui, pour l'essentiel, redéclaraient des valeurs déjà posées par les styles de base. L'utilisateur enregistrait, ne voyait aucune différence, et n'avait aucun moyen de savoir si le problème venait de son choix, du cache ou d'un bug.
Ces deux symptômes ont la même racine : l'apparence n'était le sujet d'aucun objet. Elle était répartie entre quatre colonnes du site, une feuille de style globale et des {% if %} du layout. Personne ne pouvait répondre à la question « à quoi ressemble ce site ? » en regardant une seule chose.
La bascule : l'apparence est un objet, et on la choisit¶
Un thème est un objet à part entière, fait de quatre sources : un en-tête, un corps, un pied de page et une feuille de style. C'est la totalité de l'habillage — le layout ne rend plus aucun chrome par lui-même.
Le premier bénéfice est direct : la navigation des pages spéciales n'est plus un {% else %} du layout, c'est une boucle écrite dans l'en-tête du thème, sur la variable pages. On ne peut donc plus faire disparaître le menu par omission : il est là parce que le thème l'écrit, et il ne part que si on retire explicitement la boucle. Ce qui était un piège devient une décision.
Le second bénéfice est de rendre le choix signifiant : deux thèmes différents ne sont plus deux jeux de surcharges sur un même socle, ce sont deux habillages complets et indépendants. Le socle résiduel (assets/styles/pages/site.css) ne porte plus aucun style éditorial — seulement les garde-fous que le layout doit tenir quel que soit le thème.
Le prix à payer est assumé : écrire un thème demande d'écrire tout l'habillage, il n'y a plus de « valeur par défaut » sur laquelle se reposer partiellement. C'est acceptable parce que les thèmes fournis servent de point de départ — dupliquer plutôt que partir de rien est le geste courant, et c'est aussi pourquoi créer un thème produit une copie de « Par défaut » plutôt qu'un objet vide. Voir Écrire ses propres thèmes : les arbitrages.
Ce que le layout garde pour lui¶
Un thème décide de ce qu'il met dans chaque zone, jamais de la structure de la page. Le layout (src/Plugin/Web/templates/site/layout.html.twig) conserve trois responsabilités, précisément parce qu'un thème mal écrit ne doit pouvoir en compromettre aucune :
- La structure sémantique et l'accessibilité — les landmarks
<header>/<main id="main">/<footer>et le lien d'évitement vers le contenu sont posés par le layout. Un thème ne peut ni les supprimer ni les imbriquer de travers. - Le référencement —
title, meta description, canonique, Open Graph et indicesrel=prev/nextsont calculés côté serveur et posés dans le<head>, hors de portée du thème. - La pagination du flux — ses liens visibles sont rendus dans le contenu, pas dans le pied de page. Un thème qui n'écrirait rien dans son pied ne peut donc pas priver le site de sa navigation entre pages.
C'est la même logique que pour la sécurité : on ne demande pas au thème d'être bien écrit, on organise le rendu pour qu'un thème mal écrit dégrade l'esthétique sans casser la page.
Pourquoi les thèmes fournis vivent en fichiers versionnés¶
Les trois thèmes livrés (default, classic, minimal) ne sont pas des lignes insérées en base au déploiement avec un drapeau builtin : ce sont des répertoires du dépôt, sous src/Plugin/Web/themes/, lus par BuiltinThemeCatalog (src/Plugin/Web/src/Theme/BuiltinThemeCatalog.php).
L'alternative — seeder la base puis protéger les lignes par un drapeau — aurait paru plus simple, puisqu'un seul chemin de lecture aurait suffi. Elle a été écartée pour trois raisons.
- L'immuabilité devient structurelle, pas conditionnelle. « Ce thème n'est pas modifiable » n'est plus un
ifque l'on peut oublier dans un futur contrôleur d'édition : il n'existe aucun code qui écrive dansthemes/. La garantie ne repose pas sur la vigilance, elle repose sur l'absence de chemin. - Le style passe en revue de code. Un thème fourni est du CSS et du Twig relus, versionnés, diffables. Une régression visuelle apparaît dans une merge request, pas dans une base de production.
- Faire évoluer un thème fourni ne demande aucune migration. Corriger un espacement de « Classique », c'est éditer un fichier. Avec un seed, il aurait fallu écrire une migration de données par retouche, et arbitrer le sort des instances où la ligne aurait été modifiée à la main.
Le compromis est réel : le catalogue fourni n'est pas extensible à chaud, et un administrateur ne peut pas ajouter un quatrième thème « maison » sans passer par le dépôt. C'est cohérent avec le rôle de ces trois thèmes — des points de départ maintenus par le projet, pas un espace de personnalisation.
En développement, un thème fourni est lu une seule fois par worker
BuiltinThemeCatalog met le catalogue en cache d'instance : les fichiers sont lus au premier accès, puis relus depuis la mémoire. En worker mode FrankenPHP, le processus survit aux requêtes — modifier un theme.css ou un header.html.twig d'un thème fourni n'a donc aucun effet visible tant que le worker n'a pas redémarré. Relancez-le avec castor supervisor:frankenphp-restart depuis le conteneur (voir Référence — Commandes Castor). Ce cache est sans risque de fuite entre tenants : les sources sont des fichiers identiques pour tout le monde.
Deux origines, un seul type : ThemeSource¶
Un thème fourni vient du disque, un thème personnel vient de la base. Si cette différence remontait jusqu'au rendu, chaque consommateur devrait la connaître : le renderer, le contrôleur de feuille de style, le sélecteur de l'onglet Apparence — trois endroits où un if finirait par diverger.
Elle est donc aplatie au plus tôt dans un DTO immuable unique, ThemeSource (src/Plugin/Web/src/Theme/ThemeSource.php), qui porte les quatre sources, la clé, le nom et un unique drapeau builtin. Ce drapeau ne sert qu'à deux décisions, toutes deux explicites : afficher le badge « Fourni », et décider si le CSS doit repasser par le filtre. Partout ailleurs, l'origine est indiscernable — et c'est le but.
Une seule colonne, pas de clé étrangère¶
Site::themeKey porte soit une clé courte (default), soit l'identifiant d'un thème personnel. Une seule colonne, aucune contrainte d'intégrité vers une table de thèmes.
Ce n'est pas de la paresse de schéma. Une clé étrangère aurait forcé à représenter les thèmes fournis en base pour qu'ils soient référençables — c'est-à-dire à renoncer aux fichiers versionnés et à tous leurs bénéfices. Elle aurait aussi imposé un ON DELETE à choisir : supprimer le thème d'un utilisateur aurait soit cassé ses sites, soit demandé une mise à jour en cascade.
Le prix de ce choix est l'absence d'intégrité référentielle : rien n'empêche themeKey de désigner un thème qui n'existe plus. C'est précisément ce que la règle de repli rend inoffensif.
Pourquoi un repli silencieux plutôt qu'une erreur¶
ThemeResolver (src/Plugin/Web/src/Theme/ThemeResolver.php) ne renvoie jamais rien : clé inconnue, thème supprimé, valeur illisible, ou thème appartenant à un autre compte — dans tous les cas, c'est « Par défaut » qui est rendu.
Le raisonnement est celui du contrat de non-échec. Le rendu public est anonyme et sans recours : un visiteur qui tombe sur une page blanche n'a aucun moyen de comprendre ni de signaler quoi que ce soit, et l'auteur ne l'apprendra que par hasard. Faire tomber un site entier parce qu'une chaîne de 36 caractères ne désigne plus rien serait un très mauvais échange. Un habillage inattendu se voit et se corrige ; une page blanche se subit.
Le cas « thème d'un autre compte » mérite d'être isolé : ce n'est pas un repli de robustesse mais une règle d'autorisation. themeKey est une donnée soumise par formulaire ; coller l'identifiant du thème d'autrui suffirait à faire rendre son travail sur son propre site. La vérification d'appartenance est donc faite au même endroit pour la lecture (resolve()) et pour l'écriture (isApplicable()), afin que les deux ne puissent pas diverger — et le contrôleur refuse la clé dès l'écriture plutôt que de stocker une valeur qui serait de toute façon ignorée à l'affichage.
Même logique un cran plus loin, au rendu : si les gabarits d'un thème personnel sont refusés par la sandbox, on retombe sur « Par défaut » en entier, pas zone par zone. Mélanger l'en-tête d'un thème et le pied d'un autre produirait une page incohérente, plus déroutante encore que le repli complet.
Reproductibilité : les thèmes fournis doivent être exprimables par un utilisateur¶
Le CSS d'un thème fourni est servi tel quel, sans passer par le filtre : c'est du code relu, pas une saisie. Le CSS d'un thème personnel, lui, est filtré à chaque service.
Ces deux régimes créent un risque : que les thèmes fournis utilisent un langage plus riche que celui offert aux utilisateurs. « Dupliquer Classique » donnerait alors un thème visuellement différent de l'original — un comportement incompréhensible, et une promesse trahie.
L'invariant tenu est donc : aucune déclaration des trois thèmes fournis n'est retirée par le filtre. Il est vérifié par les tests, et c'est lui qui a motivé l'élargissement de la liste des propriétés autorisées aux propriétés de mise en page (flex, grille, bordures directionnelles, propriétés logiques…) — aucune n'ouvre de surface d'exécution ou de recouvrement.
Le test porte sur l'absence de déclaration retirée, pas sur l'égalité des chaînes : le filtre supprime les commentaires et normalise l'espacement, sa sortie diffère donc légitimement de son entrée. C'est la conservation du sens qui prouve la reproductibilité, pas l'identité du texte.
Pas de @media : une contrainte de conception, pas un défaut¶
Le filtre CSS retire toutes les règles @, y compris @media. Un thème doit donc être responsive sans point de rupture : clamp() pour les tailles, max-width pour les colonnes, flex-wrap pour les barres de navigation, minmax() pour les grilles.
C'est une limite du filtre — une allowlist plate de déclarations, qui ne sait pas raisonner sur des blocs imbriqués — mais elle est conservée sciemment plutôt que contournée. Autoriser @media demanderait d'analyser et de valider les préludes de règles @, donc d'élargir la surface d'analyse du filtre là où elle reste trivialement vérifiable. En regard, le CSS moderne rend la plupart des mises en page fluides accessibles sans media query, ce que les trois thèmes fournis démontrent.
La contrainte est donc à lire comme une contrainte de style, du même ordre que « pas de ressource externe » : elle borne le vocabulaire pour garder le filtre simple, et un filtre simple est un filtre qu'on peut relire.
L'injection du contenu¶
Le corps d'un thème ne contient pas la page : il contient un emplacement ({{ content }}) que le rendu remplace par la page demandée, après assainissement du gabarit. Le contenu du site n'est donc jamais repassé au sanitizer, et la sandbox ne peut ni l'inspecter ni le manipuler.
Le mécanisme exact — pourquoi une sentinelle plutôt qu'un bloc Twig, pourquoi elle est imprévisible à chaque rendu, et pourquoi un corps sans emplacement concatène le contenu au lieu de le perdre — est détaillé dans Sécurité du rendu personnalisé des sites.
Voir aussi¶
- Écrire ses propres thèmes : les arbitrages — la suite de cette page : portée compte, deux régimes de persistance, « rien n'est refusé », suppression non bloquante.
- Référence — Thèmes de site — le contrat exact : variables, classes CSS, limites du filtre, règles de résolution.
- Sécurité du rendu personnalisé des sites — les quatre barrières traversées par les sources d'un thème.
- Ce que vous pouvez personnaliser sur votre site — la même bascule, racontée pour les auteur·ices.
- Rendu public d'un site (plugin web) — les trois surfaces publiques, le SEO et l'invalidation du cache par tag de site.
- Architecture — le socle à plugins isolés et le worker mode FrankenPHP qui contraignent ces choix.