Le noyau et son cycle de vie

Une requête HTTP entre, une réponse sort — entre les deux, 8 événements orchestrés par HttpKernel.

Symfony reçoit une requête HTTP et retourne une réponse. Entre les deux, une séquence déterministe de 8 étapes parcourt le noyau. Comprendre ce pipeline, c'est comprendre où intervenir pour modifier le comportement de n'importe quelle application Symfony.

La séquence exacte de handleRaw()

Les 8 événements KernelEvents

Chaque événement a une constante dans KernelEvents et une classe dédiée :

MAIN_REQUEST vs SUB_REQUEST

Chaque requête traitée par HttpKernel::handle() est typée :

Lance la simulation ci-dessous pour voir le pipeline s'exécuter :

kernel.request — le portail d'entrée

Le premier événement du cycle — là où une requête peut être résolue en réponse sans jamais atteindre un contrôleur.

kernel.request est le premier événement dispatché. Il est déclenché avant toute résolution de contrôleur. C'est ici que le routeur fait son travail — et c'est ici qu'on peut court-circuiter tout le pipeline pour retourner une réponse directement.

RequestEvent

use Symfony\Component\HttpKernel\Event\RequestEvent;

public function onKernelRequest(RequestEvent $event): void
{
    $request = $event->getRequest();

    // Court-circuiter le pipeline :
    if ($this->cache->has($request)) {
        $event->setResponse($this->cache->get($request));
        // Le pipeline saute directement à kernel.response
    }
}

Les listeners core (REQUEST)

Les listeners sont exécutés par ordre de priorité décroissante :

$request->attributes — le sac partagé

Après le routage, la requête porte ces attributs dans son ParameterBag :

$request->attributes->get('_controller');   // 'App\Controller\HomeController::index'
$request->attributes->get('_route');        // 'app_home'
$request->attributes->get('_route_params'); // ['id' => '42']
$request->attributes->get('_locale');      // 'fr' (si route paramétrée)

Cas d'usage du court-circuit

kernel.controller — qui prend la main

Une fois le contrôleur trouvé, cet événement permet de l'intercepter, le remplacer ou l'instrumenter.

Après le matching de route, Symfony sait quel contrôleur appeler. Avant de l'appeler, il dispatche kernel.controller pour donner la possibilité de l'intercepter — le changer, le décorer, ou simplement inspecter ses attributs PHP.

ControllerEvent

use Symfony\Component\HttpKernel\Event\ControllerEvent;

public function onKernelController(ControllerEvent $event): void
{
    $controller = $event->getController();

    // Remplacer le contrôleur
    $event->setController(function () use ($controller) {
        return new JsonResponse(['wrapped' => $controller()]);
    });

    // Lire les attributs PHP du contrôleur
    $attributes = $event->getAttributes(MyAttribute::class);
}

ControllerResolverInterface

Avant que kernel.controller soit dispatché, Symfony résout le callable depuis $request->attributes->get('_controller') :

// Formats supportés par ControllerResolver
$request->attributes->set('_controller', 'App\Controller\HomeController::index');
$request->attributes->set('_controller', [new HomeController(), 'index']);
$request->attributes->set('_controller', function(Request $r) { return new Response(); });
$request->attributes->set('_controller', new InvokableController());

Cas d'usage de kernel.controller

Cet événement est adapté pour les préoccupations transversales — ce qu'on applique à plusieurs contrôleurs sans les modifier :

kernel.controller_arguments — les arguments résolus

Avant l'appel du contrôleur, cet événement expose les arguments résolus — on peut les lire, les valider, les transformer.

L'argument resolver transforme la signature du contrôleur en un tableau de valeurs concrètes. L'événement kernel.controller_arguments est dispatché après cette résolution — les arguments sont visibles et modifiables avant l'appel.

ArgumentResolverInterface

// Signature de l'interface
interface ArgumentResolverInterface
{
    public function getArguments(
        Request   $request,
        callable  $controller,
        ?\Reflector $reflector = null,
    ): array;
}

L'implémentation standard (ArgumentResolver) parcourt les paramètres de la signature du contrôleur et demande à chaque ValueResolverInterface de les résoudre :

ControllerArgumentsEvent

use Symfony\Component\HttpKernel\Event\ControllerArgumentsEvent;

public function onKernelControllerArguments(ControllerArgumentsEvent $event): void
{
    // Arguments résolus (tableau positionnel)
    $args = $event->getArguments();

    // Arguments nommés (nom paramètre → valeur)
    $named = $event->getNamedArguments(); // ['id' => 42, 'request' => Request]

    // Modifier un argument
    $args[0] = $this->transformer->transform($args[0]);
    $event->setArguments($args);
}

kernel.view — transformer le résultat

Quand le contrôleur ne retourne pas une Response, cet événement transforme son résultat — c'est le mécanisme derrière les API REST et les moteurs de templates.

Le contrôleur peut retourner n'importe quoi : un tableau, un objet DTO, une chaîne. Si ce n'est pas une Response Symfony, kernel.view est dispatché pour que les listeners transforment ce résultat. C'est le mécanisme central des API REST et des moteurs de templates.

ViewEvent

use Symfony\Component\HttpKernel\Event\ViewEvent;
use Symfony\Component\HttpFoundation\JsonResponse;

public function onKernelView(ViewEvent $event): void
{
    $result = $event->getControllerResult();

    // Sérialiser en JSON si le format demandé est 'json'
    if ($event->getRequest()->getRequestFormat() === 'json') {
        $event->setResponse(new JsonResponse($result));
    }
}

Patterns courants

Sérialisation JSON automatique

// Le contrôleur retourne un tableau ou un objet
public function index(): array
{
    return ['users' => $this->repository->findAll()];
}

// Un listener VIEW le convertit en JsonResponse
public function onKernelView(ViewEvent $event): void
{
    $event->setResponse(
        new JsonResponse($this->serializer->normalize($event->getControllerResult()))
    );
}

Rendu de templates

// Retourner un ViewModel depuis le contrôleur
public function show(int $id): ViewModel
{
    return new ViewModel(template: 'product/show.html.twig', data: $this->find($id));
}

// Un listener VIEW rend le template
public function onKernelView(ViewEvent $event): void
{
    if (!($event->getControllerResult() instanceof ViewModel)) { return; }
    $vm = $event->getControllerResult();
    $event->setResponse(new Response($this->twig->render($vm->template, $vm->data)));
}

kernel.response — la dernière touche

La réponse existe — cet événement permet de l'enrichir, de la modifier, d'ajouter des headers avant l'envoi.

À ce stade, la réponse existe — qu'elle vienne du contrôleur, d'un listener REQUEST, ou d'un listener VIEW. kernel.response permet de la modifier avant l'envoi. C'est l'endroit idéal pour les headers de sécurité, la compression, et les modifications globales de réponse.

ResponseEvent

use Symfony\Component\HttpKernel\Event\ResponseEvent;

public function onKernelResponse(ResponseEvent $event): void
{
    // Appliquer uniquement à la requête principale
    if (!$event->isMainRequest()) { return; }

    $response = $event->getResponse();
    $response->headers->set('X-Frame-Options', 'DENY');
    $response->headers->set('X-Content-Type-Options', 'nosniff');
    $response->headers->set('Strict-Transport-Security', 'max-age=31536000');
}

ResponseListener — le listener core

ResponseListener est le seul listener RESPONSE fourni par défaut dans HttpKernel. Il appelle $response->prepare($request) pour fixer le charset, le protocole HTTP et les headers obligatoires :

// Ce que prepare() fait automatiquement :
// - Content-Type: text/html; charset=UTF-8 si absent
// - Content-Length si la réponse n'est pas chunked
// - Supprime le body pour les requêtes HEAD et les 1xx/204/304
$response->prepare($request);

FINISH_REQUEST — le nettoyage

kernel.finish_request est dispatché après RESPONSE, pour les deux types de requêtes (principale et sub-request). Il sert au nettoyage d'état :

use Symfony\Component\HttpKernel\Event\FinishRequestEvent;

public function onKernelFinishRequest(FinishRequestEvent $event): void
{
    // RouterListener restaure ici le contexte du routeur parent
    // (important pour les sub-requests)
    $this->router->getContext()->fromRequest($event->getRequest());
}

kernel.exception — capturer les erreurs

Une exception non attrapée déclenche cet événement — c'est ici que les pages d'erreur, les logs et les conversions HTTP prennent vie.

Quand une exception n'est pas attrapée par le contrôleur, elle remonte jusqu'au kernel qui dispatche kernel.exception. C'est le filet de sécurité global — chaque application Symfony a au moins un listener ici.

ExceptionEvent

use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\HttpFoundation\JsonResponse;

public function onKernelException(ExceptionEvent $event): void
{
    $e = $event->getThrowable();

    // Remplacer l'exception par une autre
    $event->setThrowable(new BadRequestHttpException('Invalid input', $e));

    // Ou fournir une réponse (avale l'exception)
    if ($event->getRequest()->getRequestFormat() === 'json') {
        $event->setResponse(new JsonResponse([
            'error' => $e->getMessage(),
        ], $this->getStatusCode($e)));
    }
}

HttpExceptionInterface — le mapping automatique

Symfony mappe automatiquement les exceptions implémentant HttpExceptionInterface au code HTTP correspondant. Les exceptions du composant symfony/http-kernel couvrent les cas les plus courants :

ErrorListener et la priorité

ErrorListener de Symfony a la priorité -64 — il s'exécute en dernier. Tes listeners EXCEPTION s'exécutent avant lui, ce qui te permet de traiter l'exception et de fournir une réponse avant qu'ErrorListener rende sa page d'erreur.

allowCustomResponseCode()

// Par défaut, Symfony écrase le code HTTP par celui de l'exception
// Pour conserver un code custom dans ta réponse :
$event->allowCustomResponseCode();
$event->setResponse(new Response('Custom', 418)); // Gardé tel quel

kernel.terminate — après l'envoi

kernel.terminate s'exécute après que la réponse ait été envoyée au client — c'est la zone des tâches coûteuses qui ne doivent pas ralentir la réponse.

kernel.terminate est unique dans le pipeline : il s'exécute après que la réponse ait été envoyée au client. Le navigateur a déjà reçu les données. C'est la zone sans pression de temps — idéale pour les tâches coûteuses.

Comment TERMINATE est déclenché

// Dans public/index.php (généré par Symfony)
$response = $kernel->handle($request);
$response->send();            // ← Le client reçoit la réponse ici
$kernel->terminate($request, $response); // ← TERMINATE dispatché ici

Avec FrankenPHP, le mécanisme est équivalent — la fibre de réponse est résolue avant que terminate() soit appelé.

TerminateEvent

use Symfony\Component\HttpKernel\Event\TerminateEvent;

public function onKernelTerminate(TerminateEvent $event): void
{
    $request  = $event->getRequest();   // Toujours la main request
    $response = $event->getResponse();  // La réponse déjà envoyée

    // Tâches post-réponse sécurisées
    $this->emailQueue->flush();
    $this->analytics->track($request, $response);
    $this->logger->flush();
}

Cas d'usage légitimes

Observe la frise chronologique ci-dessous :

Sub-requests et fragments

Un kernel peut traiter plusieurs requêtes dans une seule exécution — c'est le mécanisme derrière les fragments ESI et les includes de contrôleurs.

Symfony peut traiter plusieurs requêtes dans une seule exécution PHP. Quand tu appelles $kernel->handle($subRequest, HttpKernelInterface::SUB_REQUEST), le noyau crée un pipeline complet pour cette sous-requête — avec ses propres événements, son propre contrôleur, sa propre réponse.

Créer et traiter une sub-request

use Symfony\Component\HttpKernel\HttpKernelInterface;
use Symfony\Component\HttpFoundation\Request;

// Dans un contrôleur ou listener
$subRequest = Request::create('/api/user/42', 'GET');
$response   = $this->httpKernel->handle(
    $subRequest,
    HttpKernelInterface::SUB_REQUEST,
    false, // $catch : laisser remonter les exceptions
);

Ce qui change avec SUB_REQUEST

RequestStack — la pile des requêtes

use Symfony\Component\HttpFoundation\RequestStack;

$stack->getMainRequest();    // Toujours la requête principale
$stack->getCurrentRequest(); // La requête en cours de traitement (main ou sub)
$stack->getParentRequest();  // La requête parente dans les sub-requests imbriquées

Synthèse — guide de choix des événements

8 événements, 1 pipeline — choisir le bon endroit d'interception selon ce qu'on veut faire.

Le pipeline HttpKernel est un système à événements. Chaque événement a un rôle précis dans la séquence. Choisir le bon événement, c'est écrire des listeners qui font exactement ce qu'ils doivent — ni avant, ni après.

Guide de choix

Anti-patterns

Récapitulatif des classes d'événements