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.

Resposta curta: 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.
Neste artigo
- Método HTTP desalinhado entre servidor e aplicação é o que vaza sessão
- Regra no .htaccess que impede lookup fora de GET e HEAD
- Middleware que bloqueia por método, sessão autenticada, status e Set-Cookie
- Quais rotas podem entrar no cache e quais nunca podem
- Purge por tag disparado no observer do model, não no controller
- Como confirmar hit, miss e rota autenticada com curl
- Riscos conhecidos e como reverter sem perder dado
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).
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:
<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.
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
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. 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
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_listdeixa 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.
# 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:
/blogna segunda chamada semhit: oX-LiteSpeed-Cache-Controlprovavelmente não está chegando, ou a resposta carregaSet-Cookie. Rodecurl -sIcompleto e procure porset-cookie./painelcomhit: pare tudo. Alguma camada está cacheando sessão. Verifique se o middleware está no grupo correto e se a regra de URI do.htaccesscobre o prefixo.POSTcomhit: 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 dex-litespeed-cache: hit. Se o status for 405 (método não permitido) ou 419 (CSRF), o teste é inconclusivo: você provou que a rota rejeitaPOST, não que o cache o ignora. Escolha uma URL que aceitePOSTde verdade, com token CSRF válido ou rota isenta.- Para validar purge:
curl -sIna URL (esperehit), salve o post no painel, repita ocurle esperemissoutra 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.
OPTIONSde CORS não deve ser cacheado como página; ele cai fora do conjuntoGET/HEADe 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.
Referências
- Documentação oficial (litespeed) — LSCache for Laravel. Consultado em 2026-10-03.