blog
Infraestrutura web

LSCache no Laravel: purge por tag e quais rotas excluir

Observer Eloquent, cabeçalho de purge por tag e uma allowlist declarada no grupo de rotas, com o teste curl que prova MISS virando HIT e voltando a MISS depois da escrita.

JR · · 7 min de leitura · 2 tabelas · 13 blocos de código

Resposta curta: a invalidação se faz com um observer Eloquent que acumula tags e um middleware que emite `X-LiteSpeed-Purge: tag=post_17` na resposta da escrita.

Neste artigo
  1. A decisão de cachear acontece antes do `$next()`
  2. O middleware mínimo que aplica os três cabeçalhos
  3. A allowlist mora no arquivo de rotas, não dentro do middleware
  4. Como um observer Eloquent dispara o purge por tag
  5. Verificando MISS, HIT e volta para MISS com curl
  6. O que não dá para reproduzir e onde isso quebra
  7. Checklist antes de ligar em produção

A decisão de cachear acontece antes do `$next()`

O erro mais comum em cache de página no Laravel é tentar adivinhar se a resposta é pública olhando o que saiu dela: presença de cookie de sessão, Set-Cookie, tamanho do HTML, existência de token CSRF. Isso é heurística, e heurística em cache de página erra na direção pior possível, servindo conteúdo de um usuário para outro.

A regra que vale a pena adotar é mais rígida e mais simples de auditar: a resposta só é cacheável se três condições forem verdadeiras antes de o middleware chamar $next($request). Duas delas o middleware checa em código; a terceira é satisfeita pelo simples fato de o middleware ter sido aplicado àquela rota.

  1. Método GET (ou HEAD).
  2. A rota está em uma allowlist explícita, declarada no grupo de rotas.
  3. Não há usuário autenticado no guard relevante (Auth::guard()->guest()).

Depois do $next(), o middleware faz apenas uma coisa: confirma que o status é 200 e aplica os cabeçalhos de cache. Ele não inspeciona cookie nenhum, não olha Set-Cookie, não varre o corpo. Se a rota não está na allowlist, ela nunca chega perto de ser cacheada, e isso inclui login, painel, carrinho, qualquer rota sob middleware('auth') e endpoints de API. Elas ficam de fora por omissão deliberada, não por detecção.

Essa inversão tem um efeito prático: revisar a segurança do cache vira ler um arquivo de rotas, não auditar um middleware cheio de condicionais.

Ordem das checagens no middleware de cacheMétodo GET ou HEADSenão, segue sem cabeçalhoRota na allowlistMiddleware só nessas rotasGuard sem usuário autenticadoAuth::guard()->guest()Chama $next($request)Aplicação gera a respostaStatus 200Único teste após o nextAplica cabeçalhos LSCacheCache-Control e Tag
A decisão de cachear é tomada antes do $next(). Depois dele, só confirmação de status e escrita de cabeçalhos.

O middleware mínimo que aplica os três cabeçalhos

A documentação do LSCache for Laravel descreve o contrato de cabeçalhos que o servidor LiteSpeed lê: X-LiteSpeed-Cache-Control na resposta para dizer o que cachear e por quanto tempo, X-LiteSpeed-Tag para marcar a entrada, e X-LiteSpeed-Purge para invalidar.

<?php
// app/Http/Middleware/LsCachePublic.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

class LsCachePublic
{
    public function handle(Request $request, Closure $next, int $ttl = 300, ?string $tag = null)
    {
        // 1) Decisão ANTES do $next(): método, allowlist (o próprio middleware
        //    só é aplicado às rotas da allowlist) e ausência de sessão.
        $cacheable = in_array($request->getMethod(), ['GET', 'HEAD'], true)
            && Auth::guard()->guest();

        $response = $next($request);

        if (! $cacheable) {
            return $response;
        }

        // 2) Depois do $next(): apenas confirma 200 e aplica cabeçalhos.
        if ($response->getStatusCode() !== 200) {
            return $response;
        }

        $response->headers->set('X-LiteSpeed-Cache-Control', "public,max-age={$ttl}");
        $response->headers->set('Cache-Control', "public, max-age={$ttl}");

        if ($tag !== null) {
            $response->headers->set('X-LiteSpeed-Tag', $tag);
        }

        return $response;
    }
}

Registre o alias em bootstrap/app.php (Laravel 11/12) ou em app/Http/Kernel.php (Laravel 10 e anteriores):

// bootstrap/app.php — Laravel 11/12
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'lscache' => \App\Http\Middleware\LsCachePublic::class,
    ]);
})

A allowlist mora no arquivo de rotas, não dentro do middleware

Nada de aplicar o middleware globalmente e depois excluir. A lista positiva fica visível em routes/web.php:

Route::middleware('lscache:600')->group(function () {
    Route::get('/', [HomeController::class, 'index'])->name('home');
    Route::get('/sobre', fn () => view('sobre'));
});

// A listagem precisa carregar a MESMA tag que o observer purga.
Route::get('/blog', [PostController::class, 'index'])
    ->middleware('lscache:600,posts_index')
    ->name('posts.index');

// Rota com tag por recurso: o alias 'lscache' não serve, porque o parâmetro
// de middleware é string estática. Use a classe dedicada registrada abaixo.
Route::get('/blog/{post:slug}', [PostController::class, 'show'])
    ->middleware('lscache.post:600')
    ->name('posts.show');

Purge por tag só atinge entradas que foram armazenadas com aquela tag. Se a resposta de /blog sai sem X-LiteSpeed-Tag: posts_index, o X-LiteSpeed-Purge: tag=posts_index do observer não descarta nada: a listagem segue servida do cache até o TTL expirar. Tag emitida na leitura e tag purgada na escrita precisam ser a mesma string.

Para a tag por recurso, lscache.post é uma classe própria que estende o middleware anterior e acrescenta um bloco depois do $next(), lendo $request->route('post'):

<?php
// app/Http/Middleware/LsCachePost.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class LsCachePost extends LsCachePublic
{
    public function handle(Request $request, Closure $next, int $ttl = 300, ?string $tag = null)
    {
        $response = parent::handle($request, $next, $ttl);

        // O pai só aplica cabeçalhos quando a resposta é cacheável. Se
        // X-LiteSpeed-Cache-Control não saiu, não há entrada para rotular.
        if (! $response->headers->has('X-LiteSpeed-Cache-Control')) {
            return $response;
        }

        // Requer route model binding: a rota declara {post:slug}, então
        // route('post') devolve o model, não a string do slug.
        if ($post = $request->route('post')) {
            $response->headers->set('X-LiteSpeed-Tag', 'post_'.$post->getKey());
        }

        return $response;
    }
}

O alias entra no mesmo lugar do outro:

// bootstrap/app.php — Laravel 11/12
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'lscache'      => \App\Http\Middleware\LsCachePublic::class,
        'lscache.post' => \App\Http\Middleware\LsCachePost::class,
    ]);
})

Sem esse registro, ->middleware('lscache.post:600') estoura BindingResolutionException ao resolver a rota.

O que fica fora, e por quê:

Rota Entra na allowlist Motivo
GET / sim pública, mesma saída para todo visitante anônimo
GET /blog/{slug} sim pública, com tag por post para purge
GET /login não formulário com token CSRF por sessão
GET /painel/* não sob middleware('auth')
GET /carrinho não estado por sessão
POST de qualquer rota não método não cacheável
GET /api/* não resposta por token/escopo

Como um observer Eloquent dispara o purge por tag

O ciclo só fecha quando a escrita invalida a leitura. A doc do LSCache for Laravel define X-LiteSpeed-Purge como o cabeçalho de resposta que instrui o servidor a descartar entradas, aceitando a sintaxe por tag (tag=...) e o curinga * para tudo.

O problema é que o purge viaja em uma resposta HTTP, e o observer roda no meio de uma transação, sem referência direta à resposta. A saída limpa é acumular as tags em um serviço singleton durante o request e deixar um middleware terminal escrever o cabeçalho.

O serviço singleton que acumula as tags do request

<?php
// app/Support/PurgeBag.php
namespace App\Support;

class PurgeBag
{
    private array $tags = [];

    public function add(string $tag): void
    {
        $this->tags[$tag] = true;
    }

    public function header(): ?string
    {
        if ($this->tags === []) {
            return null;
        }

        // A doc do LSCache documenta cada item do purge com seu próprio
        // prefixo, separados por vírgula: "tag=a, tag=b". Não há forma
        // documentada de listar várias tags sob um único "tag=".
        return implode(', ', array_map(
            fn (string $tag) => 'tag='.$tag,
            array_keys($this->tags)
        ));
    }
}

Registre como singleton em AppServiceProvider::register():

$this->app->singleton(\App\Support\PurgeBag::class);

O observer que marca o post e a listagem

<?php
// app/Observers/PostObserver.php
namespace App\Observers;

use App\Models\Post;
use App\Support\PurgeBag;

class PostObserver
{
    public function __construct(private PurgeBag $bag) {}

    public function saved(Post $post): void   { $this->flag($post); }
    public function deleted(Post $post): void { $this->flag($post); }

    private function flag(Post $post): void
    {
        $this->bag->add('post_'.$post->getKey()); // a página do post
        $this->bag->add('posts_index');           // a listagem
    }
}

No Laravel 11/12, registre com o atributo #[ObservedBy(PostObserver::class)] na classe do model, ou com Post::observe(PostObserver::class) no boot() do provider.

O middleware terminal que escreve `X-LiteSpeed-Purge`

<?php
// app/Http/Middleware/EmitPurge.php
namespace App\Http\Middleware;

use App\Support\PurgeBag;
use Closure;
use Illuminate\Http\Request;

class EmitPurge
{
    public function __construct(private PurgeBag $bag) {}

    public function handle(Request $request, Closure $next)
    {
        $response = $next($request);

        if ($header = $this->bag->header()) {
            $response->headers->set('X-LiteSpeed-Purge', $header);
        }

        return $response;
    }
}

Esse middleware pode ser global: ele só escreve algo quando o bag tem conteúdo, e o bag só tem conteúdo quando um model observado mudou no request. A resposta que leva o purge é tipicamente o POST/PUT do painel, que não é cacheável de qualquer forma.

Escritas fora do ciclo HTTP não geram purge

Seed, comando artisan, job de fila e import não têm resposta HTTP para carregar o cabeçalho. O observer vai encher o bag e ninguém vai ler. Duas saídas honestas:

Cabeçalho Direção Função
X-LiteSpeed-Cache-Control resposta define se e por quanto tempo cachear
X-LiteSpeed-Tag resposta rotula a entrada armazenada
X-LiteSpeed-Purge resposta descarta entradas por tag ou *
x-litespeed-cache resposta ao cliente diagnóstico: hit ou miss

Verificando MISS, HIT e volta para MISS com curl

O teste que importa não é ver um HIT. É ver MISS virar HIT, salvar o model e ver voltar para MISS.

URL=https://exemplo.test/blog/meu-post

# 1) primeiro acesso: deve ser miss
curl -sI "$URL" | grep -i '^x-litespeed-cache'

# 2) segundo acesso: deve ser hit
curl -sI "$URL" | grep -i '^x-litespeed-cache'

# 3) tempo até o primeiro byte, três vezes seguidas
for i in 1 2 3; do
  curl -s -o /dev/null -w '%{time_starttransfer}\n' "$URL"
done

Saída possível desse laço, a título de exemplo ilustrativo e não de benchmark:

0.214301
0.021844
0.020917

A primeira linha é o MISS, que executou PHP. As seguintes vieram do cache. O número no seu ambiente vai depender de aplicação, banco e rede, meça o seu.

Agora feche o ciclo. Salve o post pelo painel, por uma requisição HTTP de escrita que passe pelo middleware de purge, e repita:

curl -sI "$URL" | grep -i '^x-litespeed-cache'   # esperado: miss
curl -sI "$URL" | grep -i '^x-litespeed-cache'   # esperado: hit

Se o passo pós-escrita continuar devolvendo hit, inspecione a resposta da escrita, não a da leitura:

curl -s -o /dev/null -D - -X POST https://exemplo.test/painel/posts/17 \
  -H 'Cookie: ...' | grep -i '^x-litespeed-purge'

Use -D - e não -I: com -I, o curl manda HEAD e, se você forçar -X POST, ele continua esperando uma resposta sem corpo, o que gera aviso e pode travar até o timeout. -D - despeja os cabeçalhos na saída padrão e -o /dev/null descarta o corpo real.

Sem esse cabeçalho na resposta do POST, o problema está no observer ou na ordem do middleware, não no servidor.

Se a escrita for feita por php artisan tinker, comando ou job, não há resposta HTTP e o purge não sai: o observer enche o bag e ninguém lê. Nesse caso, chame a rota interna de purge descrita em "Escritas fora do ciclo HTTP" ou espere o TTL expirar.

Ciclo de validação com curlMISSPHP executa, entrada armazenadaHITServidor responde sem PHPEscritaPOST devolve X-LiteSpeed-PurgeMISS de novoTag descartada, ciclo fechado
O teste que vale é o ciclo completo, não um HIT isolado. Se o último passo volta hit, inspecione a resposta da escrita.

O que não dá para reproduzir e onde isso quebra

OpenLiteSpeed sem o módulo de cache habilitado no vhost. Os cabeçalhos saem da aplicação, o servidor ignora, e x-litespeed-cache simplesmente não aparece na resposta. A doc do LSCache cobre a habilitação do cache no nível do vhost; sem isso, todo o resto do artigo é código correto sem efeito. O sintoma é exatamente esse: nenhum cabeçalho x-litespeed-cache, nem miss. Se você vê miss sempre, o módulo está ativo e o problema é de política. Se não vê nada, o problema é de servidor.

Cachear HTML com token CSRF. Este é o risco que mais machuca. Uma página pública que contenha um <form> com @csrf armazena o token de um visitante dentro do HTML cacheado. O próximo visitante recebe um token que não bate com a sessão dele e toma 419 Page Expired ao enviar o formulário. Formulário de newsletter, de busca com POST e de comentário são os suspeitos de sempre. Opções: deixar a rota fora da allowlist, trocar o POST por GET quando faz sentido (busca), ou buscar o token por JavaScript em um endpoint não cacheado depois do carregamento.

Conteúdo que varia por visitante dentro de página pública. Saudação com nome, contador de itens no carrinho no cabeçalho, bloco de "continuar lendo". Se existir, ou a rota sai da allowlist, ou esses pedaços passam a ser carregados por requisição separada.

Proxy ou CDN na frente. Cache-Control: public sai para a internet e pode ser obedecido por camadas que não enxergam seu X-LiteSpeed-Purge. Se houver CDN, o purge precisa ser disparado também lá, ou o TTL público precisa ser curto o bastante para o erro ser tolerável.

Checklist antes de ligar em produção

Para reverter, remova o grupo de middleware das rotas e emita X-LiteSpeed-Purge: * uma vez. O código do observer pode ficar: sem rota cacheada, ele apenas acumula tags que ninguém usa.

Referências

  1. Documentação oficial (litespeed) — LSCache for Laravel. Consultado em 2026-10-03.
Leia também