TD2 – Réponses HTTP Réponses HTTP, Moteur de template Twig

L’objectif de ce TD est d’améliorer nos réponses HTTP sur plusieurs points :

• ajouter un code de réponse HTTP pour indiquer plus clairement l’état du serveur. Ceci est indispensable dans l’optique du développement d’une API REST, qui est l’objectif principal de ces 3 premiers TPs ;
• pouvoir répondre du JSON, ce qui est aussi un des fondamentaux des API REST ;
• utiliser un template engine (Twig), c’est-à-dire à un langage spécifique pour la création de vues.

La classe Response

Nous allons utiliser la classe Response du composant HttpFoundation de Symfony. Selon la documentation de Symfony, un objet Response contient toute l’information qui doit être renvoyée au client HTTP : des en-têtes, un code de réponse et un corps de réponse. Voici un exemple d’appel au constructeur (tous les arguments sont optionnels) :

use Symfony\Component\HttpFoundation\Response;

$response = new Response(
    'Corps de la réponse : page Web ou JSON',
    Response::HTTP_OK, // Code 200 OK
    ['content-type' => 'text/html'] // En-tête pour indiquer une réponse HTML
);

L’envoi de la réponse au client HTTP se fait tout simplement

$response->send();

Des actions qui retournent des Response

Nous souhaitons modifier nos actions pour qu’elles retournent toutes une instance de la classe Response. Ceci nous permettra par la suite d’utiliser toutes les possibilités des réponses HTTP, notamment une meilleure redirection dans l’exercice 2, ou des codes de réponse HTTP personnalisés dans l’exercice 4.

Pour que ControleurGenerique::afficherVue() renvoie une Response, il faut que les vues renvoient une chaîne de caractères plutôt que d’écrire directement la réponse HTTP. Pour ceci, nous allons temporairement rediriger la sortie standard vers un fichier tampon de sortie (output buffer ou ‘ob’) avec la commande

ob_start();

Tant qu’elle est enclenchée, aucune donnée, hormis les en-têtes, n’est envoyée au navigateur du client HTTP. Quand l’exécution des vues est fini, nous récupérons le contenu de ce fichier tampon puis l’effaçons avec

$corpsReponse = ob_get_clean();

Il ne reste plus qu’à créer un objet Response à partir de ce corps de réponse.

Des redirections plus propres

Le composant HttpFoundation de Symfony fournit aussi la classe RedirectResponse qui hérite de Response. Cette classe permet de bénéficier automatiquement d’une redirection plus professionnelle.

En effet, si vous ouvrez son code source vendor/symfony/http-foundation/Response.php dans votre IDE, vous verrez qu’en plus de mettre en place un en-tête Location : comme nous le faisions, elle écrit la balise suivante (voir la méthode setTargetUrl())

<meta http-equiv="refresh" content="0;url=url_de_redirection" />

Ceci permet une meilleure compatibilité avec différents navigateurs. En effet, l’en-tête Location : n’est pas complètement supportée (59% des navigateurs) (cliquez sur le bouton Usage relative pour améliorer l’affichage du site caniuse.com). Au contraire, la balise <meta http-equiv="refresh" /> est supportée par 97% des navigateurs actuellement.

De plus, RedirectResponse associe automatiquement le code de réponse 302 Found qui indique une redirection temporaire. Profitons-en pour remarquer que la réécriture d’URL indiquée dans le fichier de configuration .htaccess de Apache utilisait un code 301 Moved Permanently de redirection permanente. Ceci était utilisé par exemple pour rediriger la requête web/controleurFrontal.php/connexion vers web/connexion. Une redirection permanente permet au navigateur d’optimiser la requête : le navigateur garde en cache la redirection et l’effectue lui-même sans envoyer de requête au serveur.

Un objet de type RedirectResponse peut être instancié ainsi :

use Symfony\Component\HttpFoundation\RedirectResponse;

//$url correspondant à l'URL vers laquelle on souhaite rediriger l'utilisateur
$response = new RedirectResponse($url);

Utilisation des codes de réponses pour les erreurs

Les méthodes UrlMatcher::match(), ControllerResolver::getController() et ArgumentResolver::getArguments() utilisés dans RouteurURL peuvent lever des exceptions. Nous allons les traiter en envoyant une réponse HTTP adéquate, en faisant particulièrement attention au code de réponse.

Nous allons maintenant traiter ces exceptions avec une réponse HTTP adaptée. Les codes de réponse qui signalent une erreur de l’utilisateur sont en 4xx. Voici quelques codes de réponse HTTP utiles :

• 400 Bad Request (attribut HTTP_BAD_REQUEST de la classe Response)
  Cette réponse indique que le serveur n’a pas pu comprendre la requête à cause d’une syntaxe invalide.

• 401 Unauthorized (attribut HTTP_UNAUTHORIZED)
  Bien que le standard HTTP indique « non autorisé », la sémantique de cette réponse correspond à « non authentifié » : le client doit s’authentifier afin d’obtenir la réponse demandée.

• 403 Forbidden (attribut HTTP_FORBIDDEN)
  Le client n’a pas les droits d’accès au contenu, donc le serveur refuse de donner la véritable réponse.

• 404 Not Found (attribut HTTP_NOT_FOUND)
  Le serveur n’a pas trouvé la ressource demandée. Ce code de réponse est principalement connu pour son apparition fréquente sur le web.

• 405 Method Not Allowed (attribut HTTP_METHOD_NOT_ALLOWED)
  La méthode de la requête est connue du serveur, mais n’est pas prise en charge pour la ressource cible. Par exemple, une API peut ne pas autoriser l’utilisation du verbe DELETE pour supprimer une ressource.

• 409 Conflict (attribut HTTP_CONFLICT)
  Quand la requête entraîne un conflit entre les ressources. L’exemple typique est celle de deux utilisateurs ayant la même adresse mail, alors que ce champ est unique dans la BDD.

Un langage de gabarit : Twig

Le principe des langages de gabarit (template engines) est de fournir un langage adapté aux vues. Voyons les contraintes d’un bon langage de gabarits :

• Concision : Au lieu du code PHP, <?php echo $var ?>, Twig propose un code concis

  {{ var }}
  

• Syntaxe adaptée aux besoins courants : Par exemple, disons que vous voulez itérer sur un tableau et afficher un texte par défaut lorsque le tableau est vide.

   {% for item in items %}
   - {{ item }}
   {% else %}
   Pas d'items trouvés.
   {% endfor %}
  

• Réutilisation : L’héritage de gabarit permet de reprendre une mise en page existante (comme vueGenerale.php) en spécifiant des parties (le titre, le corps de la page, …)

• Sécurité : La sécurité est activée par défaut, en particulier l’échappement des caractères spéciaux du HTML. Ceci vise à protéger les non-développeurs des menaces web courantes telles que XSS ou CSRF dont ils ne sont pas nécessairement conscients.

• Rapide : Twig compile les gabarits en code PHP simple, ce qui permet leur évaluation à un surcoût minimum.

• Favoriser la séparation des préoccupations (separation of concerns) :

  Dans les grands projets Web, des développeurs (web developer) travaillent sur le code (les contrôleurs et le modèle) et les concepteurs (web designer) sur l’aspect visuel.

  Un langage de gabarit permet d’écrire des gabarits qui respectent cette séparation des préoccupations. Un langage de gabarit doit trouver un bon équilibre entre offrir suffisamment de fonctionnalités pour faciliter l’implémentation de la logique de présentation, et limiter les fonctionnalités avancées pour éviter l’apparition de logique métier dans les gabarits. On fournit aux vues la liste des variables qu’elles peuvent utiliser. Idéalement, la vue n’accède aux variables qu’en lecture, ce qui évite de modifier l’état du système.

Sources :

• Blog de Fabien Potentier (fondateur de Symfony) sur la naissance de Twig
• Documentation officielle de Twig

Initialisation de Twig

Premier gabarit Twig, héritage de gabarit

Nous allons créer notre premier gabarit Twig qui correspond à formulaireConnexion.php. Pour que cette vue s’insère sans une mise-en-page générale (anciennement vueGenerale.php), nous allons utiliser le mécanisme d’héritage de gabarit.

Nous allons remplacer src/vue/vueGenerale.php par le fichier src/vue/base.html.twig suivant :

<!DOCTYPE html>
<html lang="fr">
<head>
    <title>{% block page_title %}The Feed{% endblock %}</title>
    <meta charset="utf-8">
    <link rel="stylesheet" type="text/css" href="{# lien vers le CSS #}">
</head>
<body>
<header>
    <div id="titre" class="center">
        <a href="{# lien #}"><span>The Feed</span></a>
        <nav>
            <a href="{# lien #}">Accueil</a>
            {# si l'utilisateur est connecte #}
            <a href="{# lien #}">Ma page</a>
            <a href="{# lien #}">Déconnexion</a>
            {# sinon #}
            <a href="{# lien #}">Inscription</a>
            <a href="{# lien #}">Connexion</a>
            {# fin si #}
        </nav>
    </div>
</header>
<div id="flashes-container">
    {# boucle sur les types de messages flash #}
        {# boucle sur les messages flash de ce type #}
            <span class="flashes flashes-{# type du message #}">{# message flash #}</span>
        {# fin boucle #}
    {# fin boucle #}
</div>
{% block page_content %}{% endblock %}
</body>
</html>

Remarque : c’est normal que plusieurs aspects de la page soient cassés (menu, lien, CSS). Nous implémenterons toutes les fonctionnalités entre commentaire Twig {# #} dans la suite.

Les balises Twig {% block page_title %}{% endblock %} définissent un bloc, c’est-à-dire une partie de la page qui pourra être remplacée dans une autre vue. Nous allons justement reprendre cette vue et remplacer le titre et le contenu de la page dans une nouvelle vue src/vue/utilisateur/connexion.html.twig :

{% extends "base.html.twig" %}

{% block page_title %}Connexion{% endblock %}

{% block page_content %}
    <main>
        <form action="{# lien vers la page de traitement #}" id="form-access" class="center" method="post">
            <fieldset>
                <legend>Connexion</legend>
                <div class="access-container">
                    <label for="login">Login</label>
                    <input id="login" type="text" name="login" required/>
                </div>
                <div class="access-container">
                    <label for="password">Mot de passe</label>
                    <input id="password" type="password" name="mot-de-passe" required/>
                </div>
                <input id="access-submit" type="submit" value="Se connecter">
            </fieldset>
        </form>
    </main>
{% endblock %}

La balise Twig {% extends %} permet d’hériter d’un gabarit. On peut alors remplacer le contenu d’un bloc en le redéfinissant.

Syntaxe de base de Twig

• L’instruction {{ donnee }} permet d’afficher une donnée. Elle sera automatiquement échappée pour le HTML, c-à-d qu’il appelle automatiquement htmlspecialchars pour vous.

  On peut accéder à une méthode d’un objet avec {{ donnee.methode() }}, et à un attribut avec {{ donnee.attribut }}. Twig essayera d’abord de trouver un attribut public $donnes->attribut, puis appellera sinon $donnes->getAttribut(), $donnes->isAttribut() et $donnes->hasAttribut() (cf. documentation de Twig).

• Les variables accessibles dans Twig sont celles qui ont été données en paramètres de $twig->render() dans la méthode ControleurGenerique::afficherTwig(). Par exemple, si le fichier exemple.html.twig contient {{ variableTwig }}, alors

  $twig->render("exemple.html.twig", ["variableTwig" => "Web4Ever🕸"]);
  

  affichera Web4Ever🕸.

• On peut définir des variables locales :

    {% set exemple = "coucou" %}
    <p>{{ exemple }}</p>
  

• Il est possible de concaténer des chaînes de caractères avec le symbole ~ :

    <p>{{donnee~'coucou'}}</p>
  

• La structure conditionnelle if permet de ne générer une partie du document que si une condition est remplie :

  {% if test %}
     Code HTML....
  {% endif %}
  

• Il est bien sûr possible de construire des conditions complexes avec les opérateurs : not, and, or, ==, <, >, <=, >=, etc… par exemple :

  {% if test and (not (user.name == 'Smith') or user.age <= 20) %}
  Code HTML....
  {% endif %}
  

• La structure répétitive for permet de parcourir une structure itérative (par exemple, un tableau) :

  {% for data in tab %}
     <p>{{ data }}</p>
  {% endfor %}
  

• Si c’est un tableau associatif et qu’on veut accéder aux clés et aux valeurs en même temps :

  <ul>
    {% for key, value in tab %}
    <li>{{ key }} = {{ value }}</li>
    {% endfor %}
  </ul>
  

• On peut aussi faire une boucle variant entre deux bornes :

  {% for i in 0..10 %}
    <p>{{ i }}ème valeur</p>
  {% endfor %}
  

• Une syntaxe {% else %} permet de traiter le cas particulier d’un tableau vide :

  {% for data in tab %}
     <p>{{ data }}</p>
  {% else %}
  Pas de données dans le tableau
  {% endfor %}
  

Les filtres de Twig

Les variables peuvent être modifiées par des filtres. Les filtres sont séparés de la variable par un symbole de pipe |. Plusieurs filtres peuvent être enchaînés, auquel cas la sortie d’un filtre est appliquée au suivant. Par exemple,

{{ donnee|lower|truncate(20) }} {# minuscule puis tronque à 20 caractères #}

Le filtre escape (ou son raccourci e) permet d’appliquer un échappement personnalisé :

{{ user.username|e('js') }} {# échappement dans un contexte JavaScript #}
{{ user.username|e('css') }} {# contexte CSS #}
{{ user.username|e('url') }} {# contexte bout d'URL, par ex. query string #}
{{ user.username|e('html_attr') }} {# contexte attribut d'une balise HTML #}

Le filtre date formate une date avec un format personnalisé. La documentation liste les filtres de Twig fournis par défaut.

Étendre la syntaxe de Twig

Twig peut être étendu de nombreuses façons : vous pouvez ajouter des filtres, des fonctions, des variables globales. Ou, plus rarement, des balises, des tests et des opérateurs.

À la manière de Symfony, nous allons rajouter des fonctions à Twig pour gérer les liens liés aux routes ou aux assets.

La syntaxe pour rajouter une fonction est

use Twig\TwigFunction;

$twig->addFunction(new TwigFunction("route", $callable));

où $callable est une variable au format callable (comme avec call_user_func() au TD1). Pour exemple, pour donner la méthode d’un objet, on peut utiliser la syntaxe

$callable = [$objet, "nomMethode"];

ou la syntaxe callable de première classe apparue avec PHP 8.1

$callable = $objet->nomMethode(...); // Les ... font parti de la syntaxe

La fonction est alors disponible dans Twig, par exemple comme ceci :

{{ route("afficherListe") }}

Il ne nous reste plus qu’à restaurer les utilisateurs connectés et les messages Flash. Pour ceci, nous allons rajouter des variables globales à Twig :

$twig->addGlobal('nomVariableTwig', $variablePHP);

Pour rajouter les messages Flash, nous pourrions être tentés de faire

$twig->addGlobal('messagesFlash', MessageFlash::lireTousMessages());

dans RouteurURL. Cependant, nous aimerions que les messages Flash soient lus au moment de l’évaluation des vues, et non pas au début du script PHP. Du coup, nous proposons de stocker une instance de MessageFlash :

$twig->addGlobal('messagesFlash', new MessageFlash());

et d’appeler la méthode lireMessages() dans la vue Twig avec messagesFlash.lireMessages().

Bonus : pour le projet ?

Approche par composants

Il est facile d’adopter une approche par composant dans les vues, c’est-à-dire de définir des bouts de vues facilement réutilisables.

Nous aimerions rétablir le fonctionnement du TP précédent où on disposait :

• D’une vue pour afficher l’ensemble des publications et en ajouter (la page d’accueil).
• D’une vue pour afficher la page personnelle d’un utilisateur, dont le titre de la page correspondait au login de l’utilisateur et sur lequel n’apparaissait pas le formulaire d’ajout de publications.

Actuellement, nous utilisons la même vue feed.html.twig pour gérer les deux cas, ce qui fait que la page personnelle d’un utilisateur :

• N’a pas de titre contenant le login de l’utilisateur.
• Possède le formulaire d’ajout de publication.

Dans un premier temps, on pourrait tenter d’étendre la page feed.html.twig pour créer une vue spécialisée pour la page personnelle et en redéfinir le titre avec le bloc associé. Mais ce n’est pas vraiment une bonne approche, car la vue feed.html.twig contient “en plus” le formulaire d’ajout. On pourrait définir un bloc autour de ce formulaire et faire en sorte qu’il soit vide dans la vue spécialisée, mais cela semble une mauvaise conception, notamment si la page feed.html.twig est encore amenée à évoluer.

Il ne parait pas non plus très adéquat de créer une vue plus générale dont hériterait les deux (même si cela serait déjà un peu mieux).

Cependant, il est hors de question de dupliquer le code correspondant à l’affichage de la liste de publications dans les deux vues. En fait, les seules choses qu’ont réellement en commun les deux vues, c’est ce bout de code. Twig va nous permettre de résoudre efficacement cette situation, grâce à l’inclusion de template.

Avec Twig, il est possible d’inclure le code d’un template dans un autre template. Ce mécanisme est différent de l’extension de template que nous utilisions jusqu’ici et qui consistait à “hériter” du code d’un template et redéfinir certaines parties. L’inclusion de template se rapproche plus d’une fonction qu’on peut réutiliser dans plusieurs autres templates. De plus, un peu comme une fonction, on peut passer des paramètres aux templates inclus.

L’instruction pour inclure un template est la suivante :

{{ include(cheminTemplate, {'param1' : ..., 'param2' : ... }) }}

• cheminTemplate : correspond au chemin du template à partir de la racine : le dossier templates (comme on étend un template, ou qu’on l’utilise dans un contrôleur…)

• Le second paramètre est optionnel et permet de passer des paramètres utilisables par le template inclus.

Imaginons par exemple qu’on définisse le template livres/livres.html.twig suivant, permettant de générer le code HTML pour présenter les détails d’un livre :

<h2>Livre : {{ livre.tire }}</h2>
<p>Année : {{ livre.anneePublication }}<p>
<p>Auteur : {{ livre.auteur }}<p>

On peut alors inclure ce template dans un autre template à tout moment, en passant le livre en paramètre. Par exemple, imaginons qu’on définisse un template best_seller.html.twig qui liste les trois livres les plus vendus cette année. On possède un objet “top” contenant quatre propriétés : annee, livre1, livre2 et livre3.

<h1>Best-sellers de {{ top.annee }} :<h1>
<p>Top 1 :</p>
{{ include('livres/livres.html.twig', {'livre' : top.livre1}) }}
<p>Top 2 :</p>
{{ include('livres/livres.html.twig', {'livre' : top.livre2}) }}
<p>Top 3 :</p>
{{ include('livres/livres.html.twig', {'livre' : top.livre3}) }}

Bien sûr, la modélisation pour ce problème n’est pas la meilleure, et même dans le template, nous aurions pu utiliser une boucle, mais cela permet d’illustrer efficacement la fonctionnalité d’inclusion.

Tout cela va trouver son intérêt si le template est réutilisé dans plusieurs pages différentes. Par exemple, on pourrait réutiliser dans la page illustrant les détails d’un livre. Ou alors, si on utilise un formulaire à plusieurs endroits du site, on peut le placer dans un template et l’inclure là où il y a besoin.

Il est intéressant de noter que le template inclus ait accès à toutes les variables déjà accessibles (ou définies) par le template qui l’appelle.

Il est d’ailleurs tout à fait possible que ce template “étende” un autre template, comme nous l’avons fait pour la plupart des templates que nous avons créé jusqu’à présent. Finalement, on peut voir l’extension de templates comme de l’héritage (et la redéfinition de blocks comme de la réécriture de méthodes) et l’utilisation d’un template à l’intérieur d’un autre template comme un appel de fonction, par exemple.

On pourrait aller plus loin et avoir un template liste_publications.html.twig si l’affichage d’une liste de publications était plus complexe qu’une simple boucle et se répétait sur plusieurs pages. Ce template utiliserait alors notre nouveau template publication.html.twig.

Ressources supplémentaires

1. La compilation des vues Twig peut être précalculée et stockée dans un cache. Utilisez la configuration auto_reload lors du développement pour mettre à jour le cache à chaque changement de code source des vues.
2. La fonction dump facilite le débogage en affichant un résultat similaire à var_dump().