7. O ciclo de vida de uma requisição
Entre a chegada de uma requisição e o envio de sua resposta, o [Laravel] passa por várias etapas, e a aplicação pode intervir em cada uma delas. Já encontramos várias delas: middleware (exemplos 03, 12, 16, 22), binding de parâmetros de rota (exemplo 12) e tratadores de exceção (exemplos 08 e 12). Este capítulo as reúne em um único exemplo, que exibe uma mensagem no console a cada etapa para que você possa observar a ordem delas:
- 1 e 7. Os middlewares globais, executados para todas as requisições, até mesmo antes do roteamento. Um middleware envolve o restante do processamento: ele vê a requisição passar antes dele e a resposta depois dele (exemplo 03). O [Laravel] instala vários por padrão (strings vazias se tornam [null], modo de manutenção, requisições se tornam CORS...), na ordem da lista de middlewares globais;
- O roteamento. O [Laravel] procura a rota que corresponde à URL e ao método. Se nenhuma corresponder, uma exceção [NotFoundHttpException] é lançada (404);
- Os middlewares de grupo e de rota, em ordem: primeiro os do grupo [web] (cookies, sessão, erros de formulário, proteção anti-CSRF, binding de parâmetros), depois os da rota. Um deles, o [SubstituteBindings], faz o binding dos parâmetros da rota (2, exemplo 12). Os middlewares de rota (3 e 4) são o lugar certo para verificações específicas de certas actions: é assim que funciona o middleware [auth] do próximo capítulo. Se um deles retornar uma resposta sem chamar [$next] (ou lançar uma exceção), o processamento para ali: a action não é chamada;
- 5. A action e a view que ela gera;
- 6. O fim da cadeia de middlewares, em ordem inversa: cada componente recebe a resposta de [$next], pode modificá-la (adicionar um cabeçalho ou um cookie) e deve retorná-la;
- 8. Os métodos [terminate] dos middlewares que os possuem, executados depois que a resposta é enviada ao navegador. Eles não podem mais modificar a resposta: servem para tarefas que podem esperar (gravar um log, enviar estatísticas etc.), sem fazer o usuário esperar;
- x. Os tratadores de exceção: uma exceção lançada por um middleware, uma action ou uma view é passada ao tratador ([render], em [bootstrap/app.php]) registrado para sua classe, que constrói uma resposta de erro. Essa resposta volta então a subir pelos middlewares, como uma resposta comum.
Isso equivale aos filtros do [Java] e aos interceptors do [Spring MVC], aos filtros de action do [ASP.NET Core MVC]e às funções [before_request] / [after_request] do [Flask]. A particularidade do [Laravel] é que quase tudo nele é middleware: o mesmo conceito é usado para processar todas as requisições (middleware global), uma família de rotas (grupos) ou algumas rotas.
7.1. Exemplo 24: As etapas do processamento de uma requisição
A aplicação tem apenas uma action, 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 gravadas no console do servidor pela função [error_log] do [PHP], exibidas pelo comando [php artisan serve].
7.1.1. O middleware global: app/Http/Middleware/Logger.php
- linhas 16–17: o middleware exibe a requisição ([getRequestUri()]: o caminho e os parâmetros). É a mensagem nº 1: nada aconteceu ainda no [Laravel], nem mesmo o roteamento;
- linha 19: o restante do processamento ocorre dentro desta chamada;
- linha 20: mensagem nº 7, depois que todo o resto foi concluído. [getStatusCode()] é o código da resposta.
Um middleware global não conhece a rota escolhida, pois o roteamento ainda não ocorreu. Ele serve para processamentos que se aplicam a todas as requisições: logging, compressão e tratamento de proxy (o middleware [TrustProxies] do [Laravel] corrige o endereço do cliente quando a aplicação está atrás de um servidor proxy; o estudo de caso trata disso em relação ao endereço IP dos clientes).
7.1.2. O mapeamento de parâmetros: routes/web.php
- linhas 12–16: [Route::bind] registra um binding explícito: todo parâmetro de rota chamado [{integer}] passa por esta função, que recebe o texto da URL e retorna o valor que a action receberá. Ela aceita qualquer texto e o converte em um inteiro, ou em [null] se não for um: diferentemente de [whereNumber] (exemplo 02), que retornaria uma página 404 para [/square/abc], aqui é a action que decidirá. Ela exibe a mensagem nº 2. Esta é a outra forma do binding de rota do exemplo 12, que vinculava um parâmetro a uma classe ([UrlRoutable]);
- Linhas 19–20: a rota, chamada [square], tem dois middlewares de rota, que serão executados nessa ordem, depois dos do grupo [web].
7.1.3. Os middlewares de rota: Block.php e Timing.php
- Linha 16: mensagem nº 3. Um middleware de rota conhece a rota selecionada: [$request->route()] retorna a rota, e [getName()] retorna o nome dela;
- Linhas 17–19: o parâmetro [?block] da URL ([has] verifica sua presença) provoca um erro 403 (*Forbidden*, acesso negado): [abort] lança uma exceção, que interrompe o processamento.
- linhas 15–18: mensagem nº 4 e a hora de início, armazenada nos atributos da requisição (exemplo 12). [hrtime(true)] é um relógio preciso, em nanossegundos, projetado para medir durações;
- Linha 20: mensagem nº 6, depois da action, com o código da resposta;
- Linhas 26–34: o método [terminate], chamado pelo [Laravel] depois que a resposta é enviada, com a requisição e a resposta: mensagem nº 8, com o tempo decorrido desde a mensagem nº 4. O [Laravel] o chama para todos os middlewares da rota, mesmo que não tenham sido executados (quando um middleware anterior interrompeu o processamento): a verificação da linha 30 confirma que a medição foi iniciada.
7.1.4. Tratamento de erros: bootstrap/app.php
- linha 19: [prepend] coloca o middleware global no início da lista: ele é executado antes de todos os outros e vê a resposta depois de todos os outros;
- Linhas 23–27: um tratador de exceção para a classe [DomainException] (e 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 30–33: um tratador para todos os erros HTTP. [abort(400)], [abort(403)], uma URL de rota inexistente (404), um método proibido (405): todos lançam uma exceção que implementa a interface [HttpExceptionInterface] do [Symfony] e que contém seu código ([getStatusCode()]). Esse único tratador substitui, portanto, todas as páginas de erro em inglês do [Laravel] pelas nossas.
O [Laravel] passa uma exceção ao primeiro tratador cujo tipo de parâmetro corresponda a ela. Uma exceção sem tratador se torna um erro 500: no modo de depuração, é a página detalhada (exemplo 03); sem o modo de depuração, é a página de erro 500 padrão. Há outra maneira, ainda mais simples, de substituir páginas de erro: uma view chamada [resources/views/errors/404.blade.php] substitui a página de erro 404, e o mesmo vale para cada código de erro (o exemplo 26 usa essa abordagem). Os tratadores [render], por outro lado, permitem qualquer tipo de tratamento: uma mensagem de log, uma resposta JSON, um redirecionamento...
7.1.5. O controller e a página de erro
- Linha 13: o parâmetro [$n] recebe o valor vinculado por [Route::bind]. O [Laravel] não passa à action um parâmetro vinculado a [null]: o parâmetro da action tem, portanto, um valor padrão, [null], que será seu valor nesse caso;
- linha 17: um parâmetro que não é um inteiro: erro 400;
- linha 20: o número 13 provoca um erro “inesperado”. [DomainException] é uma classe de exceção da biblioteca padrão do [PHP];
- linha 22: o caso normal.
A página de erro recebe o código de erro e exibe uma mensagem apropriada. A diretiva [@switch] seleciona um bloco com base em um valor: [@case] especifica um valor, [@break] encerra o bloco e [@default] trata os demais valores. A view [calc/result.blade.php] simplesmente exibe o resultado.
7.1.6. Execução
O caso normal, [/square/7]:

O console do servidor exibe as oito etapas, em ordem:
A última linha é o log do servidor de desenvolvimento, gravado quando a requisição termina. Um acesso bloqueado, [/square/7?block]:

O primeiro middleware de rota lançou uma exceção: o segundo middleware e a action não foram executados. A resposta de erro, gerada pelo tratador, sobe até o middleware global. [terminate] foi chamado, mas não exibiu nada, pois a medição não começou. Um parâmetro que não é um inteiro, [/square/abc]:

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

A exceção foi tratada por seu tratador: o usuário vê a página de erro “personalizada”, não a página detalhada, mesmo com o modo de depuração ativado. A exceção continua sendo registrada no log [storage/logs/laravel.log]: [Laravel] distingue entre o registro de uma exceção (*report*, sua entrada no log) e sua renderização (*render*, a resposta). Por fim, uma URL que não corresponde a nenhuma rota, [/unknown]:
O roteamento falhou: nenhum middleware de rota, nenhuma action. A página 404 é a nossa:
Vamos ao essencial. O middleware de rota é o lugar certo para verificações comuns a muitas actions (o usuário está logado? Tem permissão para acessar esta action?): o próximo capítulo o usa para a autenticação. Os tratadores de exceção e as views ([errors/...]) garantem que o usuário nunca veja uma página técnica, qualquer que seja o erro: o estudo de caso aproveita isso.