# Cache de página no Laravel com LiteSpeed, sem plugin

Sem plugin, o controle fica no seu código: regras por rota, exclusão de sessão autenticada e purge programático por tag, verificados com curl.

> ativar cache de página no Laravel com LiteSpeed exige três peças: `CacheLookup on` no vhost ou .htaccess, um middleware que emite `X-LiteSpeed-Cache-Control` só em rotas GET públicas, e purge por tag via `X-LiteSpeed-Purge` disparado no Observer do model.

João Rizzon · 2026-10-22 · Infraestrutura web

---

## Sem plugin, quem decide o que é cacheável é o seu código

Em WordPress o LSCache resolve sozinho: o plugin decide o que é cacheável, injeta os headers e purga ao salvar um post. No Laravel não existe esse intermediário. O cache de página do LiteSpeed continua sendo o mesmo módulo do servidor, só que quem decide tudo é o seu código.

A divisão de responsabilidade fica assim:

| Camada | Quem configura | O que faz |
|---|---|---||
| vhost ou `.htaccess` | administrador do servidor | liga o `CacheLookup`, permitindo que o LiteSpeed sirva a resposta antes do PHP |
| middleware da aplicação | você | emite `X-LiteSpeed-Cache-Control` dizendo se aquela resposta pode ser guardada e por quanto tempo |
| Event/Observer do model | você | emite `X-LiteSpeed-Purge` para invalidar o que ficou velho |

Sem a primeira camada, os headers que o Laravel emite são ignorados. Sem a segunda, o LiteSpeed não guarda nada, porque o padrão é não cachear. Sem a terceira, você serve conteúdo desatualizado até o TTL expirar.

A documentação oficial do recurso está em [LSCache for Laravel](https://docs.litespeedtech.com/lscache/lsclaravel/), e é dela que vêm os nomes de header, o pacote e as opções de configuração citados aqui.

## Ligar o CacheLookup no vhost ou no .htaccess

O módulo de cache do LiteSpeed só olha para os headers da aplicação se a busca em cache estiver habilitada para aquele contexto. Em hospedagem compartilhada com LiteSpeed, isso costuma ser feito no `.htaccess` da raiz pública:

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

Em LiteSpeed Enterprise ou OpenLiteSpeed com acesso ao painel de administração, a mesma diretiva existe no nível de virtual host. O bloco `<IfModule LiteSpeed>` é importante: em Apache puro a diretiva não existe e o arquivo quebraria.

Cuidado com a ordem no `.htaccess` do Laravel. O bloco acima pode ficar antes do `RewriteEngine On` padrão do framework; ele não interfere no rewrite. O que você não deve fazer é colocar regras de cache dentro do bloco de rewrite esperando que elas sejam avaliadas por rota, porque o controle fino vem dos headers, não do rewrite.

### Confirmar com curl se o LiteSpeed está consultando o cache

Depois de salvar o arquivo, uma requisição a qualquer URL pública deve trazer o header `x-litespeed-cache`. Se ele não aparece nem como `miss`, a busca em cache não está ligada ou o servidor não é LiteSpeed:

```bash
curl -sIk https://seusite.com.br/ | grep -i 'x-litespeed\|server'
```

## Emitir X-LiteSpeed-Cache-Control só em rotas GET públicas

O pacote oficial para Laravel é instalado via Composer e traz um middleware e um helper de tags. Segundo a documentação do LSCache for Laravel, o fluxo é instalar o pacote, publicar a configuração e registrar o middleware:

```bash
composer require litespeed/lscache-laravel
php artisan vendor:publish --provider="Litespeed\LSCache\LSCacheServiceProvider"
```

Sobre versões: o pacote não acompanha o ciclo de release do Laravel, então confira o que de fato entrou antes de subir. `composer show litespeed/lscache-laravel` mostra a versão instalada e a faixa declarada em `require` (é lá que está o `illuminate/support` aceito, e não na documentação). `php artisan --version` mostra o seu lado. Se a faixa não cobrir seu framework, o header é o mesmo texto: dá para abandonar o pacote e ficar com o middleware próprio mostrado abaixo, que não tem dependência nenhuma.

Do lado do servidor, o módulo de cache existe no LiteSpeed Enterprise e no OpenLiteSpeed. No OLS ele é um módulo que precisa estar carregado e com cache habilitado no contexto do vhost; sem isso o `CacheLookup` não tem efeito. Confirme a edição e a build com `/usr/local/lsws/bin/lshttpd -v` (ou o header `server` na resposta, em compartilhada).

O middleware traduz a configuração em um header `X-LiteSpeed-Cache-Control` na resposta. Se você prefere não depender do pacote, o header pode ser emitido direto por um middleware seu. O conteúdo é o mesmo:

```php
// app/Http/Middleware/LSCachePublic.php
public function handle($request, Closure $next)
{
    $response = $next($request);

    if ($request->isMethod('GET') && $response->getStatusCode() === 200) {
        $response->headers->set('X-LiteSpeed-Cache-Control', 'public,max-age=300');
    }

    return $response;
}
```

Aplique esse middleware por grupo de rota, nunca global. O padrão seguro é o oposto do intuitivo: nada é cacheável até você dizer que é.

```php
Route::middleware('lscache.public')->group(function () {
    Route::get('/', [PageController::class, 'home']);
    Route::get('/blog/{slug}', [PostController::class, 'show']);
});
```

### Rotas que nunca podem entrar no grupo cacheável

- `/login`, `/register`, `/password/*` e qualquer rota que devolva formulário com token CSRF. Servir um `_token` em cache gera 419 Page Expired para o visitante seguinte.
- `/admin` e todo painel atrás de `auth`.
- `/cart`, `/checkout` e páginas que mudam por usuário.
- `/api/*`, se a resposta depende de token no header. Cache de página por URL não enxerga `Authorization`.
- Qualquer rota com `POST`, `PUT`, `PATCH` ou `DELETE`, por definição.

Um segundo filtro barato evita acidente: se a sessão tem usuário autenticado, não marque como cacheável, mesmo que a rota esteja no grupo.

```php
if (auth()->check()) {
    $response->headers->set('X-LiteSpeed-Cache-Control', 'no-cache');
    return $response;
}
```

Cache privado por sessão existe no LSCache e é controlado por `private` no mesmo header, mas ele muda o modelo de invalidação e o consumo de memória. Comece por público e anônimo. É onde está o ganho e onde o risco é menor.

## Purgar por tag no Observer do model em vez de encurtar o TTL

TTL curto é um remendo. O jeito correto é marcar a resposta com tags e purgar a tag quando o dado muda.

A tag precisa sair da camada que conhece o model, e não do middleware genérico. No controller, onde o registro já está carregado:

```php
// app/Http/Controllers/PostController.php
public function show(string $slug)
{
    $post = Post::where('slug', $slug)->firstOrFail();

    return response()
        ->view('post.show', ['post' => $post])
        ->header('X-LiteSpeed-Cache-Control', 'public,max-age=300')
        ->header('X-LiteSpeed-Tag', 'post_' . $post->id . ',blog_index');
}
```

Se você quiser manter a emissão no middleware, derive o identificador do route model binding em vez de supor uma variável no escopo:

```php
// dentro do handle(), depois de $response = $next($request);
$post = $request->route('post'); // instância do model com binding, ou o parâmetro cru

if ($post instanceof \App\Models\Post) {
    $response->headers->set('X-LiteSpeed-Tag', 'post_' . $post->getKey() . ',blog_index');
}
```

Com rota declarada como `/blog/{slug}` e sem binding, `$request->route('slug')` devolve a string, e a tag teria que usar o slug. Escolha um dos dois e mantenha o mesmo formato no purge, porque tag com nome diferente não invalida nada.

No Observer do model, emita o purge. O header `X-LiteSpeed-Purge` precisa sair em uma resposta HTTP que passe pelo LiteSpeed, então o lugar natural é a própria resposta da ação administrativa que salvou o registro:

```php
// app/Observers/PostObserver.php
public function saved(Post $post)
{
    session()->flash('lscache_purge', 'tag=post_' . $post->id . ',tag=blog_index');
}
```

```php
// middleware que roda em todas as respostas do painel
if ($purge = session()->pull('lscache_purge')) {
    $response->headers->set('X-LiteSpeed-Purge', $purge);
}
```

Para jobs em fila e comandos Artisan não há resposta HTTP. Duas saídas: purgar por `*` em uma rota interna protegida que você chama ao final do job, ou aceitar o TTL como piso de atualização para conteúdo gerado em background. Diga isso em voz alta no seu README, porque é o detalhe que depois vira bug difícil.

| Valor de X-LiteSpeed-Purge | Efeito |
|---|---||
| `*` | limpa todo o cache do vhost |
| `tag=blog_index` | limpa só as respostas marcadas com essa tag |
| `tag=post_42,tag=blog_index` | limpa as duas tags em uma única resposta |

## Testar miss contra hit na mesma URL usando GET, não HEAD

A verificação não depende de ferramenta nova. Duas requisições na mesma URL, olhando um header e um tempo.

```bash
URL=https://seusite.com.br/blog/meu-post

curl -sk -D - -o /dev/null "$URL" | grep -i x-litespeed-cache
curl -sk -D - -o /dev/null "$URL" | grep -i x-litespeed-cache
```

Use GET, não HEAD. `curl -I` envia HEAD, e a entrada de cache que interessa é a do GET: dependendo da configuração, HEAD pode não popular nem consultar a mesma entrada, e você fica olhando `miss` eterno sem motivo. Por isso `-D -` com `-o /dev/null`: faz GET de verdade, imprime os headers e descarta o corpo.

A primeira deve responder `x-litespeed-cache: miss` e a segunda `x-litespeed-cache: hit`. Se as duas dão `miss`, o header de cache-control não está chegando, a rota caiu fora do grupo, ou a resposta sai com `Set-Cookie` do cookie de sessão: por padrão o LSCache não armazena resposta que carrega `Set-Cookie`, e o resultado é `miss` permanente. Confirme com `curl -sk -D - -o /dev/null "$URL" | grep -i 'set-cookie'`. Se nenhuma traz o header, volte para o `CacheLookup`.

Para comparar tempo, use `-w` e meça o mesmo campo nas duas chamadas:

```bash
curl -sk -o /dev/null -w 'ttfb=%{time_starttransfer}s total=%{time_total}s\n' "$URL"
```

O `time_starttransfer` é o intervalo do início da requisição até o primeiro byte do corpo, incluindo DNS, conexão e TLS. Rode da mesma máquina, na mesma rede, várias vezes, e compare miss contra hit. Os números que você vai ver são seus, da sua conexão e do seu servidor: não existe valor de referência universal, e qualquer tempo citado em artigo serve de ilustração, não de meta.

Para isolar rede do servidor, repita de dentro da máquina contra `127.0.0.1` com `--resolve`:

```bash
curl -sk --resolve seusite.com.br:443:127.0.0.1 \
  -o /dev/null -w '%{time_starttransfer}\n' "$URL"
```

## Set-Cookie, CSRF, query string e deploy, as armadilhas do Laravel

**Cookie de sessão em rota anônima.** O Laravel envia `Set-Cookie` com o cookie de sessão em muitas respostas. Na configuração padrão isso não vira vazamento, vira `miss` eterno: o LSCache se recusa a armazenar a resposta. O vazamento aparece quando essa proteção é contornada, por exemplo com regra de cache que manda ignorar cookies, ou quando o cookie é emitido por outra camada depois do armazenamento (proxy, CDN ou edge à frente do LiteSpeed). Nos dois casos o sintoma é o mesmo: uma resposta guardada carregando sessão de outra pessoa. Nas rotas cacheáveis, mantenha o middleware `StartSession` fora do grupo quando a página não precisa de sessão, ou garanta que nada escreva na sessão ali.

**CSRF em formulário público.** Newsletter, busca e comentário em página cacheada quebram, porque o token servido pertence a outra sessão. Converta esses formulários para envio via JavaScript buscando o token em um endpoint não cacheável, ou deixe a página fora do cache.

**Query string.** O LSCache diferencia URLs por query string. Parâmetros de campanha multiplicam entradas de cache para o mesmo conteúdo. Vale medir se isso é problema no seu volume antes de criar regra.

**Deploy.** Depois de um deploy que muda template ou assets, purgue tudo. Uma rota administrativa que devolve 204 com `X-LiteSpeed-Purge: *`, chamada no final do pipeline, resolve.

**Reversão.** Se algo der errado em produção, a reversão é comentar o `CacheLookup` no `.htaccess`, ou trocar o header do middleware para `no-cache` e purgar com `*`. O efeito é imediato na próxima requisição; não há cache a esperar expirar.

## Checklist de 10 itens antes de liberar em produção

- `CacheLookup on` presente dentro de `<IfModule LiteSpeed>`.
- Middleware aplicado por grupo de rota, nunca global.
- Apenas `GET` com status 200 marcados como cacheáveis.
- `auth()->check()` força `no-cache`.
- `/login`, `/register`, `/admin`, `/cart`, `/checkout` e `/api/*` fora do grupo.
- Nenhuma rota cacheável emite `Set-Cookie`.
- Tags emitidas na resposta e purgadas no Observer do model.
- `curl -sk -D - -o /dev/null` mostra `miss` seguido de `hit` na mesma URL.
- Purge total no final do deploy.
- Teste manual logado e deslogado na mesma URL, confirmando que o conteúdo não vaza entre os dois.

O item 10 é o que mais costuma ser pulado e o único que tem consequência séria. Faça em aba anônima, com a sessão real aberta em outra janela.

