Introduction à la syntaxe de Twig : variables, filtres, fonctions et structures de contrôle

Les fondations de Twig : une syntaxe claire et expressive

Twig, le moteur de templates privilégié par Symfony, possède une syntaxe distincte de PHP, conçue spécifiquement pour la création de vues. Son objectif est d'être à la fois puissante pour les développeurs et accessible pour les intégrateurs web. Comprendre ses éléments de base est la première étape pour exploiter pleinement ses capacités. Ce chapitre se concentre sur les quatre piliers de la syntaxe Twig : les variables pour afficher des données, les filtres pour transformer ces données, les fonctions pour des opérations plus complexes, et les structures de contrôle pour ajouter de la logique à vos templates.

La syntaxe de Twig repose sur trois types de délimiteurs principaux qui s'intègrent naturellement dans votre code HTML :

• {{ ... }} : Utilisé pour afficher le résultat d'une expression (typiquement une variable ou l'appel d'une fonction/filtre). On parle d'"expression d'affichage".
• {% ... %} : Utilisé pour exécuter des instructions logiques, comme les boucles, les conditions, ou la définition de blocs. On parle d'"instruction de tag".
• {# ... #} : Utilisé pour les commentaires. Ces derniers ne sont pas rendus dans le HTML final.

En maîtrisant ces éléments, vous serez capable de prendre les données préparées par vos contrôleurs Symfony et de les présenter de manière dynamique, structurée et sécurisée à vos utilisateurs.

Afficher des données avec les variables

Les variables sont le moyen par lequel les données de votre application (transmises par le contrôleur) deviennent accessibles dans le template. Pour afficher une variable, vous l'encadrez simplement par des doubles accolades : {{ nom_de_la_variable }}.

Si la variable est un objet ou un tableau associatif, vous pouvez accéder à ses attributs, méthodes ou clés en utilisant la notation "point" (.) ou la notation "crochets" ([]). Twig est intelligent et essaie plusieurs méthodes pour récupérer la valeur :

• Pour {{ produit.nom }}, Twig essaiera :
1. D'accéder à la clé 'nom' si produit est un tableau ($produit['nom']).
2. D'accéder à la propriété publique nom si produit est un objet.
3. D'appeler la méthode getNom() si produit est un objet.
4. D'appeler la méthode isNom() si produit est un objet.
5. D'appeler la méthode hasNom() si produit est un objet.
6. Si rien n'est trouvé et que la variable Twig strict_variables est à false (par défaut en mode dev), cela affichera une chaîne vide ou lèvera une erreur en mode strict.
• La notation avec crochets est utile lorsque le nom de la clé contient des caractères spéciaux ou est lui-même une variable : {{ user['user-name'] }} ou {{ mon_tableau[cle_dynamique] }}.

Exemple :

{# Supposons que le contrôleur a passé : #}
{# 'utilisateur' => un objet User avec une méthode getUsername() #}
{# 'config' => un tableau ['couleur_fond' => '#FAFAFA'] #}

<p>Bonjour, {{ utilisateur.username }} !</p>
<div style="background-color: {{ config.couleur_fond }};">
    Contenu avec fond dynamique.
</div>

Par défaut, Twig échappe automatiquement toutes les variables affichées avec {{ ... }}. Cela signifie que les caractères HTML spéciaux (comme <, >, &) sont convertis en leurs entités HTML correspondantes (<, >, &). C'est une mesure de sécurité cruciale contre les attaques XSS. Si vous avez besoin d'afficher du HTML brut (et que vous êtes certain de sa provenance), vous devez utiliser le filtre raw : {{ mon_contenu_html | raw }}.

Transformer l'affichage avec les filtres

Les filtres sont des fonctions spéciales que vous pouvez appliquer aux variables pour modifier leur formatage ou leur contenu avant l'affichage. Ils sont chaînés à une variable ou à une expression à l'aide du symbole pipe (|) et peuvent prendre des arguments entre parenthèses.

Twig vient avec une riche collection de filtres intégrés. Voici quelques exemples parmi les plus utiles :

• Modification de casse :
  • {{ 'Bonjour le monde' | upper }} → BONJOUR LE MONDE
  • {{ 'Bonjour le monde' | lower }} → bonjour le monde
  • {{ 'bonjour le monde' | capitalize }} → Bonjour le monde
  • {{ 'bonjour le monde' | title }} → Bonjour Le Monde
• Formatage de dates : (nécessite que la variable soit un objet DateTime ou un timestamp)
  • {{ article.datePublication | date('d/m/Y H:i:s') }} → 25/12/2023 14:30:00
  • {{ 'now' | date('Y') }} → Année actuelle
• Manipulation de chaînes :
  • {{ 'Texte trop long' | slice(0, 5) }}... → Texte...
  • {{ ' espaces ' | trim }} → espaces
  • {{ 'pomme,banane,orange' | split(',') }} → retourne un tableau PHP ['pomme', 'banane', 'orange'] (utilisable dans une boucle for)
• Formatage de nombres :
  • {{ 12345.678 | number_format(2, ',', ' ') }} → 12 345,68
• Gestion des valeurs par défaut :
  • {{ variable_optionnelle | default('Valeur si non définie ou vide') }}
• Encodage et sécurité :
  • {{ url_param | url_encode }} → Encode une chaîne pour une URL.
  • {{ 'Donnée brute <script>alert("XSS")</script>' | escape }} → (C'est le comportement par défaut, mais escape peut forcer l'échappement si besoin ou spécifier un contexte d'échappement différent : js, css, html_attr).
  • {{ html_confiance | raw }} → A utiliser avec une extrême prudence ! Désactive l'échappement automatique.
• Manipulation de tableaux/objets :
  • {{ [1, 2, 3, 4, 5] | length }} → 5
  • {{ ['a', 'b', 'c'] | join(', ') }} → a, b, c
  • {{ mon_tableau | reverse }} → Inverse l'ordre des éléments.

Vous pouvez chaîner plusieurs filtres : {{ ma_variable | trim | upper }}. Ils sont appliqués de gauche à droite.

Utiliser les fonctions pour des opérations complexes

Les fonctions dans Twig sont similaires aux fonctions en PHP. Elles sont appelées par leur nom suivi de parenthèses, qui peuvent contenir des arguments. Les fonctions sont généralement utilisées pour générer du contenu ou effectuer des actions plus complexes que ce que permettent les filtres simples.

Quelques fonctions Twig couramment utilisées dans un contexte Symfony :

• path(nom_route, parametres_route) : Génère une URL relative pour une route Symfony. C'est la fonction la plus utilisée pour créer des liens.
  • Exemple : <a href="{{ path('app_article_show', { 'slug': article.slug }) }}">{{ article.titre }}</a>
• url(nom_route, parametres_route) : Similaire à path(), mais génère une URL absolue (avec le schéma et le nom d'hôte).
• asset(chemin_fichier) : Génère le chemin vers un fichier public (CSS, JS, image) géré par Symfony Encore (Webpack) ou le système d'assets traditionnel.
  • Exemple :
• random(valeurs) : Retourne un élément aléatoire d'un tableau ou d'une chaîne.
  • Exemple : {{ random(['Rouge', 'Vert', 'Bleu']) }}
• range(debut, fin, pas) : Crée une séquence de nombres, utile pour les boucles.
  • Exemple : {% for i in range(0, 5) %} {{ i }} {% endfor %} → 0 1 2 3 4 5
• include(template, variables, options) : Inclut le contenu d'un autre template Twig. Très utile pour décomposer les vues en morceaux réutilisables.
  • Exemple : {{ include('fragments/_header.html.twig') }}
• dump(variable1, variable2, ...) : Affiche des informations de débogage sur une ou plusieurs variables, similaire à var_dump() en PHP. Nécessite que le DebugExtension soit activé (généralement le cas en environnement de développement). Très utile pour inspecter le contenu des variables dans vos templates.

Symfony et les bundles que vous ajoutez peuvent fournir leurs propres fonctions Twig personnalisées pour simplifier des tâches spécifiques à votre application.

Implémenter la logique avec les structures de contrôle

Les structures de contrôle permettent d'introduire de la logique dans vos templates Twig, comme afficher du contenu conditionnellement ou itérer sur des collections de données. Elles utilisent la syntaxe {% ... %}.

Conditions if/elseif/else :

{% if user.isLoggedIn() %}
    <p>Bienvenue, {{ user.username }} !</p>
{% elseif user.isGuest %}
    <p>Bonjour visiteur.</p>
{% else %}
    <p>Veuillez vous connecter.</p>
{% endif %}

Les opérateurs logiques (and, or, not) et de comparaison (==, !=, <, >, <=, >=) sont disponibles. Vous pouvez également utiliser des tests avec l'opérateur is : {% if produit is defined and produit.prix > 0 %} ... {% endif %}. Tests courants : defined, null, empty, even, odd, iterable.

Boucles for :

Pour itérer sur les éléments d'un tableau ou d'un objet itérable :

<ul>
    {% for produit in produits %}
        <li>{{ produit.nom }} - {{ produit.prix | number_format(2) }} €</li>
    {% else %}
        <!-- Ce bloc est exécuté si 'produits' est vide ou non itérable -->
        <li>Aucun produit disponible.</li>
    {% endfor %}
</ul>

A l'intérieur d'une boucle for, la variable spéciale loop donne accès à des informations sur l'itération en cours :

• loop.index: L'index actuel de la boucle (commence à 1).
• loop.index0: L'index actuel de la boucle (commence à 0).
• loop.revindex: Le nombre d'itérations restantes (commence par la longueur totale).
• loop.revindex0: Le nombre d'itérations restantes (indexé à partir de 0).
• loop.first: Vrai si c'est la première itération.
• loop.last: Vrai si c'est la dernière itération.
• loop.length: Le nombre total d'éléments dans la séquence.
• loop.parent: Le contexte de la boucle parente (si vous avez des boucles imbriquées).

{% for user in users %}
    <div class="{{ loop.first ? 'first-user' : '' }} {{ loop.index is odd ? 'odd-row' : 'even-row' }}">
        {{ loop.index }}. {{ user.name }}
    </div>
{% endfor %}

Définition de variables avec set :

Vous pouvez définir des variables directement dans le template :

{% set nom_complet = utilisateur.prenom ~ ' ' ~ utilisateur.nom | upper %}
<p>{{ nom_complet }}</p>

Ces éléments de syntaxe constituent la base de la création de templates avec Twig. En les combinant avec l'héritage de templates et les inclusions (que nous verrons plus tard), vous pouvez construire des interfaces utilisateur complexes et maintenables.