Socle Symfony (multisite, CMS, contact, i18n)

Bundle Symfony réutilisable fournissant des briques transverses (multisite, CMS Markdown, formulaire de contact, i18n, réglages, upload, back-office extensible) qu'une application hôte assemble et configure. Le composant n'est pas une application : il n'a ni entité utilisateur, ni firewall, ni route front publique, ni page d'accueil propre. Il fournit des contrats, des entités, des services et des points d'extension.

• Type de paquet : symfony-bundle, namespace PSR-4 Tlr\Symfony\ → src/.
• Cible : PHP moderne (série 8.x), Symfony 8.x, Doctrine ORM 3.x.
• Distribution par VCS Git (pas de dépôt public de paquets).

Périmètre : ce que le socle fournit / délègue

Architecture d'exécution (chaîne par requête)

Sur l'événement noyau REQUEST (requête principale uniquement), trois abonnés d'événements interviennent dans un ordre de priorité contrôlé :

SiteContext est un service partagé portant l'état « site courant » (setSite/getSite/hasSite) sur le postulat « une requête = un process ». Il est consommé par les contrôleurs, le rendu CMS et l'extension Twig qui expose la variable globale site.

Configuration sémantique du bundle

Nœud racine tlr_symfony :

Paramètres du noyau applicatif repris automatiquement par injection nommée : kernel.enabled_locales → $enabledLocales, kernel.default_locale → $defaultLocale. Une variable d'environnement optionnelle (URI par défaut) alimente le seed de site (repli sur host local si absente).

Le bundle est un micro-bundle (config sémantique + extension inline). Sa méthode build() enregistre deux tags d'autoconfiguration (ConfigSectionInterface, BoPageInterface) : tout service implémentant ces interfaces est collecté automatiquement, sans câblage.

Multisite

Entité Site (table site)

Représente un domaine servi. Champs observables :

Contraintes d'unicité sur host et slug. Méthode matchesHost(string): bool : teste host canonique et alias, insensible à la casse.

Résolution et cloisonnement

• SiteResolver::resolve(string $host): ?Site : normalise, parcourt les sites actifs, retourne le premier matchesHost(), sinon primary(). Cache mémoire (un chargement par requête via SiteRepository::findAllEnabled(), triés isPrimary DESC, label ASC).
• SiteResolver::primary(): ?Site : premier site isPrimary, sinon premier site actif.
• Cloisonnement vitrine (SiteAccessSubscriber) : sur un site vitrine (non primaire) dont le host matche réellement, toute route applicative absente de vitrine_allowed_routes (préfixe localized_ retiré) renvoie 404. Ignoré en mode single-site, pour le site primaire, pour les routes internes (préfixe _) et si aucune route n'est matchée. Le site primaire garde l'application entière.

Garantie d'au moins un site

Commande idempotente tlr:site:ensure-default (options --host, --label, --slug) : crée un Site primaire par défaut seulement si aucun n'existe ; ne touche jamais les sites gérés par l'app/BO. À jouer au déploiement après les migrations (le resolver exige ≥ 1 site, faute de quoi l'app renvoie 404 partout).

Moteur CMS

Entité CmsContent (table cms_content)

Page éditoriale en Markdown, rattachée obligatoirement à un Site. Slug unique par site (contrainte sur site_id, slug), pas globalement.

Constantes exposées : STATUSES, VISIBILITIES, LAYOUTS, TYPE_BLOCK. Helpers : isPublished(), isPublic(), publish().

Statut (cycle de vie) et visibilité (portée d'accès) sont deux axes indépendants. Le socle ne fait pas respecter la visibilité protected/private : CmsContentRepository::findPublished() filtre le statut publié et exclut les blocs, mais l'arbitrage d'accès reste au contrôleur applicatif.

Blocs de chrome (type = block)

Fragment éditable de chrome (nav, footer, bandeau) : jamais servi comme page, jamais indexé, exclu des requêtes pages/sitemap/nav. Rendu dans le layout via la fonction Twig site_block(slug).

CmsTag (table cms_tag)

Vocabulaire de classement partagé entre sites (non scopé). name + slug unique (auto-dérivé). Le tag doc a un rôle : findDocNavBySite() liste les pages taguées doc d'un site, publiées, triées par position ASC, pour bâtir une nav de documentation.

CmsImage (table cms_image)

Métadonnées d'un fichier uploadé : filename, mime, size, width, height, checksum (dédup via findOneByChecksum), createdAt. Rattachée à un owner (CmsUserInterface, non null), un site nullable (onDelete SET NULL, bibliothèque média par domaine), optionnellement un CmsContent. Expose getSlug(): ?string retournant null (contrat attendu par l'uploader).

Édition et rendu

• CmsContentType (formulaire BO) : expose site, titre, slug, excerpt, markdown, statut, visibilité, type, position, noindex, ogImage, layout, tags. L'auteur est posé côté contrôleur (utilisateur courant). Le socle ne fournit pas de contrôleur CMS : l'app câble le CRUD front et BO.
• Layouts fournis (templates/cms/layouts/) : default.html.twig (étend site.layoutTemplate, remplit métas SEO/OG, rend body_html) et three-col.html.twig (mise en page docs à 3 colonnes ; référence un contrôleur et une route de doc côté application).

Contact & anti-spam

ContactDTO

Objet de transport (data_class du formulaire). Validation :

ContactType (formulaire)

Champs name, email, message (textarea avec compteur via contrôleur Stimulus character-counter), send. Libellés = clés de traduction (catalogue fourni par l'app). Option max_length (défaut 2000) pilotant la contrainte, l'attribut HTML maxlength et le compteur.

Honeypot anti-bot : champ website non mappé, masqué (tabindex -1, aria-hidden, autocomplete off). Le socle définit le champ mais ne vérifie pas qu'il est vide — la détection est laissée à l'app.

Contrat anti-spam

interface ContactSpamAnalyzerInterface {
    public function analyze(string $name, string $email, string $message): SpamAnalysisResult;
    public function isEnabled(): bool;
}

SpamAnalysisResult (readonly) : bool $isSpam, string $reason, bool $apiError = false. Le socle définit le contrat mais ne fournit aucune implémentation (l'app branche son analyseur, potentiellement distant).

Internationalisation (i18n)

Mécanique de locale basée sur préfixe d'URL /{_locale}/…, la locale par défaut restant sans préfixe.

• Convention de routage : locale par défaut = route « nue » ; autres locales = route préfixée localized_ avec paramètre _locale. Convention structurante : le retrait du préfixe localized_ conditionne aussi le cloisonnement vitrine.
• LocaleSubscriber (après le routeur) : si l'URL porte une locale activée, la mémorise en session ; sinon applique la locale de session ou la locale par défaut. Ne fait rien sans session préalable.
• LocalizedUrlGenerator : generate($route, $params, $refType), getLocalizedRoute($route), getRouteParams($params).

Réglages applicatifs (Settings)

Magasin clé→valeur persistant. Entité AppSetting (table app_setting) : name string(128) clé primaire, value text nullable.

Service AppSettings (readonly) :

Distinct du hub de configuration BO : AppSettings persiste les valeurs, le hub organise l'UI.

Markdown & upload de fichiers

MarkdownRenderer

toHtml(string $markdown, string $currentPath = '', bool $rewriteDocLinks = true): string. Pipeline CommonMark durci :

• html_input => escape (HTML brut échappé), allow_unsafe_links => false (liens dangereux neutralisés).
• Extensions : cœur CommonMark, GitHub-Flavored (tables, task lists, barré, autoliens), coloration syntaxique serveur, FrontMatter (retire le cartouche YAML du corps rendu).
• Réécriture optionnelle des liens .md vers une route de viewer de doc (défaut docs.show, injectable), avec navigation AJAX ; ne traite que les chemins .md, résout les chemins relatifs en mémoire (sans accès disque). À désactiver hors viewer (le rendu CMS l'appelle avec false).

FileUploader

upload(object $entity, UploadedFile $file): ?string — chemin relatif stocké ou null si refus. Garde-fous :

• Limite de taille (plafond en Mo ; au-delà, refus + log).
• Validation MIME réelle via finfo (pas le MIME déclaré) ; liste blanche image (jpeg, png, webp, gif).
• Nommage : slug (entity->getSlug() ou nom d'origine) + identifiant unique + extension devinée.
• Rangement sous le répertoire public, dans un sous-dossier dérivé du nom court de la classe. Répertoire d'upload surchargeable par config service.

delete(string $fileName): bool — protection anti-traversal : retire les ../, résout le chemin réel, vérifie qu'il reste sous le répertoire public, sinon refuse + log ; idempotent (vrai si le fichier n'existe pas).

Contrat entité : toute entité passée à upload() doit exposer getSlug(): ?string (null autorisé → nom d'origine).

Back-office extensible

Deux registres à points d'extension. N'importe quel bundle/app ajoute une entrée en implémentant une interface auto-taggée, sans toucher la navigation ni les contrôleurs.

Hub de configuration (/admin/config)

ConfigSectionInterface : key() (segment d'URL kebab-case), category() (groupe de nav), label(), icon(), priority() (tri croissant), handle(Request): Response (fragment HTML ou RedirectResponse pour PRG). ConfigSectionRegistry collecte les sections taggées, trie par priorité, groupe par catégorie (get(key), first(), groupedByCategory()). ConfigController (ROLE_ADMIN) rend le hub avec la section active dans un turbo-frame config.

Pages BO (/admin/pages)

BoPageInterface : key(), group(), label(), icon(), priority(), handle(Request): Response. BoPageRegistry collecte, trie, groupe par group(). BoPageController (ROLE_ADMIN) rend la page plein cadre.

Les deux contrôleurs Admin portent ROLE_ADMIN et supposent un firewall applicatif : la sécurité HTTP n'est pas fournie par le socle.

Contrats publics (récapitulatif intégrateur)

Interfaces à implémenter

Auto-mapping Doctrine et résolution d'entité

Toutes les entités sont annotées par attributs et découvertes par Doctrine (auto-mapping ou mapping explicite du namespace Tlr\Symfony\Entity). Aucune migration livrée : l'app génère les siennes (tables site, cms_content, cms_image, cms_tag, app_setting). CmsContent.author et CmsImage.owner ciblent l'interface CmsUserInterface : l'app doit la résoudre vers son entité concrète, sinon le schéma Doctrine est invalide.

doctrine:
    orm:
        auto_mapping: true
        resolve_target_entities:
            Tlr\Symfony\Contract\CmsUserInterface: App\Entity\User

Services publics autowirables

SiteContext, SiteResolver, LocalizedUrlGenerator, MarkdownRenderer, FileUploader, AppSettings, ConfigSectionRegistry, BoPageRegistry, et les repositories (SiteRepository, CmsContentRepository, CmsImageRepository, CmsTagRepository, AppSettingRepository).

Extensions et globales Twig

Templates à fournir par l'app

html.twig (base des templates admin/config/front/erreurs), cms/index.html.twig (base du layout par défaut et du three-col), traductions du formulaire de contact, route de viewer de doc si la réécriture de liens .md est active, contrôleur de panneau doc si le layout three-col est utilisé.

Posture d'intégration minimale

1. Enregistrer le bundle.
2. Activer l'auto-mapping Doctrine (ou mapper le namespace des entités).
3. Déclarer resolve_target_entities pour CmsUserInterface.
4. Fournir les templates de base (html.twig, cms/index.html.twig).
5. Configurer les locales activées et par défaut.
6. Optionnellement configurer tlr_symfony.multisite et vitrine_allowed_routes.
7. Jouer tlr:site:ensure-default au déploiement pour garantir ≥ 1 site.

Dépendances

Runtime : doctrine/doctrine-bundle, doctrine/orm, league/commonmark, psr/log, composants Symfony (config, dependency-injection, doctrine-bridge, event-dispatcher, form, http-foundation, http-kernel, options-resolver, routing, string, validator), un moteur de coloration syntaxique, twig/twig.

Dépendances de framework supposées mais non déclarées (fournies par l'app) : symfony/framework-bundle (contrôleurs AbstractController), un composant de sécurité (ROLE_ADMIN), symfony/twig-bundle, un système de session (i18n), symfony/console (commande de seed).

Absences notables : aucune suite de tests déclarée dans le bundle, aucune migration Doctrine, aucun asset (Bootstrap, Bootstrap Icons, Turbo, Stimulus référencés dans les templates mais fournis par l'app).