Le cache HTTP, vu par Symfony

Le tour complet du cache HTTP côté Symfony : l'API sur la réponse, l'attribut #[Cache], le reverse proxy maison et le découpage ESI.

Cacher une page, ce n'est pas la ranger dans un coin de ton application. C'est inscrire dans les en-têtes de la réponse à quelles conditions on peut la réutiliser, puis laisser un cache — ton navigateur, un reverse proxy, un CDN — s'en servir à ta place. Du coup Symfony ne cache presque rien lui-même : tout son travail est de te laisser exprimer ces conditions clairement, sans bricoler des chaînes d'en-têtes à la main. Et si tu n'as encore ni Varnish ni CDN devant toi, il t'en prête un, écrit en PHP.

Deux modèles, une question

Tout le cache HTTP se ramène à une question : « cette réponse est-elle encore bonne ? ». Il y a deux façons d'y répondre.

Les quatre sections qui suivent montent en abstraction : d'abord l'API bas niveau sur Response, puis l'attribut déclaratif #[Cache], puis le reverse proxy HttpCache qui consomme ces en-têtes, et enfin l'ESI pour cacher une page par morceaux.

L'API de cache de Response

Public ou privé, une durée de vie, une empreinte pour revalider : chaque intention de cache tient en un appel.

La classe Response expose une API fluide pour tous les en-têtes de cache. Tu ne construis jamais la chaîne Cache-Control toi-même : chaque méthode ajoute la bonne directive.

use Symfony\Component\HttpFoundation\Response;

$response = new Response($html);

$response->setPublic();              // Cache-Control: public
$response->setMaxAge(3600);         // max-age=3600 (caches privés)
$response->setSharedMaxAge(7200);   // s-maxage=7200 (caches partagés) + public

return $response;

Les validateurs

$response->setEtag(md5($article->getContent()));
$response->setLastModified($article->getUpdatedAt());
$response->setPublic();

// Court-circuite tout : si la requête correspond, renvoie 304 et vide le corps
if ($response->isNotModified($request)) {
    return $response;   // 304, sans regénérer le contenu
}

$response->setCache([
    'public'        => true,
    'max_age'       => 600,
    's_maxage'      => 3600,
    'must_revalidate' => true,
]);

Le modèle d'expiration

Servir vite, oui — mais une page vue par tout le monde n'est pas une page vue par chacun.

L'expiration est le modèle le plus performant : tant que la réponse est fraîche, le cache la sert seul, sans aucun aller-retour vers ton application. Zéro latence côté serveur.

// Une page d'accueil qui change peu : 1 h en CDN, 5 min en navigateur
public function home(): Response
{
    $response = $this->render('home.html.twig');
    $response->setSharedMaxAge(3600);   // s-maxage=3600
    $response->setMaxAge(300);          // max-age=300

    return $response;
}

Expires ou max-age ?

L'expiration ne convient donc qu'aux réponses identiques pour un groupe de clients et dont on tolère qu'elles soient légèrement périmées. Dès qu'il faut « du frais garanti mais pas régénéré pour rien », c'est la validation qu'il faut.

Le modèle de validation

Régénérer une page coûte cher ? Laisse le serveur répondre « c'est toujours bon » en quelques octets.

La validation répond à l'autre besoin : garder une réponse à jour sans renvoyer son corps si rien n'a changé. Le cache garde sa copie même périmée, et demande au serveur de confirmer.

public function show(Article $article, Request $request): Response
{
    $response = new Response();
    $response->setEtag(md5($article->getContent()));
    $response->setLastModified($article->getUpdatedAt());
    $response->setPublic();

    // Si la requête est conditionnelle et correspond → 304, on s'arrête là
    if ($response->isNotModified($request)) {
        return $response;
    }

    // Sinon, on rend le contenu complet (coûteux)
    return $this->render('article/show.html.twig', ['article' => $article], $response);
}

Observe l'échange conditionnel

Le serveur détient un article en version v3. Choisis l'ETag que le client a en cache, envoie la requête, et regarde s'il reçoit un 304 (léger) ou un 200 (corps complet). Modifie l'article pour changer l'ETag serveur.

L'attribut déclaratif #[Cache]

Les mêmes en-têtes, déclarés d'une ligne au-dessus de l'action — et un 304 servi sans même l'exécuter.

Manipuler Response à la main marche, mais l'attribut #[Cache] (namespace Symfony\Component\HttpKernel\Attribute) rend le cache déclaratif. Un listener applique ses valeurs à la réponse après le contrôleur.

use Symfony\Component\HttpKernel\Attribute\Cache;

class BlogController
{
    // public + s-maxage=3600 + max-age=600, sans toucher à la Response
    #[Cache(public: true, smaxage: 3600, maxage: 600)]
    public function list(): Response
    {
        return $this->render('blog/list.html.twig');
    }
}

Validation sans exécuter le contrôleur

Le plus puissant : etag et lastModified acceptent une expression ou une closure évaluée avant l'action, avec accès aux attributs de requête et aux arguments résolus du contrôleur. Si la réponse est validée (304), le corps du contrôleur n'est jamais exécuté.

// L'ETag est calculé depuis l'entité résolue par le ParamConverter,
// AVANT le corps de la méthode. Un 304 court-circuite tout le rendu.
#[Cache(lastModified: 'article.getUpdatedAt()', etag: 'article.getId() ~ article.getUpdatedAt().getTimestamp()')]
public function show(Article $article): Response
{
    // Non exécuté si le client possède déjà la bonne version
    return $this->render('article/show.html.twig', ['article' => $article]);
}

HttpCache — le reverse proxy de Symfony

Un reverse proxy complet en PHP, qui note dans chaque réponse ce qu'il a fait de ta requête.

Si tu n'as pas de Varnish ou de CDN devant ton app, Symfony fournit son propre reverse proxy écrit en PHP : HttpCache. Il implements HttpKernelInterface, TerminableInterface — c'est un kernel qui enveloppe le tien.

// public/index.php — on emballe le kernel dans le cache
use Symfony\Component\HttpKernel\HttpCache\HttpCache;

$kernel = new Kernel($env, $debug);
// En prod uniquement, et derrière un vrai proxy on s'en passe
if ('prod' === $env) {
    $kernel = new HttpCache($kernel, new Store($cacheDir));
}
$response = $kernel->handle($request);

Le cœur : lookup()

Regarde le proxy travailler

Enchaîne des requêtes et observe la trace X-Symfony-Cache, l'âge de l'entrée, et si le backend est réellement sollicité. Fais expirer le TTL, poste une requête, force un rechargement.

ESI — cacher une page par morceaux

Cacher la coquille d'une page une heure tout en gardant un bloc frais à chaque visite : chaque fragment vit à son rythme.

Le problème de l'expiration : une page entière partage un seul TTL. Or une page mêle souvent du contenu très cacheable (l'article) et du contenu volatil ou personnalisé (le panier, « bonjour Alice »). L'ESI (Edge Side Includes) résout ça en cachant chaque fragment séparément.

# config/packages/framework.yaml
framework:
  http_cache:
    enabled: true
  esi: true

{# Dans un template Twig : délègue le fragment à un contrôleur #}
{# La coquille est très cacheable ; ce bloc a son propre cache #}
{{ render_esi(controller('App\\Controller\\CartController::summary')) }}

Le fragment décide de son cache

public function summary(): Response
{
    $response = $this->render('cart/_summary.html.twig');
    $response->setSharedMaxAge(10);   // ce bloc : 10 s seulement

    return $response;
}

Synthèse — choisir sa stratégie

Le mode d'emploi : quoi cacher, comment le déclarer, et avec quel outil selon ton contexte.

Le cache HTTP dans Symfony, c'est un empilement de choix cohérents. Voici comment les trancher.