Skip to content

7. O ciclo de vida de uma requisição

Entre a chegada de uma requisição e o envio de sua resposta, o kernel do [Symfony] (a classe [HttpKernel]) executa várias etapas e, em cada uma delas, publica um evento ao qual a aplicação pode reagir por meio de um listener. Já encontramos vários deles: os listeners de [kernel.request] e [kernel.response] (exemplos 03, 16, 22), de [kernel.exception] (exemplos 08 e 12) e os argument resolvers (exemplo 12). Este capítulo reúne todos eles em um único exemplo, que exibe uma mensagem no console a cada etapa para que você observe a ordem:

  • 1 e 2. [kernel.request]: a requisição acabou de chegar. Todos os listeners desse evento são chamados, em ordem decrescente de prioridade. Um deles é o listener de roteamento do [Symfony] (o listener [RouterListener], com prioridade 32): ele procura a rota que corresponde à URL e ao método e armazena seu nome e seus parâmetros nos atributos da requisição; se nenhuma corresponder, lança uma exceção [NotFoundHttpException] (404). Um listener com prioridade superior a 32 (1) é executado antes do roteamento e não conhece a rota; um listener com prioridade inferior (2) a conhece. Um listener de [kernel.request] também pode fornecer ele próprio a resposta ([$event->setResponse(...)]): nesse caso, a ação não é chamada;
  • 3. [kernel.controller]: a ação foi selecionada, mas ainda não invocada. Um listener pode examinar a ação (seus atributos, como os do [PHP], por exemplo) ou substituí-la;
  • 4. Os argument resolvers calculam os parâmetros da ação (Exemplo 12), e então o evento [kernel.controller_arguments] é publicado;
  • 5. A ação e a view que ela gera. (Se a ação não devolver um objeto [Response], um evento adicional, [kernel.view], permite que um listener construa a resposta a partir do que a ação devolveu.);
  • 6 e 7. [kernel.response]: a resposta está pronta. Cada listener pode modificá-la (adicionar um cabeçalho, um cookie), em ordem decrescente de prioridade;
  • 8. [kernel.terminate], publicado depois que a resposta é enviada ao navegador (é a chamada [$kernel->terminate(...)] do arquivo [public/index.php], exemplo 01). Os listeners não podem mais alterar a resposta: servem para tarefas que podem esperar (gravar um log, enviar um e-mail etc.), sem fazer o usuário esperar;
  • x. [kernel.exception]: uma exceção lançada em qualquer etapa (por um listener, um resolver, a ação ou a view) interrompe o processamento; ela é tratada pelos listeners desse evento. O primeiro listener que fornecer uma resposta encerra a busca. Essa resposta passa então por [kernel.response], como uma resposta comum. Se nenhum listener da aplicação fornecer uma, o [Symfony] gera a página de erro: detalhada no modo de depuração, mínima nos demais casos.

Isso equivale aos filtros do [Java] e aos interceptors do [Spring MVC], aos filtros de ação do [ASP.NET Core MVC], às funções [before_request] / [after_request] do [Flask] e ao middleware do [Laravel]. A diferença entre eles está em sua estrutura: um componente de middleware envolve o restante do processamento (ele chama [$next] e, assim, vê a requisição antes e a resposta depois, dentro do mesmo código), ao passo que um listener reage a um evento; para agir antes e depois da ação, é preciso escutar dois eventos. Por outro lado, um listener pode intervir em uma etapa específica (depois do roteamento, depois da seleção da ação etc.), e a ordem dos listeners é determinada por um número: a prioridade.

7.1. Exemplo 24: As etapas do processamento de uma requisição

24-lifecycle/
├── src/
│   ├── Controller/
│   │   └── CalcController.php
│   ├── EventListener/
│   │   ├── Block.php
│   │   ├── Timing.php
│   │   ├── Timed.php
│   │   ├── Logger.php
│   │   └── ErrorPage.php
│   └── Binding/
│       └── IntegerResolver.php
├── templates/
│   ├── calc/
│   │   └── result.html.twig
│   ├── error.html.twig
│   └── layout.html.twig
└── ...

A aplicação tem apenas uma ação, que calcula o quadrado de um inteiro: [/square/7]. Dependendo da URL, ela tem sucesso ou falha de várias maneiras. As mensagens são escritas no console do servidor pela função [error_log] do [PHP], que o servidor de desenvolvimento ([php -S]) exibe.

7.1.1. Antes e depois de tudo: src/EventListener/Logger.php

<?php
// src/EventListener/Logger.php: um listener de DOIS eventos. Ele vê cada requisição
// passar ANTES do resto da aplicação (até mesmo do roteamento) e a resposta
// DEPOIS de todo o resto

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\Event\ResponseEvent;
use Symfony\Component\HttpKernel\KernelEvents;

class Logger
{
    // priority 100: antes do roteamento do Symfony (priority 32)
    #[AsEventListener(event: KernelEvents::REQUEST, priority: 100)]
    public function before(RequestEvent $event): void
    {
        $request = $event->getRequest();
        // error_log: uma mensagem no console do servidor de desenvolvimento
        error_log('--- '.$request->getMethod().' '.$request->getRequestUri());
        error_log('1. Logger, kernel.request (before the routing)');
    }

    // priority -100: depois dos outros listeners de kernel.response
    #[AsEventListener(event: KernelEvents::RESPONSE, priority: -100)]
    public function after(ResponseEvent $event): void
    {
        error_log('7. Logger, kernel.response (code '.$event->getResponse()->getStatusCode().')');
    }
}

Uma única classe pode escutar vários eventos: o atributo [#[AsEventListener]] é então aplicado a cada um dos métodos pertinentes.

  • linhas 16–23: mensagem nº 1, com a requisição ([getRequestUri()]: o caminho e os parâmetros). A prioridade 100 coloca o listener antes do roteamento: nada aconteceu ainda no [Symfony];
  • Linhas 26–30: mensagem nº 7, depois que tudo o mais foi concluído. Uma prioridade de -100 coloca o listener depois dos da aplicação e dos do [Symfony] (a maioria dos quais tem prioridade entre -10 e 10). [getStatusCode()] é o código da resposta.

Um listener assim não conhece a rota escolhida, já que o roteamento ainda não ocorreu. Ele serve para processamentos que se aplicam a todas as requisições: registro de logs, tratamento de um proxy (o estudo de caso menciona isso a propósito do endereço IP dos clientes)...

7.1.2. Depois do roteamento: src/EventListener/Block.php

<?php
// src/EventListener/Block.php: um listener de kernel.request, executado DEPOIS do
// roteamento: ele conhece a rota escolhida

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\HttpKernel\KernelEvents;

// priority 0 (padrão): depois do roteamento (priority 32)
#[AsEventListener(event: KernelEvents::REQUEST)]
class Block
{
    public function __invoke(RequestEvent $event): void
    {
        $request = $event->getRequest();
        // o atributo _route da requisição: o nome da rota escolhida pelo roteamento
        error_log('2. Block, kernel.request (route: '.$request->attributes->get('_route').')');
        if ($request->query->has('block')) {
            // uma exceção: o restante (Timing, a action) não é executado
            throw new AccessDeniedHttpException('access blocked');
        }
    }
}
  • linha 13: a prioridade padrão, 0: o listener é chamado depois do roteamento;
  • linha 20: mensagem nº 2. O roteamento armazenou o nome da rota selecionada no atributo [_route] da requisição (e seus parâmetros nos atributos de mesmo nome, exemplo 12);
  • Linhas 21–24: o parâmetro [?block] da URL ([has] verifica sua presença) provoca um erro 403 (Forbidden, acesso negado): a exceção [AccessDeniedHttpException] encerra o processamento.

7.1.3. Antes da ação: src/EventListener/Timed.php e Timing.php

Queremos medir o tempo apenas de certas ações, as que precisam disso. Basta marcá-las com um atributo personalizado, [PHP]:

<?php
// src/EventListener/Timed.php: um ATRIBUTO PHP de nossa própria invenção, para colocar
// nas actions cuja duração queremos medir (veja o listener Timing)

namespace App\EventListener;

use Attribute;

// #[Attribute]: esta classe é um atributo; TARGET_METHOD: ele é colocado em um método
#[Attribute(Attribute::TARGET_METHOD)]
class Timed
{
}

Um atributo é uma classe comum, ela própria marcada com o atributo [#[Attribute]]; [Attribute::TARGET_METHOD] indica que ele se aplica a um método. Esse atributo não carrega nenhuma informação: sua mera presença é o que importa.

<?php
// src/EventListener/Timing.php: um listener de três eventos, que age apenas
// para as actions marcadas com o atributo #[Timed]: ANTES da action, DEPOIS
// dela e, por fim, mais uma vez DEPOIS do envio da resposta (kernel.terminate)

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\ControllerEvent;
use Symfony\Component\HttpKernel\Event\ResponseEvent;
use Symfony\Component\HttpKernel\Event\TerminateEvent;
use Symfony\Component\HttpKernel\KernelEvents;

class Timing
{
    // kernel.controller: a action foi escolhida, mas ainda não foi chamada
    #[AsEventListener(event: KernelEvents::CONTROLLER)]
    public function before(ControllerEvent $event): void
    {
        // getAttributes: os atributos PHP de uma determinada classe, presentes na action
        if ($event->getAttributes(Timed::class) === []) {
            return;
        }
        error_log('3. Timing, kernel.controller (before the action)');
        // a hora de início (hrtime: um relógio preciso, em nanossegundos), armazenada
        // nos atributos da requisição (escopo de requisição, veja o exemplo 12)
        $event->getRequest()->attributes->set('start', hrtime(true));
    }

    #[AsEventListener(event: KernelEvents::RESPONSE)]
    public function after(ResponseEvent $event): void
    {
        if ($event->getRequest()->attributes->has('start')) {
            error_log('6. Timing, kernel.response (code '.$event->getResponse()->getStatusCode().')');
        }
    }

    // kernel.terminate: bem no final, DEPOIS de a resposta ser enviada ao navegador;
    // a resposta não pode mais ser alterada
    #[AsEventListener(event: KernelEvents::TERMINATE)]
    public function end(TerminateEvent $event): void
    {
        $start = $event->getRequest()->attributes->get('start');
        // a medição não começou se a action não foi alcançada
        if ($start !== null) {
            $ms = round((hrtime(true) - $start) / 1e6);
            error_log("8. Timing, kernel.terminate (end, $ms ms)");
        }
    }
}
  • Linhas 17–28: o evento [kernel.controller]. O método [getAttributes] do evento devolve os atributos [PHP] de uma determinada classe presentes na ação (e em sua classe): uma lista vazia significa que a ação não está marcada, e o listener não faz nada. Caso contrário, mensagem nº 3, e o horário de início, armazenado nos atributos da requisição (exemplo 12). [hrtime(true)] é um relógio preciso, em nanossegundos, projetado para medir durações;
  • linhas 30–36: mensagem nº 6, sobre [kernel.response], com o código da resposta, se a medição tiver começado. A prioridade padrão, 0, coloca esse listener antes do [Logger] (-100);
  • linhas 40–49: o evento [kernel.terminate], publicado depois que a resposta é enviada: mensagem nº 8, contendo o tempo decorrido desde a mensagem nº 3. A verificação da linha 45 confirma que a medição começou: o evento é publicado para todas as requisições, mesmo as que não chegaram à ação.

É assim que o [Symfony] próprio implementa alguns de seus atributos: [#[IsGranted]], que veremos no próximo capítulo, é lido por um listener de [kernel.controller_arguments], que nega o acesso à ação se o usuário não tiver a permissão exigida.

7.1.4. Os argumentos da ação: src/Binding/IntegerResolver.php e o controller

<?php
// src/Binding/IntegerResolver.php: um argument resolver (veja o exemplo 12): o
// parâmetro de rota transformado em inteiro, ou em null se não for um
// inteiro (cabe então à action decidir)

namespace App\Binding;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Controller\ValueResolverInterface;
use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadata;

class IntegerResolver implements ValueResolverInterface
{
    public function resolve(Request $request, ArgumentMetadata $argument): iterable
    {
        $value = $request->attributes->get($argument->getName());
        error_log("4. IntegerResolver, the arguments of the action (received value: \"$value\")");
        $n = filter_var($value, FILTER_VALIDATE_INT);
        return [$n === false ? null : $n];
    }
}

Um argument resolver (Exemplo 12), que escreve a mensagem nº 4. Ele aceita qualquer texto e o converte em um inteiro ou em [null] se não for um ([filter_var] devolve [false]): diferentemente de uma restrição como [requirements] (Exemplo 02), que devolveria uma página 404 para [/square/abc]; aqui, é a ação que determinará o resultado.

<?php
// src/Controller/CalcController.php: uma action cronometrada

namespace App\Controller;

use App\EventListener\Timed;
use App\Binding\IntegerResolver;
use DomainException;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\ValueResolver;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use Symfony\Component\Routing\Attribute\Route;

class CalcController extends AbstractController
{
    // $n: o parâmetro de rota {n}, fornecido por nosso resolver IntegerResolver;
    // #[Timed]: o listener Timing mede a duração desta action
    #[Route('/square/{n}', name: 'square', methods: ['GET'])]
    #[Timed]
    public function square(#[ValueResolver(IntegerResolver::class)] ?int $n): Response
    {
        error_log("5. action square($n)");
        if ($n === null) {
            throw new BadRequestHttpException('not an integer');    // erro 400: veja ErrorPage
        }
        if ($n === 13) {
            throw new DomainException('13 brings bad luck');    // um erro "inesperado"
        }
        return $this->render('calc/result.html.twig', ['n' => $n, 'square' => $n * $n]);
    }
}
  • linha 20: a ação é marcada com nosso atributo [#[Timed]];
  • linha 21: o parâmetro [$n] é fornecido por nosso resolver (atributo [#[ValueResolver]], exemplo 12);
  • linhas 24–26: um parâmetro que não é um inteiro: erro 400 (Bad Request), causado pela exceção [BadRequestHttpException];
  • linhas 27–29: o número 13 provoca um erro “inesperado”. [DomainException] é uma classe de exceção da biblioteca padrão do [PHP];
  • linha 30: o caso normal. A view [calc/result.html.twig] simplesmente exibe o resultado.

7.1.5. Tratamento de erros: src/EventListener/ErrorPage.php

<?php
// src/EventListener/ErrorPage.php: um listener de kernel.exception, que substitui
// as páginas de erro do Symfony pelas nossas

namespace App\EventListener;

use DomainException;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
use Symfony\Component\HttpKernel\KernelEvents;
use Twig\Environment;

// priority -10: depois do listener do Symfony que escreve a exceção no log (0),
// antes do que constrói sua página de erro (-128)
#[AsEventListener(event: KernelEvents::EXCEPTION, priority: -10)]
class ErrorPage
{
    // Environment: a própria engine Twig, para construir uma página fora de um controller
    public function __construct(private Environment $twig)
    {
    }

    public function __invoke(ExceptionEvent $event): void
    {
        $e = $event->getThrowable();
        if ($e instanceof HttpExceptionInterface) {
            // os erros HTTP (403, página desconhecida -> 404...): HttpExceptionInterface
            // é a interface de todas as exceções HTTP; elas carregam seu código
            error_log("x. ErrorPage, kernel.exception (HTTP {$e->getStatusCode()})");
            $code = $e->getStatusCode();
        } elseif ($e instanceof DomainException) {
            // uma exceção "inesperada" de um determinado tipo: DomainException e suas subclasses
            error_log("x. ErrorPage, kernel.exception (DomainException: {$e->getMessage()})");
            $code = 500;
        } else {
            return;    // as demais: a página de erro do Symfony
        }
        // a resposta do evento substitui a exceção (os listeners seguintes não
        // são chamados); ela passará então por kernel.response, como uma resposta comum
        $event->setResponse(new Response(
            $this->twig->render('error.html.twig', ['code' => $code]), $code));
    }
}
  • linhas 15–17: o listener de [kernel.exception], com prioridade -10. O [Symfony] registra dois listeners para esse evento: o primeiro, com prioridade 0, registra a exceção no log; o segundo, com prioridade -128, gera a página de erro do [Symfony]. O nosso fica entre os dois: a exceção é registrada no log e, em seguida, exibimos nossa página;
  • linha 21: o listener não é um controller e não tem o método [render] de [AbstractController]: ele recebe o próprio engine do [Twig] (a classe [Twig\Environment]), cujo método [render] devolve a página renderizada como uma string;
  • linhas 28–32: todos os erros HTTP: uma URL sem rota (404), um método negado (405) e as exceções [AccessDeniedHttpException] (403) e [BadRequestHttpException] (400)... implementam a interface [HttpExceptionInterface] e carregam seu código ([getStatusCode()]). Esse único teste substitui, portanto, todas as páginas de erro do [Symfony] pelas nossas;
  • linhas 33–36: uma exceção da classe [DomainException] (ou de suas subclasses; veja o Exemplo 08): um erro “inesperado”, convertido em uma página de erro “personalizada”, com código de status 500 (Internal Server Error). A mensagem da exceção é exibida no console, mas não na página: ela pode conter detalhes internos que não interessam ao usuário;
  • linhas 37–39: as demais exceções são tratadas pelo [Symfony];
  • linhas 42–43: [setResponse] fornece a resposta, que substitui a exceção e interrompe a propagação do evento: os listeners seguintes (a página de erro do [Symfony]) não são chamados.

A página de erro recebe o código de erro e exibe uma mensagem apropriada:

{% extends 'layout.html.twig' %}
{# a página de erro; seu modelo: o código de erro #}

{% block content %}
  <div class="alert alert-danger">
    <h1 class="h4">Error {{ code }}</h1>
    {# um array associativo, indexado pelo código; ??: o valor padrão #}
    <p class="mb-0">{{ {400: 'Bad request.', 403: 'Access denied.', 404: 'Page not found.'}[code] ?? 'Internal server error.' }}</p>
  </div>
{% endblock %}
  • Linha 8: um array associativo definido na view ([{key: value, ...}]), do qual se obtém o elemento com índice [code]; o operador [??] fornece um valor padrão quando esse elemento não existe.

Há outra maneira, ainda mais simples, de substituir as páginas de erro sem escrever um listener: uma view chamada [templates/bundles/TwigBundle/Exception/error404.html.twig] substitui a página de erro 404, e o mesmo vale para cada código ([error.html.twig] para todos os demais). Essas views só são usadas em produção; o modo de depuração mantém suas páginas detalhadas (você pode visualizá-las no modo de depuração em [/_error/404], desde que tenha importado as rotas [@FrameworkBundle/Resources/config/routing/errors.php]). Um listener, por outro lado, permite qualquer tipo de tratamento (uma resposta em JSON, um redirecionamento etc.) em todos os modos.

7.1.6. Execução

Caso normal, [/square/7]:

Image

O console do servidor exibe as oito etapas em ordem (as datas que o [php -S] coloca no início das linhas foram removidas):

--- GET /square/7
1. Logger, kernel.request (before the routing)
[info] Matched route "square".
2. Block, kernel.request (route: square)
3. Timing, kernel.controller (before the action)
4. IntegerResolver, the arguments of the action (received value: "7")
5. action square(7)
6. Timing, kernel.response (code 200)
7. Logger, kernel.response (code 200)
8. Timing, kernel.terminate (end, 2 ms)
127.0.0.1:51612 [200]: GET /square/7

A linha [[info]] vem do roteamento do [Symfony]: é o seu log (log). Sem uma biblioteca de logging (a mais usada é o [Monolog], instalado por [composer require logger]), o [Symfony] usa um log mínimo, que escreve no console. A última linha é o log do servidor de desenvolvimento, escrito quando a requisição termina. Um acesso bloqueado, [/square/7?block]:

Image

1
2
3
4
5
6
7
--- GET /square/7?block
1. Logger, kernel.request (before the routing)
[info] Matched route "square".
2. Block, kernel.request (route: square)
[error] Uncaught PHP Exception Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException: "access blocked" at Block.php line 23
x. ErrorPage, kernel.exception (HTTP 403)
7. Logger, kernel.response (code 403)

O listener [Block] lançou uma exceção: a ação não foi selecionada, seus argumentos não foram calculados e ela não foi chamada. A exceção foi registrada no log pelo [Symfony] e depois convertida em uma resposta por nosso listener; essa resposta passou por [kernel.response]. O evento [kernel.terminate] foi publicado, mas [Timing] não exibiu nada, pois a medição não havia começado. Um parâmetro que não é um inteiro, [/square/abc]:

Image

--- GET /square/abc
1. Logger, kernel.request (before the routing)
[info] Matched route "square".
2. Block, kernel.request (route: square)
3. Timing, kernel.controller (before the action)
4. IntegerResolver, the arguments of the action (received value: "abc")
5. action square()
[error] Uncaught PHP Exception Symfony\Component\HttpKernel\Exception\BadRequestHttpException: "not an integer" at CalcController.php line 25
x. ErrorPage, kernel.exception (HTTP 400)
6. Timing, kernel.response (code 400)
7. Logger, kernel.response (code 400)
8. Timing, kernel.terminate (end, 1 ms)

Desta vez, a ação foi chamada com [null] (que é renderizado como uma string vazia: [square()]), e foi essa ação que lançou o erro 400. Um erro “inesperado”, [/square/13]:

Image

--- GET /square/13
1. Logger, kernel.request (before the routing)
[info] Matched route "square".
2. Block, kernel.request (route: square)
3. Timing, kernel.controller (before the action)
4. IntegerResolver, the arguments of the action (received value: "13")
5. action square(13)
[critical] Uncaught PHP Exception DomainException: "13 brings bad luck" at CalcController.php line 28
x. ErrorPage, kernel.exception (DomainException: 13 brings bad luck)
6. Timing, kernel.response (code 500)
7. Logger, kernel.response (code 500)
8. Timing, kernel.terminate (end, 1 ms)

A exceção foi tratada por nosso listener: o usuário vê a página de erro “personalizada”, e não a página detalhada, embora o modo de depuração esteja ativo. Ela foi registrada no log mesmo assim, com o nível [critical] (um erro HTTP é simplesmente um [error]): como o [Laravel], o [Symfony] distingue entre registrar no log uma exceção e a resposta que ela gera. Por fim, uma URL que não corresponde a nenhuma rota, [/unknown]:

1
2
3
4
5
--- GET /unknown
1. Logger, kernel.request (before the routing)
[error] Uncaught PHP Exception Symfony\Component\HttpKernel\Exception\NotFoundHttpException: "No route found for "GET http://localhost:8000/unknown"" at RouterListener.php line 156
x. ErrorPage, kernel.exception (HTTP 404)
7. Logger, kernel.response (code 404)

O roteamento falhou: nenhum listener depois dele, nenhuma ação. A página 404 é a nossa:

curl http://localhost:8000/unknown
1
2
3
4
5
6
...
      <div class="alert alert-danger">
    <h1 class="h4">Error 404</h1>
        <p class="mb-0">Page not found.</p>
  </div>
...

Vamos ao essencial. Os listeners de eventos do kernel são o lugar certo para as verificações comuns a muitas ações (o usuário está logado? Ele tem permissão para acessar esta ação?): eles formam a base do componente de segurança do [Symfony], que o próximo capítulo usa para a autenticação. Os listeners do evento [kernel.exception] e as views de erro garantem que o usuário nunca veja uma página técnica, seja qual for o erro: o estudo de caso tira proveito disso.