# 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.

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

João Rizzon · 2026-11-04 · Infraestrutura web

---

## 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.

- Método `GET` (ou `HEAD`).
- A rota está em uma allowlist explícita, declarada no grupo de rotas.
- 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.

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

A [documentação do LSCache for Laravel](https://docs.litespeedtech.com/lscache/lsclaravel/) 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
<?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):

```php
// 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`:

```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
<?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:

```php
// 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
<?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()`:

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

### O observer que marca o post e a listagem

```php
<?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
<?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:

- Aceitar o TTL como piso de frescor para esses casos e documentar isso.
- Fazer o worker chamar uma rota interna de purge, restrita por IP/token, cuja única função é devolver 204 com `X-LiteSpeed-Purge` montado a partir das tags recebidas. É uma requisição HTTP a mais, mas é o único jeito de o servidor ver o cabeçalho.

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

```bash
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:

```bash
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:

```bash
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.

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

- A allowlist está em grupos de rota, e não há aplicação global do middleware de cache.
- Nenhuma rota sob `auth`, nenhuma rota de API e nenhum método diferente de `GET`/`HEAD` recebem o middleware.
- Cada view cacheada foi lida à procura de `@csrf`, nome de usuário e contador por sessão.
- O observer está registrado e cobre `saved` e `deleted` (inclua `restored` se usar soft deletes).
- O middleware que emite `X-LiteSpeed-Purge` roda em todas as rotas de escrita.
- Há um plano declarado para escritas fora do HTTP (fila, comando, import).
- O teste MISS → HIT → escrita → MISS foi executado e passou em pelo menos uma rota com tag.

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.

