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.

Resposta curta: 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.
Neste artigo
- Os três cabeçalhos com que o LiteSpeed decide guardar a página
- Por que allowlist, e o que uma blocklist esquecida vaza
- Middleware que só emite public,max-age em resposta anônima
- Purga por tag disparada pelo Observer do Eloquent
- Confirmar miss e hit no curl, antes e depois
- Como desligar, e o que cache de página não resolve
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 (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:sanctumou 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
VerifyCsrfTokendo 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
// 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:
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-Cookieda resposta no middleware quando ela for marcada como cacheável; - definir um grupo de middleware enxuto para rotas públicas, sem
StartSessione semVerifyCsrfToken, deixandowebpara 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 (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-Purgena resposta doPOST. - 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 devolve204com o cabeçalho de purga. Essa requisição precisa atravessar o LiteSpeed: host e porta do vhost, com o cabeçalhoHostcorreto. Chamada direta ao PHP-FPM, aophp artisan serveou a qualquer backend que não seja o vhost executa o código e emite o cabeçalho para ninguém, porque quem interpretaX-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
// 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:
$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:
# 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:
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.
Referências
- Documentação oficial (litespeed) — LSCache for Laravel. Consultado em 2026-10-03.