Écrire ses propres thèmes : les arbitrages¶
Cette page explique pourquoi la bibliothèque de thèmes se comporte comme elle se comporte : pourquoi un thème appartient au compte et non au carnet, pourquoi créer un thème produit une copie de « Par défaut » plutôt qu'une page blanche, pourquoi le CSS et les gabarits ne sont pas traités de la même façon, pourquoi rien n'est jamais refusé à l'enregistrement, et pourquoi supprimer un thème en service est autorisé.
Elle s'adresse aux personnes qui font évoluer Kirexo. Pour les gestes, voir Créer, dupliquer, modifier et supprimer un thème de site ; pour le contrat exact, Référence — Thèmes de site ; pour le modèle et le catalogue fourni, Modèle de thème et catalogue fourni ; pour les barrières de sécurité, Sécurité du rendu personnalisé des sites.
L'écriture ouvre ce que le choix laissait fermé¶
Le modèle de thème posé précédemment ne proposait qu'un choix : trois habillages maintenus par le projet, un sélecteur, rien à écrire. Les trois thèmes fournis vivent en fichiers versionnés et le resteront — leur immuabilité n'est pas une règle d'autorisation, c'est l'absence de chemin d'écriture, argument développé dans Modèle de thème et catalogue fourni.
Ce qui change avec la bibliothèque, c'est qu'un second régime apparaît à côté : des thèmes en base, écrits par un utilisateur, avec les quatre mêmes sources. Toutes les décisions qui suivent découlent d'une même contrainte : ce second régime ne doit ni fragiliser le rendu public, ni transformer l'écriture d'un thème en parcours d'obstacles.
Portée compte, pas carnet¶
Un thème est rattaché à un utilisateur (Theme::userId, src/Plugin/Web/src/Entity/Theme.php), jamais à un carnet. Un thème écrit une fois est applicable au site de n'importe lequel de ses carnets.
L'alternative — un thème par carnet — aurait été plus simple à câbler, puisque toute la configuration web est déjà scopée au carnet (voir Configuration par carnet et extensibilité des plugins). Elle a été écartée parce qu'elle produit mécaniquement de la duplication : un auteur avec trois carnets et une charte visuelle unique aurait dû écrire trois fois le même thème, puis répercuter chaque correction trois fois. La configuration d'un site est propre à un carnet ; son habillage est une identité d'auteur.
Le prix de ce choix se paye sur l'accès. Comme la bibliothèque n'appartient à aucun carnet, elle ne pouvait pas vivre dans le hub des réglages d'un carnet — d'où une route hors hub, /u/web/themes. Tant qu'elle n'était atteignable que depuis l'onglet Apparence d'un carnet configuré, un compte sans domaine rattaché ne pouvait pas atteindre ses propres thèmes : une portée compte accessible seulement par un carnet, c'est-à-dire l'incohérence exacte que le choix de portée voulait éviter.
Elle est donc atteinte par une entrée du menu de l'espace utilisateur, « Mes thèmes ». Le cœur ne cite pour autant aucune route du plugin : celui-ci déclare la capability UserMenuContributorInterface (src/Plugin/Contracts/UserMenuContributorInterface.php), et le composant App\Twig\Components\UserMenuPluginLinks (src/Twig/Components/UserMenuPluginLinks.php) agrège les plugins qui la portent et qui sont actifs pour le compte courant. C'est la même mécanique que la configuration par carnet (voir Configuration par carnet et extensibilité des plugins) : un point d'extension neutre plutôt qu'un lien codé en dur.
Ce choix a une conséquence de sécurité directe : le compteur « N site(s) » affiché sur chaque ligne de la bibliothèque est scopé au compte. Les clés des thèmes fournis sont partagées par toute la plateforme ; les compter sans scope divulguerait l'usage des autres comptes.
Créer, c'est copier « Par défaut »¶
Un thème neuf n'est pas vide : il est créé comme une copie du thème fourni « Par défaut ». Trois options étaient sur la table.
- Un thème réellement vide. Rejetée : elle ramène par la porte de la création l'écart que le modèle de thème avait précisément corrigé — un site sans navigation ni style, sans que rien ne l'annonce.
- Un squelette commenté écrit en dur dans le contrôleur. Rejetée : ce markup divergerait tôt ou tard de
src/Plugin/Web/themes/default/, et personne ne le remarquerait avant qu'un utilisateur ne s'en plaigne. - Une copie de « Par défaut » — retenue. Le point de départ est un site complet et stylé, maintenu par le projet, qui ne peut pas dériver puisqu'il est la source.
L'auteur qui veut réellement partir de rien vide les zones. C'est un geste explicite, réversible dans la session d'édition, et surtout : il sait ce qu'il fait.
Le même raisonnement rend la duplication centrale. C'est la seule opération offerte sur un thème fourni, et l'invariant qui la soutient — aucune déclaration des thèmes fournis n'est retirée par le filtre CSS — est ce qui garantit qu'une copie de Classique rend comme Classique. Sans lui, dupliquer serait un piège. Voir Reproductibilité.
Deux régimes de persistance : CSS filtré, gabarits bruts¶
C'est l'asymétrie la plus visible à l'usage, et elle est délibérée.
- Le CSS est persisté déjà filtré (
CssFilter,src/Plugin/Web/src/Security/CssFilter.php) : ce qui dort en base est propre. Un fragment retiré ne revient pas dans le champ après enregistrement. - Les gabarits (en-tête, corps, pied) sont persistés bruts et assainis au rendu (sandbox Twig + sanitizer
site_public).
Le premier régime se justifie par le fait qu'un CSS filtré est un CSS fini : le filtre est déterministe, sa sortie est du CSS valide et servi tel quel. Le stocker filtré évite de refaire le travail à chaque requête publique — même si le contrôleur de feuille de style refiltre malgré tout, en défense en profondeur, pour couvrir ce qui entrerait par un autre chemin (fixtures, import, SQL direct).
Le second régime, lui, est imposé par la nature d'un gabarit : c'est du code, pas des données. Un {% if %} n'a de sens qu'exécuté, et son résultat dépend du contexte de la page servie. « Assainir à l'écriture » demanderait de rendre le gabarit une fois pour toutes avec un contexte fictif, puis de stocker sa sortie — autant dire de perdre le gabarit. C'est aussi le régime des thèmes fournis : un seul pipeline de rendu pour les deux origines, sans branche à maintenir.
L'effet secondaire est heureux : l'auteur relit son HTML tel qu'il l'a écrit, y compris les fragments que le rendu retirera. Il peut corriger. C'est l'inverse pour le CSS, et c'est le compromis assumé de ce couple.
Rien n'est refusé : avertir plutôt que bloquer¶
Enregistrer un thème ne peut pas échouer pour une raison de contenu. Un corps sans {{ content }}, une balise interdite, un tag Twig hors sandbox, un fragment CSS non autorisé : dans tous les cas l'enregistrement réussit, et l'auteur reçoit un message qui dit ce qui a été retiré et pourquoi.
L'option inverse — refuser l'enregistrement tant que le corps ne contient pas l'emplacement de contenu — avait été envisagée, sous forme d'une contrainte de validation. Elle a été abandonnée en cours de route, pour deux raisons.
Le rendu sait déjà se rabattre. Un corps sans emplacement voit le contenu ajouté en fin de zone ; un gabarit refusé par la sandbox fait retomber le site sur « Par défaut » en entier. Dans les deux cas, le site reste servi et lisible. Refuser à l'écriture protégerait donc contre un risque que le rendu a déjà neutralisé.
Le coût du refus tombe sur l'auteur, pas sur le site. Un thème s'écrit par itérations : on enregistre un état intermédiaire, on va regarder, on revient. Bloquer sur l'absence d'une sentinelle qu'on s'apprêtait à ajouter, c'est jeter quatre zones de travail pour un oubli de trente secondes. La validation ne porte donc plus que sur ce qui n'a aucun rattrapage possible : un nom vide (impossible à afficher) et une zone au-delà de la taille que le sanitizer tronquerait silencieusement.
Cette dernière borne mérite d'être notée : la taille maximale d'une zone est alignée sur le max_input_length du profil site_public. Sans elle, on accepterait un gabarit dont une partie ne serait jamais rendue, sans rien dire à l'auteur — le pire des deux mondes, puisqu'on aurait à la fois accepté et perdu.
La même logique dicte le comportement en cas d'erreur de validation : le formulaire est réaffiché avec la saisie (réponse 422), jamais redirigé. Une redirection relirait le thème depuis la base et effacerait les quatre zones que l'auteur vient d'écrire — exactement ce qu'on refuse de lui infliger ailleurs.
Les diagnostics viennent du pipeline réel¶
Les messages affichés ne sont pas une réimplémentation « d'éditeur » : ils sortent du même filtre CSS et du même renderer que le rendu public, en mode rapport (HtmlOverrideRenderer::renderWithReport(), src/Plugin/Web/src/Security/HtmlOverrideRenderer.php). Ce mode, décrit dans Le mode rapport : expliquer plutôt que planter, avait été conçu sans consommateur ; l'édition de thème en est le premier.
Deux détails d'implémentation en découlent, et ils comptent.
- Le rendu d'essai utilise un contexte représentatif — un profil, une page, un article — et non un contexte vide. Avec des tableaux vides,
{% if pages is not empty %}et{% for page in pages %}ne s'exécuteraient jamais : les violations de sandbox qui s'y cachent passeraient inaperçues à l'enregistrement pour ressurgir en production. - Le retrait HTML se mesure en nombre de balises, pas en comparant les chaînes. Le profil
site_publicforce l'attributrelsur tout<a>: une comparaison de chaînes déclencherait donc une notice à tonalité sécurité à chaque enregistrement d'une zone contenant un lien, y compris pour un thème fourni dupliqué sans modification. Un avertissement qui se déclenche toujours ne veut plus rien dire.
Supprimer un thème en service ne bloque pas¶
La suppression est autorisée même quand des sites appliquent le thème. Ceux-ci retombent sur « Par défaut », leur cache est invalidé, et l'auteur est informé du nombre de sites concernés.
Interdire la suppression tant qu'un site l'utilise aurait paru plus prudent. Mais le résultat final serait identique — l'auteur repasserait sur chaque site pour le détacher, puis supprimerait — au prix d'une corvée proportionnelle au nombre de carnets. Et surtout, le repli existe déjà : Site::themeKey n'a pas de clé étrangère, et ThemeResolver retombe sur « Par défaut » pour toute clé qui ne désigne plus rien (voir Pourquoi un repli silencieux plutôt qu'une erreur). Le cas « thème supprimé » n'est donc pas un accident à prévenir : c'est un cas nominal déjà traité.
Ce que la suppression doit garantir, en revanche, c'est que les sites concernés soient capturés avant l'opération : une fois le thème parti, sa clé ne désigne plus rien et il devient impossible de savoir quels caches invalider.
Le formulaire est un POST classique, sauf le CSS¶
Les cinq champs partent dans un seul formulaire HTML, avec un jeton CSRF lié à la ressource. Aucun Live Component ne pilote le nom ni les trois zones : ils n'ont aucun aller-retour serveur à faire, et un composant temps réel n'y apporterait qu'une dépendance au JavaScript.
Le CSS fait exception, pour une raison précise : le filtre et la liste des propriétés autorisées vivent en PHP, source unique. Montrer « ce qui sera retiré » avant d'enregistrer suppose donc un aller-retour serveur — c'est le rôle du Live Component ThemeCssEditor (src/Plugin/Web/src/Twig/Component/ThemeCssEditor.php), et la raison pour laquelle l'autocomplétion CodeMirror est alimentée par la whitelist serveur plutôt que par une liste recopiée dans le JavaScript.
Ce composant ne persiste rien. Il est monté à l'intérieur du formulaire du thème, dont il partage le bouton d'enregistrement — un <form> imbriqué serait du HTML invalide. Son <textarea name="css"> part donc avec le reste du formulaire, ce qui produit deux propriétés d'un coup :
- le repli sans JavaScript est gratuit : le CSS s'envoie normalement, seule l'assistance (coloration, autocomplétion, bouton « Vérifier le CSS ») disparaît, et le filtrage a lieu de toute façon à l'enregistrement avec les mêmes messages ;
- il n'y a rien à défendre côté composant : ne pas écrire, c'est ne pas avoir à se prémunir d'un identifiant de thème forgé. La seule écriture passe par le contrôleur de mise à jour, derrière le
ThemeVoter.
Autorisation : une propriété, jamais un if¶
ThemeVoter (src/Plugin/Web/src/Security/ThemeVoter.php) tranche THEME_EDIT et THEME_DELETE sur la seule appartenance du thème au compte connecté. Le thème d'un autre compte donne un 403, et il n'apparaît nulle part dans la bibliothèque.
Les thèmes fournis, eux, ne passent pas par ce Voter. Ce ne sont pas des entités : la question « ai-je le droit de modifier Classique ? » n'a pas de réponse parce qu'elle n'a pas de destinataire — il n'existe aucune route capable d'écrire dans src/Plugin/Web/themes/. Leur immuabilité ne dépend d'aucune décision d'autorisation.
La duplication est le point où les deux régimes se croisent, et donc le point sensible : le thème source y est cherché parmi les choix réels de l'utilisateur (ThemeResolver::choicesFor()), pas par un accès direct en base. Sans cela, dupliquer deviendrait un moyen de lire le travail d'un autre compte à partir de son seul identifiant.
Le rel des liens : pourquoi une passe DOM plutôt qu'un attribut¶
Le profil site_public du sanitizer force rel="noopener noreferrer" sur tout <a>, mais il ne peut pas y ajouter nofollow sans discernement : un thème porte la navigation interne du site, et déclasser ses propres pages serait absurde. Inversement, ne jamais poser nofollow laisse un problème réel — un lien de thème est site-wide, présent sur chaque page, ce qui est le motif même du link farm, là où un lien d'article reste unitaire.
La décision dépend donc de l'hôte visé : interne, on ne touche à rien ; externe, on ajoute nofollow. C'est ce que fait ExternalLinkRelSanitizer (src/Plugin/Web/src/Security/ExternalLinkRelSanitizer.php), en passe DOM appliquée après le sanitizer.
La piste initiale — un AttributeSanitizerInterface sur rel — a été écartée pour une raison d'API, et elle mérite d'être notée parce qu'elle n'est pas évidente : Symfony ne présente qu'un attribut isolé à la fois (sanitizeAttribute($element, $attribute, $value, $config)), sans accès au href depuis le rel. Impossible d'y décider quoi que ce soit qui dépende de la cible du lien. En travaillant sur la sortie déjà assainie, où href et rel coexistent, on garde en prime une seule allowlist : pas de second profil de sanitizer à maintenir en parallèle.
Un détail de cohérence en découle : l'hôte du site est lu depuis le site résolu (attribut de requête posé par la résolution multi-tenant), jamais depuis l'en-tête Host brut. Le rendu public étant mis en cache par site, la décision interne/externe doit l'être aussi — sinon deux domaines du même site produiraient deux versions du même cache.
Voir aussi¶
- Créer, dupliquer, modifier et supprimer un thème de site — les gestes correspondants.
- Référence — Thèmes de site — routes, jetons CSRF, validation, messages, effets exacts.
- Modèle de thème et catalogue fourni — pourquoi un thème est un objet, pourquoi les fournis vivent en fichiers, pourquoi le repli est silencieux.
- Sécurité du rendu personnalisé des sites — les quatre barrières traversées par les sources d'un thème et le mode rapport.
- Ce que vous pouvez personnaliser sur votre site (et pourquoi ces limites) — la même matière, racontée pour les auteur·ices.