Installation & configuration

Twig est un moteur de template développé en PHP par les équipes de Sensiolabs (Fabien Potencier et ses équipes) pour Symfony à l'origine. Toutefois, il est possible de l'utiliser de façon indépendante de du framework.

Prérequis

Au moment de ce tutoriel, la dernière version est la 3.21.1. Il requiert d'avoir PHP 8.1 installé au minimum.

Installation

Pour installer Twig, le plus simple reste de passer par composer. Une fois que vous avez initialisé votre projet composer avec composer init, tapez la commande suivante :

composer require twig/twig

La commande permet de demander à Composer d'installer le package twig/twig.

Configurer un environnement Twig

Maintenant que vous avez le moteur installé, il faut maintenant le configurer pour que votre projet puisse l'utiliser.

Comme pour tout les packages composer, il faut en premier lieu importer l'autoloader :

require_once 'vendor/autoload.php'

Maintenant, nous devons initialiser le loader de Twig. Le loader c'est ce qui permet entre autre d'indiquer à Twig où il doit trouver les templates.

$loader = new \Twig\`Loader\FilesystemLoader(__DIR__.'/templates');

Ici, nous lui avons indiqué que c'est le dossier templates à la racine de notre projet (DIR pour partir du dossier courant et le / pour revenir à la racine).

Ensuite, nous devons définir son environnement. L'environnement permet la configuration du moteur, par exemple l'emplacement du cache si toutefois nous l'activons, ce qui n'est pas le cas ici.

$twig = new \Twig\Environment($loader, [
    'cache" => false
]);

Premier template

L'environnement est totalement prêt. Nous pouvons créer notre premier template. Pour cela, vous allez créer dans le dossier templates un fichier index.html.twig. C'est un fichier HTML classique, mais qui sera agrémenté de différents éléments au fil des besoins.

Pour l'heure ne vous embêtez même pas avec la structure HTML, mettez une simple phrase.

Maintenant, vous devez charger et "rendre" le template. Cela se fait avec la méthode render:

echo $twig->render('index.html.twig', []);

Le premier paramètre est le nom du template dans le dossier, ensuite vous indiquez un tableau de clé => valeur pour les différentes variables. Ici, nous n'en avons pas dans ce premier exemple, donc mettez un tableau vide.

Lancez votre session PHP (php -S localhost:8080 dans votre terminal dans le dossier du projet), et vous constatez que le template s'affiche parfaitement bien.

Amélioration : extends & block

Créée un nouveau fichier HTML : layout.html.twig, dans lequel vous allez mettre une structure HTML 5 classique.

Au début de votre body, ajoutez ceci :

{% block title %}<h1>Le titre</h1>{% endblock %}

Retournez ensuite dans votre template d'index, et ajoutez en haut la ligne :

{% extends 'layout.html.twig' %}

Cette ligne permet d'indiquer à Twig que vous étendez du template layout.html.twig. En exécutant ça, vous aurez une erreur. En effet, aucun contenu ne peut être à l'extérieur d'un bloc. Nous devons donc définir dans le layout, un nouveau bloc, appelons-le body.

Dans le template d'index, mettez maintenant ce texte à l'intérieur du bloc body, comme vous l'avez fait dans le layout pour le titre. Vous pouvez recharger la page, vous verrez notre titre h1 et notre phrase de tout à l'heure. En regardant dans les sources ou via l'outil développeur du navigateur, vous constaterez que nous avons bien notre structure HTML définie dans le layout, et notre phrase définie elle, dans notre index.

Syntaxes

Les syntaxes de Symfony sont plutôt simple :

Variables :
Blocs : {% block nom %} {% endblock %}
Variables globales : {% set variable=valeur %}
Les filtres : {var|filtre}

Documentation

Vous pouvez retrouver la documentation complète du moteur sur son site officiel : https://twig.synfony.com où vous retrouverez toutes les informations importantes pour pouvoir utiliser le moteur avec ou sans Symfony.

Sachez que Symfony ajoute au travers des bundle, des tas de fonctionnalités pour Twig donc la gestion des URL par exemple, l'ajout des assets, etc.

Conclusion

Nous avons vu comment installer, configurer et utiliser Twig. Son utilisation est très simple, c'est sa compréhension qui est difficile.

Le moteur est très puissant, gérant même les boucles, les conditions et encore pleins d'autres fonctionnalités. C'est actuellement le meilleur moteur de template sur le marché. Pleins de sites même en dehors de Symfony, l'utilise, du fait de sa grande puissance et sa facilité d'utilisation.

27 août 2025