Référence : domaines de site (plugin web)¶
Cette page décrit, de façon exhaustive et neutre, les règles qui régissent le domaine d'un site dans le plugin web : l'invariant « un domaine par site », les règles d'unicité, les états, les messages et le comportement de l'onglet Domaine. Pour un parcours pas à pas côté utilisateur, voir le tutoriel Personnaliser son site — « Rattacher un domaine » ; pour le pourquoi de la résolution domaine → site, voir Multi-tenant : résolution d'un domaine vers un site.
Où cela se règle¶
Onglet Domaine des réglages du site d'un carnet, à l'adresse /u/web/reglages/site/{notebookId} (accessible depuis le menu ⋯ de la carte du carnet → « Configurer Web », dans « Mon espace »). Le rendu est porté par le template src/Plugin/Web/templates/settings/_domains.html.twig. Voir le guide Configurer le site web d'un carnet.
Le rattachement du domaine crée le site du carnet
Un carnet sans domaine n'a pas de site : tant qu'aucun domaine n'est rattaché, seul l'onglet Domaine est proposé. Le rattachement du premier domaine est le seul point de naissance d'un site — le contrôleur d'ajout crée le Site du carnet puis lui rattache le domaine. Les onglets Pages spéciales et Apparence n'apparaissent qu'ensuite. Le pourquoi est détaillé dans Configuration par carnet et extensibilité des plugins.
Invariant : un domaine unique par site¶
Chaque site est borné à un seul domaine. L'ajout d'un domaine à un site qui en possède déjà un est refusé. Pour changer de domaine, il faut supprimer l'actuel puis en ajouter un nouveau.
L'invariant est posé à deux niveaux, en défense en profondeur :
| Niveau | Mécanisme | Emplacement |
|---|---|---|
| Garde applicative | Le contrôleur d'ajout rejette la requête si un domaine est déjà rattaché au site, avant même de valider l'hôte saisi. | src/Plugin/Web/src/Controller/WebPluginSiteDomainAddController.php (appel à SiteDomainRepositoryInterface::existsForSite()) |
| Contrainte de schéma | La JoinColumn site_id de l'association ManyToOne porte unique: true : la base refuse un second domaine sur le même site. |
src/Plugin/Web/src/Entity/SiteDomain.php (index unique sur web_plugin_domain.site_id) |
La méthode existsForSite(Site $site): bool est déclarée sur SiteDomainRepositoryInterface et implémentée dans SiteDomainRepository (src/Plugin/Web/src/Repository/).
Règles d'unicité¶
Deux unicités distinctes coexistent :
| Règle | Portée | Effet |
|---|---|---|
| Un domaine par site | Un site donné | Rejette l'ajout d'un second domaine au même site (invariant ci-dessus). |
| Un hôte par plateforme | Toute la plateforme | Un même hôte ne peut être rattaché qu'à un seul site, tous sites confondus (colonne host unique). |
L'hôte saisi est normalisé et validé par le Value Object Domain (src/Plugin/Web/src/ValueObject/Domain.php) avant persistance : hôte ASCII/punycode, sans schéma (http://) ni chemin.
Ordre des contrôles à l'ajout¶
Le contrôleur d'ajout (POST /u/web/reglages/site/{notebookId}/domaines, route web_plugin_site_domain_add) applique, dans l'ordre :
- Résolution du carnet et autorisation via
NotebookVoter::EDIT(appartenance du carnet, anti-IDOR). - Résolution du site du carnet — il peut ne pas exister encore ; s'il existe, filet supplémentaire via
SiteVoter::EDIT. - Validation du jeton CSRF
site_domain_add-<notebookId>. - Invariant « un domaine par site » — refus si le site en possède déjà un.
- Validation de l'hôte par le VO
Domain. - Unicité globale de l'hôte.
- Naissance du site — si le carnet n'a pas encore de
Site, il est créé ici (new Site($notebookId, $ownerId)). - Persistance du domaine et message de succès.
L'étape 4 court-circuite les étapes 5 et 6 : sur un site déjà pourvu, l'ajout est refusé quel que soit l'hôte saisi. La création du site (étape 7) n'a lieu qu'après validation complète de l'hôte : un rattachement refusé ne crée pas de site.
Le carnet est obligatoire
{notebookId} est un segment obligatoire de la route, contraint à un UUIDv7 (Requirement::UUID_V7) et résolu en App\Entity\Notebook par MapEntity : un carnet inconnu produit un 404. Il n'existe aucune variante de la route sans carnet — la configuration du site est intégralement scopée au carnet.
États d'un domaine¶
L'état est porté par l'enum DomainState (src/Plugin/Web/src/Entity/Enum/DomainState.php). Il est affiché sans jamais reposer sur la seule couleur (pastille + couleur + texte).
| Case | Valeur | Libellé | Signification |
|---|---|---|---|
EnAttente |
en_attente |
En attente | Domaine rattaché, mais encore jamais visité. |
Actif |
actif |
Actif | Le domaine a reçu sa première requête ; la transition est passive (déclenchée par la première visite). |
La transition « En attente » → « Actif » est détaillée dans Multi-tenant : l'état passif du domaine.
Comportement de l'onglet Domaine¶
Le formulaire de rattachement et l'affichage du domaine sont mutuellement exclusifs :
- Aucun domaine rattaché — un formulaire de rattachement est proposé (champ hôte + bouton Rattacher).
- Un domaine rattaché — le formulaire de rattachement disparaît ; le domaine est affiché avec :
- son hôte et son badge d'état ;
- un lien « Voir mon site » vers
https://<hôte>, ouvert dans un nouvel onglet (target="_blank",rel="noopener") ; - un bouton Supprimer (confirmation avant suppression).
Un rappel accompagne l'affichage : pour changer de domaine, supprimer l'actuel puis en rattacher un nouveau.
Messages¶
| Canal de flash | Message | Déclencheur |
|---|---|---|
web_plugin_success |
« Domaine rattaché. Il passera « actif » dès la première visite. » | Rattachement réussi. |
web_plugin_success |
« Domaine supprimé. » | Suppression réussie (WebPluginSiteDomainRemoveController). |
domain_error |
« Votre site possède déjà un domaine. Supprimez-le avant d'en rattacher un autre. » | Ajout sur un site déjà pourvu (invariant). |
domain_error |
« Ce domaine est déjà rattaché à un site. » | Hôte déjà pris par un autre site (unicité globale). |
domain_error |
Message du VO Domain |
Hôte mal formé. |
Table et route¶
| Élément | Valeur |
|---|---|
| Table Doctrine | web_plugin_domain |
| Index unique | site_id (un domaine par site), host (unicité globale) |
| Route d'ajout | web_plugin_site_domain_add — POST /u/web/reglages/site/{notebookId}/domaines (le carnet porte la route : le site n'existe pas encore) |
| Route de suppression | web_plugin_site_domain_remove — POST /u/web/reglages/site/domaines/{id}/suppression (le domaine existe : la route porte son identifiant) |
| Retour après action | web_plugin_site_settings — GET /u/web/reglages/site/{notebookId}, le hub du carnet concerné ({notebookId} déduit du site du domaine lors d'une suppression) |
Voir aussi¶
- Configurer le site web d'un carnet — rattacher un domaine (et créer le site) carnet par carnet.
- Configuration par carnet et extensibilité des plugins — pourquoi le site naît au rattachement du domaine.
- Personnaliser son site (tutoriel) — rattacher et changer un domaine, pas à pas.
- Multi-tenant : résolution d'un domaine vers un site — pourquoi le domaine est résolu à l'exécution, et l'état passif.
- Servir les domaines de site en HTTPS — côté opérateur, terminer le TLS d'un domaine.