blog
Infraestrutura web

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.

JR · · 8 min de leitura · 2 tabelas · 6 blocos de código

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
  1. Os três cabeçalhos com que o LiteSpeed decide guardar a página
  2. Por que allowlist, e o que uma blocklist esquecida vaza
  3. Middleware que só emite public,max-age em resposta anônima
  4. Purga por tag disparada pelo Observer do Eloquent
  5. Confirmar miss e hit no curl, antes e depois
  6. 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:

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.

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:

  1. remover o Set-Cookie da resposta no middleware quando ela for marcada como cacheável;
  2. 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 (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:

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

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

  1. Documentação oficial (litespeed) — LSCache for Laravel. Consultado em 2026-10-03.
Leia também