blog
Infraestrutura web

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.

JR · · 7 min de leitura · 1 tabela · 4 blocos de código

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
  1. Método HTTP desalinhado entre servidor e aplicação é o que vaza sessão
  2. Regra no .htaccess que impede lookup fora de GET e HEAD
  3. Middleware que bloqueia por método, sessão autenticada, status e Set-Cookie
  4. Quais rotas podem entrar no cache e quais nunca podem
  5. Purge por tag disparado no observer do model, não no controller
  6. Como confirmar hit, miss e rota autenticada com curl
  7. 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.

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:

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.

Ordem das quatro condicoes no middlewareMetodo e GET ou HEAD?Nao: emite no-cacheUsuario autenticado na sessao?Sim: emite no-cacheStatus da resposta e 200?Nao: emite no-cacheResposta carrega Set-Cookie?Sim: emite no-cacheEmite public,max-age e tagTag vai em X-LiteSpeed-Tag

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:

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:

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:

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

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