# LSCache no Laravel: quais rotas nunca podem ser cacheadas

Como alinhar .htaccess, middleware e purge no mesmo conjunto de métodos cacheáveis, e verificar com curl que nenhuma rota autenticada entrou no cache.

> neste guia, cacheável é só GET e HEAD, e as três camadas (regra no .htaccess, middleware PHP e purge) precisam usar esse mesmo conjunto. O LiteSpeed permite configurar cache de resposta a POST, por isso a restrição tem de ser explícita em cada camada.

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

---

## Método HTTP desalinhado entre servidor e aplicação é o que vaza sessão

Cache de página em LiteSpeed acontece em dois lugares que precisam concordar. O servidor decide **se vai olhar o cache** (regra no `.htaccess`, diretiva `CacheLookup`). A aplicação decide **se aquela resposta pode ser guardada** (cabeçalho `X-LiteSpeed-Cache-Control`, emitido pelo middleware do pacote LSCache for Laravel, conforme a [documentação oficial da LiteSpeed](https://docs.litespeedtech.com/lscache/lsclaravel/)).

Quando as duas camadas usam conjuntos de métodos diferentes, o resultado não é só cache ruim: é resposta de um usuário entregue a outro. O caso clássico é o servidor fazer lookup em `POST` ou em qualquer método, enquanto o middleware só se preocupa com `GET`. Ou o inverso: o middleware marca `public` sem checar o método, e uma resposta de `POST` com `Set-Cookie` de sessão entra no objeto de cache.

A regra deste guia é uma só, aplicada nas três camadas: **cacheável é `GET` e `HEAD`. Nada mais.** `POST`, `PUT`, `PATCH`, `DELETE` e `OPTIONS` nunca são lidos do cache nem armazenados. Isso é decisão de projeto, não limite do servidor: o LiteSpeed suporta cache de resposta a `POST` mediante configuração, e é justamente por isso que a restrição precisa estar escrita nas três camadas, em vez de ser presumida. O purge, que é a terceira camada, também só faz sentido para o que foi gravado sob essa mesma regra.

## Regra no .htaccess que impede lookup fora de GET e HEAD

A ativação do cache é feita pelo bloco de módulo do LiteSpeed. Exemplo mínimo, no `.htaccess` da pasta `public/` do projeto:

```apache
<IfModule LiteSpeed>
  CacheLookup on
</IfModule>

# Nunca faz lookup fora de GET/HEAD
RewriteEngine On
RewriteCond %{REQUEST_METHOD} !^(GET|HEAD)$
RewriteRule .* - [E=Cache-Control:no-cache]

# Rotas que nunca passam pelo cache, mesmo em GET
RewriteCond %{REQUEST_URI} ^/(login|logout|register|password|admin|painel|carrinho|checkout|api)(/|$) [NC]
RewriteRule .* - [E=Cache-Control:no-cache]
```

Dois pontos importantes. Primeiro: `CacheLookup on` liga o mecanismo, mas quem autoriza o armazenamento continua sendo a resposta da aplicação. Segundo: a variável de ambiente `Cache-Control:no-cache` é a forma documentada de desligar o cache por requisição no nível do servidor, e ela é a sua rede de segurança caso o middleware deixe de rodar (por exemplo, um grupo de middleware que você esqueceu de registrar).

Trate esse bloco de URIs como lista de bloqueio **redundante**, não como a defesa principal. A defesa principal está no PHP, porque só o PHP sabe se há sessão autenticada.

## Middleware que bloqueia por método, sessão autenticada, status e Set-Cookie

O pacote é o `litespeed/lscache-laravel` (testado na série 1.x), em Laravel 10.x e 11.x, com LiteSpeed Enterprise 6.x ou OpenLiteSpeed 1.8.x. Ele expõe o middleware que escreve `X-LiteSpeed-Cache-Control` na resposta e as tags em `X-LiteSpeed-Tag`. O valor típico do primeiro é `public,max-age=N` para cachear e `no-cache` para não cachear. A referência dos valores e dos nomes de cabeçalho é a [documentação do LSCache for Laravel](https://docs.litespeedtech.com/lscache/lsclaravel/).

O exemplo abaixo **substitui** o middleware do pacote: ele concentra a decisão de cacheabilidade, as tags e o purge em um ponto só. Se você usar o middleware do pacote, não empilhe os dois na mesma rota.

Exemplo de middleware próprio (exemplo ilustrativo, adapte os nomes de rota ao seu projeto):

```php
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class LsCacheGate
{
    private const CACHEABLE_METHODS = ['GET', 'HEAD'];

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

        // Purge acumulado pelos observers: vale para qualquer resposta,
        // inclusive POST/PUT, que caem no ramo no-cache logo abaixo.
        if ($purge = $request->attributes->get('lscache_purge')) {
            $response->headers->set('X-LiteSpeed-Purge', $purge);
        }

        if (! in_array($request->getMethod(), self::CACHEABLE_METHODS, true)
            || $request->user() !== null
            || $response->getStatusCode() !== 200
            || $response->headers->has('Set-Cookie')) {
            $response->headers->set('X-LiteSpeed-Cache-Control', 'no-cache');
            return $response;
        }

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

        // Tags vão no cabeçalho próprio, nunca dentro do Cache-Control.
        $tags = $request->attributes->get('lscache_tags', []);
        if ($tags) {
            $response->headers->set('X-LiteSpeed-Tag', implode(',', $tags));
        }

        return $response;
    }
}
```

As quatro condições de bloqueio existem por motivos distintos, e nenhuma substitui a outra:

- **Método fora de `GET`/`HEAD`**: espelha exatamente a regra do `.htaccess`.
- **`$request->user() !== null`**: resposta renderizada com sessão autenticada nunca é pública, mesmo que o HTML pareça igual ao do visitante anônimo.
- **Status diferente de 200**: evita gravar 302 de redirecionamento de login e páginas de erro transitórias.
- **Presença de `Set-Cookie`**: um cookie de sessão ou de CSRF dentro de um objeto de cache público é o vazamento mais direto que existe nesse tipo de arquitetura.

Registre o middleware no grupo `web` apenas, nunca no grupo `api`. Repare na ordem dentro do `handle`: o purge é escrito antes do ramo `no-cache`, senão ele nunca sairia, já que toda escrita chega por `POST`/`PUT`/`DELETE`. E repare que `tag=` não é diretiva de `X-LiteSpeed-Cache-Control`: a tag viaja em `X-LiteSpeed-Tag`, conforme a [documentação do LSCache for Laravel](https://docs.litespeedtech.com/lscache/lsclaravel/). Tag escrita dentro do `Cache-Control` é ignorada, e o purge por tag não casa com objeto nenhum.

## Quais rotas podem entrar no cache e quais nunca podem

| Rota (exemplo) | Métodos tratados | Cacheável | Motivo |
|---|---|---|---||
| `/` | GET, HEAD | Sim | Conteúdo público, igual para todo visitante anônimo |
| `/blog`, `/blog/{slug}` | GET, HEAD | Sim | Conteúdo público versionado por tag de model |
| `/produtos/{id}` | GET, HEAD | Sim, TTL curto | Preço e estoque mudam; use purge por tag |
| `/busca?q=` | GET | Caso a caso | Cardinalidade alta de query string infla o armazenamento |
| `/login`, `/register`, `/password/*` | GET, POST | Não | Emite token CSRF e cookie de sessão |
| `/admin/*`, `/painel/*` | todos | Não | Sessão autenticada por definição |
| `/carrinho`, `/checkout` | todos | Não | Estado por usuário, mesmo sem login formal |
| `/api/*` | todos | Não | Resposta por token; trate com cache de aplicação, não de página |
| Qualquer rota com `auth` no middleware | todos | Não | Regra automática, não depende de lista manual |
| `POST`/`PUT`/`PATCH`/`DELETE` em qualquer URI | todos | Não | Fora do conjunto cacheável |

A última linha de `auth` vale mais que todas as anteriores: se o seu critério for "a rota tem middleware de autenticação", a lista de exclusão se mantém sozinha conforme o projeto cresce. Listas de URI escritas à mão envelhecem mal.

## Purge por tag disparado no observer do model, não no controller

Marcar a resposta com `tag=` só serve se alguém emitir o purge daquela tag. O caminho documentado é o cabeçalho `X-LiteSpeed-Purge` na resposta, com `tag=` ou `*` para limpar tudo.

O lugar certo de disparar isso é o ciclo de vida do model, não o controller. Exemplo com um observer:

```php
<?php

namespace App\Observers;

use App\Models\Post;
use Illuminate\Support\Facades\Cache;

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

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

    private function purge(Post $post): void
    {
        $tags = 'tag=post_' . $post->id . ',tag=post_list';

        // app('request') só existe em contexto HTTP. Em artisan, job ou
        // worker a Request é descartável (ou nem existe): a tag iria para
        // o lixo. Nesses casos, enfileire no cache de aplicação.
        if (app()->runningInConsole()) {
            $pendentes = Cache::get('lscache_purge_queue', []);
            $pendentes[] = $tags;
            Cache::forever('lscache_purge_queue', array_unique($pendentes));
            return;
        }

        app('request')->attributes->set('lscache_purge', $tags);
    }
}
```

A fila `lscache_purge_queue` é consumida pelo endpoint interno protegido citado abaixo: ele lê as tags pendentes, emite `X-LiteSpeed-Purge` na própria resposta e limpa a chave. O middleware da Camada 2 já aplica o atributo `lscache_purge` em qualquer resposta, inclusive nas de escrita, então não há segundo trecho de código para colar.

Dois cuidados que a maioria dos tutoriais omite:

- **O purge só viaja em uma resposta HTTP.** Uma alteração feita em `php artisan`, em job de fila ou em worker não tem resposta onde pendurar o cabeçalho. Para esses casos, concentre a invalidação em um endpoint interno protegido que a aplicação chama, ou aceite que o TTL vai expirar sozinho.
- **Emita tanto a tag do item quanto a tag da listagem.** Atualizar o post 42 sem limpar `post_list` deixa o índice do blog mostrando o título antigo até o TTL vencer.

## Como confirmar hit, miss e rota autenticada com curl

A leitura que importa é o cabeçalho `x-litespeed-cache`, com valor `hit` ou `miss`. Primeira requisição em uma URL nova costuma responder `miss`; a seguinte, `hit`.

```bash
# 1) aquece e observa
curl -sI https://exemplo.com.br/blog | grep -i -E 'x-litespeed|cache-control'

# 2) repete e espera hit
curl -sI https://exemplo.com.br/blog | grep -i x-litespeed-cache

# 3) prova que POST nao e cacheado (use uma URL que aceite POST)
curl -s -D- -o /dev/null -X POST https://exemplo.com.br/newsletter | \
  grep -i -E 'HTTP/|x-litespeed-cache'

# 4) prova que rota autenticada nao e cacheada
curl -sI -b cookies.txt https://exemplo.com.br/painel | grep -i x-litespeed
```

Checklist de leitura:

- `/blog` na segunda chamada sem `hit`: o `X-LiteSpeed-Cache-Control` provavelmente não está chegando, ou a resposta carrega `Set-Cookie`. Rode `curl -sI` completo e procure por `set-cookie`.
- `/painel` com `hit`: pare tudo. Alguma camada está cacheando sessão. Verifique se o middleware está no grupo correto e se a regra de URI do `.htaccess` cobre o prefixo.
- `POST` com `hit`: a condição de método não está sendo avaliada, ou há proxy intermediário respondendo antes do LiteSpeed. O esperado no item 3 é ausência de `x-litespeed-cache: hit`. Se o status for 405 (método não permitido) ou 419 (CSRF), o teste é inconclusivo: você provou que a rota rejeita `POST`, não que o cache o ignora. Escolha uma URL que aceite `POST` de verdade, com token CSRF válido ou rota isenta.
- Para validar purge: `curl -sI` na URL (espere `hit`), salve o post no painel, repita o `curl` e espere `miss` outra vez.

## Riscos conhecidos e como reverter sem perder dado

O maior risco não é cache frio, é cache quente com conteúdo errado. Antes de ligar em produção:

- Teste com um usuário real logado e um anônimo, nas mesmas URLs, em janelas separadas.
- Confira se o seu layout imprime nome de usuário, carrinho ou token CSRF em páginas públicas. Se imprime, essa página não é pública: ou você remove o trecho, ou carrega via requisição separada não cacheada, ou tira a rota do cache.
- `OPTIONS` de CORS não deve ser cacheado como página; ele cai fora do conjunto `GET`/`HEAD` e já está coberto.

Reversão é simples e vale deixar ensaiada: comente `CacheLookup on` no `.htaccess` e emita um purge total (`X-LiteSpeed-Purge: *`) em uma rota administrativa, ou limpe pelo painel do servidor. O estado volta a ser idêntico ao de antes, sem migração nem perda de dado, porque o cache de página é descartável por natureza.

E a recomendação que contraria o apelo de "ligar cache e pronto": se a sua aplicação é majoritariamente autenticada, cache de página entrega pouco. O ganho, nesse caso, costuma estar em query lenta, em `N+1` de Eloquent e em cache de aplicação (`Cache::remember`), não em `X-LiteSpeed-Cache-Control`. Meça o tempo de resposta do PHP antes de decidir que o problema é entrega de HTML.

