Retourner des objets `Response` (HTML, JSON)

L'objet `Response` : la finalité de chaque action de contrôleur

Chaque action de contrôleur dans Symfony a une responsabilité finale : retourner un objet qui implémente l'interface Symfony\Component\HttpFoundation\ResponseInterface. Le plus souvent, il s'agira d'une instance de la classe Symfony\Component\HttpFoundation\Response ou de l'une de ses sous-classes spécialisées (comme JsonResponse, RedirectResponse, etc.). Cet objet Response encapsule tout ce que le serveur doit renvoyer au client (navigateur, application mobile, etc.) : le contenu, le code de statut HTTP, et les en-têtes HTTP.

Comprendre comment construire et retourner ces objets Response est fondamental. Que vous souhaitiez afficher une page HTML générée par Twig, fournir des données au format JSON pour une API, rediriger l'utilisateur vers une autre page, ou même envoyer un fichier à télécharger, tout passe par la création et le retour d'un objet Response approprié.

Ce chapitre se concentrera sur les deux types de réponses les plus courants : les réponses HTML, souvent générées à l'aide du moteur de templates Twig, et les réponses JSON, essentielles pour la création d'API RESTful ou la communication avec des applications JavaScript front-end.

Retourner une réponse HTML avec `Response` et Twig

Pour la plupart des applications web traditionnelles, la majorité des actions de contrôleur retourneront du contenu HTML. Symfony facilite grandement cette tâche, notamment lorsque vous héritez de AbstractController, qui fournit des méthodes raccourcis pratiques.

La méthode la plus courante pour retourner une réponse HTML est render(). Cette méthode, fournie par AbstractController, prend en charge le rendu d'un template Twig et encapsule le HTML résultant dans un objet Response.

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class PageController extends AbstractController
{
    #[Route('/accueil', name: 'app_accueil')]
    public function accueil(): Response
    {
        $nomUtilisateur = 'Invité'; // Ou récupéré depuis la session, base de données, etc.
        $derniersArticles = [
            ['titre' => 'Symfony 6.3 est sorti !', 'date' => '2023-05-25'],
            ['titre' => 'Maîtriser Twig', 'date' => '2023-05-20'],
        ];

        // Rend le template 'page/accueil.html.twig'
        // et lui passe les variables 'nom' et 'articles'
        return $this->render('page/accueil.html.twig', [
            'nom' => $nomUtilisateur,
            'articles' => $derniersArticles,
        ]);
    }

    #[Route('/contact', name: 'app_contact')]
    public function contact(): Response
    {
        // Si vous n'avez pas besoin de passer de variables au template :
        return $this->render('page/contact.html.twig');
    }
}

Dans cet exemple, $this->render('page/accueil.html.twig', [...]) fait plusieurs choses :

1. Il localise le fichier de template templates/page/accueil.html.twig.
2. Il rend ce template en utilisant le moteur Twig, en mettant à disposition les variables nom et articles dans le contexte du template.
3. Il prend le HTML généré par Twig et le place dans le corps d'un nouvel objet Response.
4. Cet objet Response est ensuite retourné. Par défaut, le code de statut sera 200 OK et le type de contenu (Content-Type) sera text/html.

Si vous avez besoin de plus de contrôle sur l'objet Response (par exemple, pour définir un code de statut spécifique ou des en-têtes personnalisés), vous pouvez instancier l'objet Response manuellement après avoir obtenu le contenu HTML de Twig (en utilisant le service Twig directement) ou en passant des arguments supplémentaires à la méthode render() si elle le supporte dans votre version ou via des méthodes utilitaires.

Une autre méthode utile est renderBlock(), qui permet de rendre un bloc spécifique d'un template Twig, ce qui peut être utile pour des réponses partielles (par exemple, pour des requêtes AJAX qui ne mettent à jour qu'une partie de la page).

Construire et retourner des réponses JSON avec `JsonResponse`

Lorsque vous construisez une API ou que vous avez besoin de communiquer avec du code JavaScript côté client, le format JSON (JavaScript Object Notation) est très largement utilisé. Symfony fournit une classe de réponse dédiée, Symfony\Component\HttpFoundation\JsonResponse, pour faciliter la création de réponses JSON.

JsonResponse prend en argument les données que vous souhaitez envoyer (généralement un tableau PHP ou un objet qui peut être sérialisé en JSON), un code de statut HTTP (par défaut 200), et un tableau d'en-têtes (par défaut, il définit automatiquement Content-Type à application/json).

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class ApiController extends AbstractController
{
    #[Route('/api/produits', name: 'api_produits_list', methods: ['GET'])]
    public function listProduits(): JsonResponse
    {
        $produits = [
            ['id' => 1, 'nom' => 'Ordinateur portable', 'prix' => 1200.00],
            ['id' => 2, 'nom' => 'Souris sans fil', 'prix' => 25.00],
            ['id' => 3, 'nom' => 'Clavier mécanique', 'prix' => 75.00],
        ];

        return new JsonResponse($produits);
        // Alternative plus concise si vous héritez de AbstractController:
        // return $this->json($produits);
    }

    #[Route('/api/produit/{id}', name: 'api_produit_show', methods: ['GET'])]
    public function showProduit(int $id): JsonResponse
    {
        // Simuler la récupération d'un produit
        $produit = null;
        if ($id === 1) {
            $produit = ['id' => 1, 'nom' => 'Ordinateur portable', 'prix' => 1200.00];
        }

        if (!$produit) {
            return $this->json(['message' => 'Produit non trouvé'], Response::HTTP_NOT_FOUND); // Code 404
        }

        return $this->json($produit); // Code 200 OK par défaut
    }

    #[Route('/api/produit/creer', name: 'api_produit_create', methods: ['POST'])]
    public function createProduit(Request $request): JsonResponse
    {
        // En situation réelle, vous utiliseriez le Serializer de Symfony ou des DTOs
        $donnees = $request->toArray(); // Pour les requêtes avec Content-Type: application/json
        // Ou $request->request->all(); pour les données de formulaire x-www-form-urlencoded

        if (empty($donnees['nom']) || empty($donnees['prix'])) {
            return $this->json(['message' => 'Données manquantes'], Response::HTTP_BAD_REQUEST); // Code 400
        }

        // Simuler la création
        $nouveauProduit = [
            'id' => rand(100, 200), 
            'nom' => $donnees['nom'], 
            'prix' => (float)$donnees['prix']
        ];

        // Généralement, pour une création réussie, on retourne un code 201 Created
        // et potentiellement l'entité créée ou un lien vers celle-ci.
        return $this->json($nouveauProduit, Response::HTTP_CREATED);
    }
}

AbstractController fournit également une méthode raccourci json(), qui est encore plus concise : return $this->json($data, $status, $headers);. Elle s'occupe d'instancier JsonResponse pour vous.

L'utilisation de JsonResponse (ou du raccourci $this->json()) garantit que vos données sont correctement encodées en JSON et que l'en-tête Content-Type: application/json est défini, ce qui est crucial pour que les clients API interprètent correctement la réponse.

Autres types de réponses et bonnes pratiques

Outre les réponses HTML et JSON, Symfony propose d'autres classes de Response pour des cas d'usage spécifiques :

• Symfony\Component\HttpFoundation\RedirectResponse : Pour effectuer des redirections HTTP (codes 301, 302, etc.). Typiquement utilisé après la soumission réussie d'un formulaire. AbstractController fournit le raccourci $this->redirectToRoute('nom_de_la_route', ['param' => 'valeur']) ou $this->redirect('url_absolue_ou_relative').
• Symfony\Component\HttpFoundation\StreamedResponse : Pour envoyer de grandes quantités de données en streaming, sans avoir à tout charger en mémoire d'un coup. Utile pour générer de gros fichiers CSV, par exemple.
• Symfony\Component\HttpFoundation\BinaryFileResponse : Pour envoyer un fichier existant sur le serveur au client (par exemple, pour un téléchargement d'image, PDF, etc.). Il gère correctement les en-têtes comme Content-Disposition.

Bonnes pratiques générales pour les réponses :

• Codes de statut HTTP : Utilisez toujours les codes de statut HTTP appropriés. Ils communiquent l'issue de la requête au client (200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error, etc.).
• En-têtes HTTP : N'hésitez pas à manipuler les en-têtes si nécessaire (par exemple, pour le caching avec Cache-Control, ETag, ou des en-têtes de sécurité). L'objet Response a une propriété $headers (un objet HeaderBag) pour cela : $response->headers->set('X-Custom-Header', 'Valeur');.
• Contenu négocié : Pour des API plus avancées, vous pourriez avoir besoin de supporter différents formats de réponse (JSON, XML) en fonction de l'en-tête Accept de la requête. Le composant Serializer de Symfony, souvent utilisé avec FOSRestBundle ou API Platform, peut aider à gérer cela.
• Sécurité : Assurez-vous que tout contenu dynamique intégré dans vos réponses HTML est correctement échappé (Twig le fait automatiquement pour les variables affichées) pour prévenir les attaques XSS. Pour les réponses JSON, veillez à ne pas exposer de données sensibles.

Maîtriser la création et la manipulation des objets Response est une compétence clé pour tout développeur Symfony, car c'est l'interface directe entre votre application et le monde extérieur.