# LSCache no Laravel: 3 cabeçalhos e um middleware por rota

Allowlist de rotas no código, purga disparada pelo Eloquent e verificação com curl, sem plugin e sem CMS no caminho.

> ligue o LSCache no Laravel por middleware que emite `X-LiteSpeed-Cache-Control: public,max-age=N` apenas em GET anônimo de rotas marcadas numa allowlist, purgue por `X-LiteSpeed-Tag`/`X-LiteSpeed-Purge` a partir de Observers do Eloquent e confirme lendo `x-litespeed-cache: hit` no curl.

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

---

## Os três cabeçalhos com que o LiteSpeed decide guardar a página

O LiteSpeed Enterprise e o OpenLiteSpeed guardam a resposta HTTP inteira em disco e a devolvem sem subir o PHP. Não existe `handler` de framework no caminho: a decisão é por cabeçalho de resposta. A aplicação responde uma vez, emite `X-LiteSpeed-Cache-Control`, e as próximas requisições com a mesma chave de cache são servidas pelo servidor web.

Segundo a [documentação do LSCache para Laravel](https://docs.litespeedtech.com/lscache/lsclaravel/) (consultada em 03/10/2026), a integração se dá por três cabeçalhos emitidos pela aplicação, e os três cabeçalhos abaixo, com os valores descritos, são o que está na doc:

| Cabeçalho | Direção | Função |
|---|---|---||
| `X-LiteSpeed-Cache-Control` | resposta | define se e por quanto tempo armazenar (`public,max-age=...`, `no-cache`) |
| `X-LiteSpeed-Tag` | resposta | marca a página com tags para purga seletiva |
| `X-LiteSpeed-Purge` | resposta | instrui o servidor a invalidar tags ou URLs |

Não há plugin. Para Laravel, a documentação oficial descreve o uso via middleware e via o pacote `litespeed/lscache-laravel`, que embrulha esses mesmos cabeçalhos em uma API de PHP. Você pode usar o pacote ou escrever o middleware à mão: o contrato com o servidor é idêntico.

Um detalhe que costuma passar batido: o cache de página do LiteSpeed precisa estar habilitado no nível do servidor ou do virtual host. Sem isso, os cabeçalhos são emitidos e ignorados, e você vai depurar código por horas atrás de um problema de configuração.

## Por que allowlist, e o que uma blocklist esquecida vaza

A regra de ouro ao ligar cache de página em aplicação sob medida: **nenhuma rota é cacheável até que alguém marque explicitamente que ela é**. Blocklist é tentadora porque dá ganho imediato em todo o site, e é exatamente por isso que ela vaza. Você esquece uma rota, e um usuário logado recebe a página montada para outro.

Fiquem fora por padrão, sem exceção:

- qualquer rota atrás de `auth`, `auth:sanctum` ou guard customizado;
- qualquer rota que leia ou escreva `session()`, inclusive flash messages;
- carrinho, checkout, wishlist, qualquer estado por visitante;
- `api/*`, onde a resposta normalmente depende de token no header e de parâmetros arbitrários;
- rotas com token CSRF embutido no HTML, porque o token guardado em cache será rejeitado pelo `VerifyCsrfToken` do próximo visitante.

E o óbvio que precisa ser dito: **só `GET` e `HEAD`**. `POST`, `PUT`, `PATCH` e `DELETE` nunca entram.

## Middleware que só emite public,max-age em resposta anônima

O middleware abaixo é um exemplo, não um trecho de produção auditado. Ele emite o cabeçalho de cache apenas quando todas as condições são satisfeitas, e emite `no-cache` em qualquer outro caso, para que uma resposta privada nunca seja armazenada por engano. Duas distinções importam aqui. `$request->hasSession()` só diz que o Laravel anexou um store de sessão à requisição, e o grupo `web` anexa para todo visitante, logado ou não: testar isso sozinho deixaria qualquer rota do grupo `web` eternamente fora do cache. E `Request::session()` lança `RuntimeException` quando não há store configurado, não devolve `null`, então operador nullsafe ali não protege de nada. O que separa resposta pública de privada é a sessão ter conteúdo próprio: `_token` e `_previous` são escritos pelo framework mesmo em visita anônima e não tornam a página pessoal; carrinho, flash message e usuário autenticado tornam.

```php
<?php
// app/Http/Middleware/LsCachePublic.php  (exemplo)
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class LsCachePublic
{
    public function handle(Request $request, Closure $next, int $ttl = 300, string $tag = '')
    {
        $response = $next($request);

        $sessionDirty = $request->hasSession()
            && $request->session()->isStarted()
            && array_diff(
                array_keys($request->session()->all()),
                ['_token', '_previous']
            ) !== [];

        $cacheable =
            in_array($request->method(), ['GET', 'HEAD'], true)
            && $response->getStatusCode() === 200
            && ! auth()->check()
            && ! $sessionDirty;

        if (! $cacheable) {
            $response->headers->set('X-LiteSpeed-Cache-Control', 'no-cache');
            return $response;
        }

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

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

        return $response;
    }
}
```

Registre com alias no `bootstrap/app.php` (Laravel 11+) ou no `$middlewareAliases` do `Kernel` (Laravel 10), e aplique rota a rota:

```php
Route::get('/', [HomeController::class, 'index'])
    ->middleware('lscache:600,home');

Route::get('/blog/{post:slug}', [PostController::class, 'show'])
    ->middleware('lscache:3600,post');

Route::get('/produtos/{categoria:slug}', [CatalogController::class, 'index'])
    ->middleware('lscache:900,catalogo');
```

O TTL vira argumento porque a home muda mais que um post antigo. A tag vira argumento porque é ela que você vai purgar depois.

### A sessão que o grupo web inicia sozinha e o Set-Cookie em cache compartilhado

O grupo `web` do Laravel inclui `StartSession`. Se a rota pertence ao grupo `web`, a sessão existe mesmo para visitante anônimo, e o `Set-Cookie` com o ID de sessão entra na resposta. Guardar uma resposta com `Set-Cookie` em cache compartilhado é entregar a mesma sessão para pessoas diferentes.

Duas saídas, e a segunda é a boa:

- remover o `Set-Cookie` da resposta no middleware quando ela for marcada como cacheável;
- definir um grupo de middleware enxuto para rotas públicas, sem `StartSession` e sem `VerifyCsrfToken`, deixando `web` para o resto da aplicação.

A segunda evita a classe inteira de erro em vez de remediar caso a caso.

### Query string livre multiplica entradas de cache sem ganho

A chave de cache do servidor inclui a query string. Rota pública que aceita parâmetro livre (`?utm_source=`, `?ref=`, busca aberta) multiplica entradas de cache sem ganho. Normalize: em rota marcada como cacheável, aceite uma lista fechada de parâmetros e redirecione (301) quando vier parâmetro fora dela, ou emita `no-cache` quando a query string não for reconhecida.

## Purga por tag disparada pelo Observer do Eloquent

Cache de página só é aceitável quando a invalidação é automática. O caminho documentado na [referência do LSCache para Laravel](https://docs.litespeedtech.com/lscache/lsclaravel/) (consultada em 03/10/2026) é a resposta HTTP com `X-LiteSpeed-Purge`: o servidor lê o cabeçalho e invalida as entradas correspondentes às tags listadas, e o escopo (`public` ou `private`) faz parte do valor. Documentado é esse contrato de cabeçalho. A organização em Observer, bag em memória e middleware terminal, descrita a seguir, é sugestão minha e não está na doc.

Isso cria uma assimetria desconfortável: o Observer do Eloquent roda em um job de fila ou num `POST` do painel administrativo, contextos que podem não ter uma resposta HTTP útil para carregar o cabeçalho. Duas organizações funcionam:

- **Purga na própria resposta administrativa.** O Observer registra as tags sujas numa coleção em memória; um middleware terminal, aplicado às rotas do painel, lê a coleção e escreve `X-LiteSpeed-Purge` na resposta do `POST`.
- **Rota interna de purga.** O Observer (ou o job) faz uma requisição HTTP local para uma rota tipo `/__lscache/purge`, protegida por token e restrita a loopback, que devolve `204` com o cabeçalho de purga. Essa requisição precisa atravessar o LiteSpeed: host e porta do vhost, com o cabeçalho `Host` correto. Chamada direta ao PHP-FPM, ao `php artisan serve` ou a qualquer backend que não seja o vhost executa o código e emite o cabeçalho para ninguém, porque quem interpreta `X-LiteSpeed-Purge` é o servidor web. E o token vai em header, não em query string: query string entra na chave de cache e no log de acesso.

```php
<?php
// app/Observers/PostObserver.php  (exemplo)
namespace App\Observers;

use App\Models\Post;
use App\Support\LsPurgeBag;

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

    private function flag(Post $post): void
    {
        // tags, não URLs: sobrevivem a mudança de slug
        LsPurgeBag::add('post');
        LsPurgeBag::add('home');
        LsPurgeBag::add('catalogo');
    }
}
```

E o middleware terminal, aplicado ao painel:

```php
$tags = LsPurgeBag::all();   // ['post', 'home', 'catalogo']

if ($tags !== []) {
    $response->headers->set(
        'X-LiteSpeed-Purge',
        'public, ' . implode(', ', array_map(
            static fn (string $t): string => 'tag=' . $t,
            $tags
        ))
    );
    // valor final: public, tag=post, tag=home, tag=catalogo
}
```

O escopo `public` no início do valor não é decoração: sem ele a purga atinge apenas o cache privado, e as páginas emitidas com `public,max-age=N` continuam sendo servidas do disco até o TTL expirar. Purgue por tag, não por URL. Tag sobrevive a mudança de slug, a paginação e a rota com parâmetro. URL não.

### Purgar tudo a cada save é tão ruim quanto purgar de menos

Purgar tudo (`*`) a cada `save` transforma o cache em enfeite: o primeiro visitante depois de qualquer edição paga a renderização completa. Purgar de menos deixa conteúdo velho no ar até o TTL expirar. O meio-termo prático é tag por tipo de conteúdo mais tag por entidade (`post`, `post-142`), purgando as duas no `saved` e só a genérica quando a listagem muda de ordem.

## Confirmar miss e hit no curl, antes e depois

A verificação não é opcional, porque um middleware que silenciosamente nunca aciona é indistinguível de um que funciona, até alguém reclamar de conteúdo errado.

O estado da entrega aparece no cabeçalho de resposta `x-litespeed-cache`:

```bash
# 1) inspecionar os cabeçalhos da rota pública
curl -sSI https://exemplo.com.br/blog/meu-post | grep -i 'x-litespeed\|cache-control\|set-cookie'

# 2) primeira passada: espera-se miss
curl -s -o /dev/null -D - https://exemplo.com.br/blog/meu-post | grep -i x-litespeed-cache

# 3) segunda passada: espera-se hit
curl -s -o /dev/null -D - https://exemplo.com.br/blog/meu-post | grep -i x-litespeed-cache
```

Para o tempo até o primeiro byte do corpo, na mesma URL:

```bash
for i in 1 2 3 4 5; do
  curl -s -o /dev/null \
    -w '%{time_starttransfer} %{http_code}\n' \
    https://exemplo.com.br/blog/meu-post
done
```

Rode o laço uma vez logo após uma purga e outra vez com a página já em cache, e compare as duas séries. O número que interessa é a diferença entre as duas, no seu servidor, com o seu banco: qualquer valor publicado por terceiros (inclusive por nós) descreve outra máquina.

Checklist do que olhar em cada resposta:

| Sinal | Esperado em rota pública | Esperado em rota privada |
|---|---|---||
| `x-litespeed-cache` | `miss` e depois `hit` | ausente |
| `X-LiteSpeed-Cache-Control` emitido | `public,max-age=N` | `no-cache` |
| `Set-Cookie` | ausente | presente, se houver sessão |
| Conteúdo pessoal no HTML | nenhum | esperado |

O teste que pega o erro de verdade: faça login num navegador, copie o cookie de sessão e repita a requisição com `-b`. Se a resposta vier `hit` e com o nome do usuário no HTML, o middleware deixou passar uma rota que toca na sessão.

## Como desligar, e o que cache de página não resolve

O desligamento é barato, e isso deve ser parte do plano:

- remover o alias da rota faz a aplicação parar de emitir o cabeçalho, mas **não** apaga o que já está em cache. Para limpar, emita uma resposta com purga total ou limpe o diretório de cache no servidor;
- desabilitar o cache no nível do vhost mata tudo de uma vez, incluindo outras aplicações no mesmo host;
- enquanto houver entrada antiga válida, o TTL antigo continua valendo. Comece com TTL curto (alguns minutos) e só aumente depois de a purga estar comprovadamente funcionando.

Limites que vale conhecer antes de prometer resultado: página cacheada não executa PHP, logo contador de visitas, A/B test server-side e qualquer personalização server-side somem daquela rota. Se o conteúdo variar por país ou por dispositivo, isso precisa virar parte da chave de cache no servidor (vary), e não um `if` no controller, que não será executado no `hit`.

E a recomendação contra o próprio interesse: se a rota pública já responde rápido e o gargalo é uma consulta N+1 no painel administrativo, cache de página não resolve nada. Ligue o `DB::listen` ou o Telescope, encontre a consulta, corrija, e só então avalie se ainda precisa de cache de página.

