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 [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

24-lifecycle/
├── app/
│   └── Http/
│       ├── Controllers/
│       │   └── CalcController.php
│       └── Middleware/
│           ├── Block.php
│           ├── Timing.php
│           └── Logger.php
├── bootstrap/
│   └── app.php
├── resources/
│   └── views/
│       ├── calc/
│       │   └── result.blade.php
│       ├── error.blade.php
│       └── layout.blade.php
├── routes/
│   └── web.php
└── ...

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

<?php
// app/Http/Middleware/Logger.php: um middleware GLOBAL, o primeiro de todos: ele
// vê cada requisição passar ANTES do resto da aplicação, e a resposta DEPOIS

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class Logger
{
    public function handle(Request $request, Closure $next): Response
    {
        // error_log: uma mensagem no console do servidor de desenvolvimento
        error_log('--- '.$request->method().' '.$request->getRequestUri());
        error_log('1. global middleware Logger (before)');
        // todo o resto: os outros middlewares, o roteamento, a action, a view
        $response = $next($request);
        error_log('7. global middleware Logger (after: code '.$response->getStatusCode().')');
        return $response;
    }
}
  • 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

<?php
// routes/web.php: as rotas do exemplo 24

use App\Http\Controllers\CalcController;
use App\Http\Middleware\Block;
use App\Http\Middleware\Timing;
use Illuminate\Support\Facades\Route;

// um BINDING de parâmetro: qualquer parâmetro de rota chamado {integer} é transformado
// por esta função antes de ser passado à action: um inteiro, ou null se ele
// não for um inteiro (cabe então à action decidir)
Route::bind('integer', function (string $value) {
    error_log("2. binding of the parameter (received value: \"$value\")");
    $n = filter_var($value, FILTER_VALIDATE_INT);
    return $n === false ? null : $n;
});

// a rota: dois middlewares de rota, executados nesta ordem, antes da action
Route::get('square/{integer}', [CalcController::class, 'square'])->name('square')
    ->middleware([Block::class, Timing::class]);
  • 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

<?php
// app/Http/Middleware/Block.php: um middleware de ROTA, executado apenas para as
// rotas que o pedem

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class Block
{
    public function handle(Request $request, Closure $next): Response
    {
        // $request->route(): a rota escolhida pelo roteamento; getName(): seu nome
        error_log('3. middleware Block (route: '.$request->route()->getName().')');
        if ($request->has('block')) {
            // uma exceção: o resto (Timing, a action) não é executado
            abort(403);
        }
        return $next($request);
    }
}
  • 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.
<?php
// app/Http/Middleware/Timing.php: um middleware de rota, que age ANTES e DEPOIS da
// action, e uma última vez DEPOIS que a resposta é enviada (terminate)

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class Timing
{
    public function handle(Request $request, Closure $next): Response
    {
        error_log('4. middleware Timing (before)');
        // 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)
        $request->attributes->set('start', hrtime(true));
        $response = $next($request);
        error_log('6. middleware Timing (after: code '.$response->getStatusCode().')');
        return $response;
    }

    // terminate: chamado bem no final, DEPOIS que a resposta é enviada ao navegador;
    // ele não pode mais alterar a resposta
    public function terminate(Request $request, Response $response): void
    {
        $start = $request->attributes->get('start');
        // a medição não começou se a requisição foi bloqueada antes deste middleware
        if ($start !== null) {
            $ms = round((hrtime(true) - $start) / 1e6);
            error_log("8. terminate Timing (end, $ms ms)");
        }
    }
}
  • 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

<?php
// bootstrap/app.php: a aplicação do exemplo 24

use App\Http\Middleware\Logger;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;

(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        // a rota que serve o Bootstrap (veja o exemplo 15)
        then: fn () => require __DIR__.'/../../common/bootstrap.php')
    ->withMiddleware(function (Middleware $middleware): void {
        // prepend: o middleware global Logger vai ANTES de todos os outros
        $middleware->prepend(Logger::class);
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        // uma exceção "inesperada" de um dado tipo: DomainException e suas subclasses
        $exceptions->render(function (DomainException $e) {
            error_log("x. render DomainException ({$e->getMessage()})");
            // em vez da página de erro padrão, nossa view [error], com o código 500
            return response()->view('error', ['code' => 500], 500);
        });
        // os erros HTTP (abort(400), abort(403), página desconhecida -> 404...):
        // HttpExceptionInterface é a interface de todas as exceções HTTP
        $exceptions->render(function (HttpExceptionInterface $e) {
            error_log("x. render HttpException (code {$e->getStatusCode()})");
            return response()->view('error', ['code' => $e->getStatusCode()], $e->getStatusCode());
        });
    })
    ->create();
  • 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

<?php
// app/Http/Controllers/CalcController.php: uma action protegida por dois middlewares

namespace App\Http\Controllers;

use DomainException;
use Illuminate\View\View;

class CalcController
{
    // $n: o parâmetro de rota {integer}, vinculado por Route::bind (veja routes/web.php);
    // um parâmetro vinculado a null não é passado à action: daí o valor padrão
    public function square(?int $n = null): View
    {
        error_log("5. action square($n)");
        if ($n === null) {
            abort(400);    // um erro 400: veja bootstrap/app.php
        }
        if ($n === 13) {
            throw new DomainException('13 brings bad luck');    // um erro "inesperado"
        }
        return view('calc.result', ['n' => $n, 'square' => $n * $n]);
    }
}
  • 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.
@extends('layout')
{{-- the error page; its model: the error code --}}

@section('content')
  <div class="alert alert-danger">
    <h1 class="h4">Error {{ $code }}</h1>
    <p class="mb-0">
      @switch($code)
        @case(400) Bad request. @break
        @case(403) Access denied. @break
        @case(404) Page not found. @break
        @default Internal server error.
      @endswitch
    </p>
  </div>
@endsection

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]:

Image

O console do servidor exibe as oito etapas, em ordem:

  --- GET /square/7
  1. global middleware Logger (before)
  2. binding of the parameter (received value: "7")
  3. middleware Block (route: square)
  4. middleware Timing (before)
  5. action square(7)
  6. middleware Timing (after: code 200)
  7. global middleware Logger (after: code 200)
  8. terminate Timing (end, 5 ms)
  2026-09-26 18:19:51 /square/7 .................................... ~ 0.35ms

A última linha é o log do servidor de desenvolvimento, gravado quando a requisição termina. Um acesso bloqueado, [/square/7?block]:

Image

1
2
3
4
5
6
  --- GET /square/7?block
  1. global middleware Logger (before)
  2. binding of the parameter (received value: "7")
  3. middleware Block (route: square)
  x. render HttpException (code 403)
  7. global middleware Logger (after: code 403)

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]:

Image

  --- GET /square/abc
  1. global middleware Logger (before)
  2. binding of the parameter (received value: "abc")
  3. middleware Block (route: square)
  4. middleware Timing (before)
  5. action square()
  x. render HttpException (code 400)
  6. middleware Timing (after: code 400)
  7. global middleware Logger (after: code 400)
  8. terminate Timing (end, 6 ms)

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]:

Image

  --- GET /square/13
  1. global middleware Logger (before)
  2. binding of the parameter (received value: "13")
  3. middleware Block (route: square)
  4. middleware Timing (before)
  5. action square(13)
  x. render DomainException (13 brings bad luck)
  6. middleware Timing (after: code 500)
  7. global middleware Logger (after: code 500)
  8. terminate Timing (end, 3 ms)

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]:

1
2
3
4
  --- GET /unknown
  1. global middleware Logger (before)
  x. render HttpException (code 404)
  7. global middleware Logger (after: code 404)

O roteamento falhou: nenhum middleware de rota, nenhuma action. A página 404 é a nossa:

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

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.