# Galactic-Shrine Twig Coding Standard

**Version:** 1.0.0  
**Auteur / Author:** ⋞Galactic-Shrine⋟  
**Portée / Scope:** Projets Twig / Symfony / Layouts / Pages / Partials / Components / Emails / Back-office / Fragments réutilisables

---

## 1. Objectif

Ce standard définit la manière d’écrire le code **Twig** dans les projets Galactic-Shrine.

Il a pour objectifs :

- d’uniformiser les templates Twig ;
- de limiter la logique applicative dans les vues ;
- de garder des layouts et composants lisibles ;
- d’aligner l’organisation Twig avec Symfony et les conventions Galactic-Shrine.

---

## 2. Principes généraux

Le code Twig Galactic-Shrine doit être :

- lisible ;
- structuré ;
- peu chargé en logique ;
- prévisible ;
- compatible avec une maintenance long terme.

Le code doit privilégier :

- des templates ciblés ;
- des blocks utiles ;
- des includes explicites ;
- un contexte de vue préparé en amont ;
- une logique d’affichage simple.

---

## 3. Décisions officielles Galactic-Shrine pour Twig

Décisions officielles :

- garder la logique métier hors Twig ;
- préparer les données dans le contrôleur, le presenter ou la couche dédiée ;
- nommer les blocks, templates et partials de manière explicite ;
- utiliser des variables de contexte claires ;
- limiter les conditions imbriquées dans les vues ;
- conserver une cohérence forte entre layout, partials et composants.

---

## 4. Convention de nommage

- templates : nommés selon leur rôle (`profile/show.html.twig`, `components/user-card.html.twig`) ;
- blocks : explicites ;
- variables Twig : convention du contexte préparé par l’application ;
- macros : rares, ciblées et clairement nommées ;
- fragments : pas de noms vagues.

Lorsque le contexte applicatif appartient à Galactic-Shrine, privilégier des noms clairs et stables.  
Lorsque Twig consomme des structures externes, conserver la convention imposée par la source.

---

## 5. Structure recommandée d’un template Twig

Ordre recommandé :

1. `extends` ou structure principale ;
2. définition des blocks majeurs ;
3. includes ou embeds ciblés ;
4. fragments secondaires ;
5. scripts et hooks spécifiques si nécessaires.

Règles :

- un template doit avoir un rôle identifiable ;
- un partial doit être réellement réutilisable ou spécialisé ;
- ne pas transformer un template en couche métier déguisée.

---

## 6. Style d’écriture

### 6.1 Conditions

- garder des conditions simples ;
- éviter l’enchaînement de logique métier ;
- préparer les états complexes en amont.

### 6.2 Blocks et includes

- créer un `block` pour un vrai point d’extension ;
- utiliser `include` pour les fragments réutilisables ;
- utiliser `embed` seulement si le gain structurel est réel.

### 6.3 Variables

- préférer des variables déjà normalisées ;
- éviter les chaînes d’accès trop profondes répétées ;
- garder les noms du contexte cohérents entre contrôleurs et templates.

---

## 7. Règles spécifiques Twig

- ne pas effectuer de calcul métier important dans Twig ;
- limiter les filtres chaînés difficiles à lire ;
- traiter les permissions et états complexes avant rendu quand possible ;
- garder les composants Twig stables et bien délimités ;
- préserver l’accessibilité du HTML produit.

---

## 8. Gestion des erreurs et robustesse

- prévoir les données optionnelles explicitement ;
- ne pas supposer silencieusement qu’une variable existe si le contrat est flou ;
- centraliser les valeurs par défaut importantes ;
- garder les templates résilients aux contextes partiels raisonnables.

---

## 9. Types d’éléments à revoir en priorité

Relire en priorité :

- layouts ;
- templates de page ;
- composants réutilisables ;
- partials complexes ;
- emails ;
- blocs avec permissions ou états multiples ;
- vues fortement couplées à JavaScript.

---

## 10. Exemple complet recommandé

```twig
{% extends 'layout/base.html.twig' %}

{% block body %}
    <main class="GsProfilePage">
        {% include 'components/profile/header.html.twig' with {
            User: User,
            Statistics: Statistics
        } only %}

        {% if RecentActivities is not empty %}
            {% include 'components/profile/recent-activities.html.twig' with {
                Activities: RecentActivities
            } only %}
        {% endif %}
    </main>
{% endblock %}
```

---

## 11. Décision officielle recommandée

Standard officiel recommandé pour Galactic-Shrine Twig :

- logique métier hors template ;
- templates et partials explicites ;
- contexte préparé en amont ;
- conditions courtes ;
- structure de layout propre et maintenable.

---

## 12. Résumé exécutable

À appliquer dans tous les projets Twig Galactic-Shrine :

- peu de logique dans Twig ;
- blocks et includes ciblés ;
- noms de templates explicites ;
- contexte clair ;
- HTML produit sémantique et stable.