claude-plugins/wordpress/skills/wp-fastest-cache/SKILL.md

---
name: wp-fastest-cache
description: Gestão completa do WP Fastest Cache (page cache HTML local) via WP-CLI em servidores CWP. Cobre purga de cache nativa (`wp fastest-cache clear`), diferença entre page cache (WPFC) e object cache (Redis), preload após publicar, minify HTML/CSS/gzip, exclusão de páginas/cookies/user-agents, Clearing Specific Pages, integração CDN (Cloudflare/MaxCDN/genérica) e Varnish, customização do caminho da cache, matriz Free vs Premium, e sequência de purga completa (WPFC + Cloudflare) após deploys ou mudanças de config. Usar quando "wp fastest cache", "wpfc", "purgar cache", "limpar cache wordpress", "cache não actualiza", "preload cache", "minify html", "combine css", "gzip wordpress", "excluir página cache", "cache timeout", "cdn wordpress", "clearing specific pages", "varnish wordpress".
---

# /wp-fastest-cache — Gestão do WP Fastest Cache via WP-CLI

Page cache local (HTML estático em disco) do bundle de performance WP
Descomplicar®. Complementa (não substitui) o Redis Object Cache e o
App for Cloudflare® — os três operam em camadas diferentes, ver §3.

**Fonte:** leitura completa do código-fonte v1.5.0 (versão **Free** — sem
`wp-fastest-cache-premium/` instalado) no servidor `server.descomplicar.pt`,
porta 9443, site piloto `emanuelalmeida.pt`: `wpFastestCache.php` (2746
linhas), `inc/admin.php` (2620 linhas), `inc/cache.php` (1460 linhas),
`inc/preload.php` (894 linhas), `inc/css-utilities.php` (766 linhas),
`inc/cdn.php` (650 linhas), `inc/js-utilities.php` (340 linhas),
`inc/single-preload.php` (346 linhas), `inc/varnish.php` (177 linhas),
`inc/admin-toolbar.php`, `inc/clearing-specific-pages.php`, `inc/column.php`,
`inc/wp-polls.php`, `inc/cli.php`, `uninstall.php`, e todos os templates em
`templates/` (`exclude.php`, `timeout.php`, `preload.php`, `cache_path.php`,
`varnish.php`, `toolbar_settings.php`, `disable_wp_cron.php`,
`clearing_specific_pages.php`, `cdn/cloudflare.php`, `cdn/maxcdn.php`,
`cdn/other.php`, `cdn/file_types.php`, `cdn/specify_sources.php`,
`cdn/exclude_sources.php`) + `CONFIG-Plugins-Referencia.md` §3 +
`BUNDLE-Excelencia-WP.md` §2.2/§2.4 + verificação ao vivo de todas as
`wp_options` prefixadas `WpFastestCache*` via SSH em `emanuelalmeida.pt`,
16-08-2026.

---

## Contexto CWP — sempre obrigatório

```bash
PATH=/home/USER/public_html
wp <comando> --allow-root --path=$PATH
```

**Acesso via SSH:** `ssh server "sudo -u USER /usr/local/bin/wp <comando> --path=$PATH --format=json"`
(alias `server` já configurado; user/path variam por site — ver tabela de
sites de referência no topo desta sessão).

---

## 1. Config real — `wp_options.WpFastestCache` (JSON serializado)

Não existe API `wp option patch` dedicada a este plugin de forma prática —
a option é um objecto JSON simples (não serializado PHP), por isso
**`wp option update` com `--format=json` funciona directamente** (ao
contrário do Rank Math, que usa arrays PHP serializados e exige
`wp option patch`). Internamente, `saveOption()` (`inc/admin.php`) faz
`json_encode($_POST)` do formulário inteiro — ou seja, a option guarda
**exactamente** o subconjunto de checkboxes que estava marcado no momento
de gravar, nunca chaves "off" explícitas (chave ausente = desligada).

```bash
# Ler a config completa
wp option get WpFastestCache --format=json --allow-root --path=$PATH
```

Valor real verificado ao vivo em `emanuelalmeida.pt` (16-08-2026):

```json
{
  "wpFastestCacheStatus": "on",
  "wpFastestCachePreload": "on",
  "wpFastestCachePreload_number": "4",
  "wpFastestCacheLoggedInUser": "on",
  "wpFastestCacheMobile": "on",
  "wpFastestCacheMobileTheme": "on",
  "wpFastestCacheNewPost": "on",
  "wpFastestCacheMinifyHtml": "on",
  "wpFastestCacheMinifyCss": "on",
  "wpFastestCacheCombineCss": "on",
  "wpFastestCacheGzip": "on",
  "wpFastestCacheLBC": "on",
  "wpFastestCacheDisableEmojis": "on"
}
```

| Chave | Valor | O que faz |
|---|---|---|
| `wpFastestCacheStatus` | `on` | Liga a cache HTML (interruptor mestre) |
| `wpFastestCachePreload` + `wpFastestCachePreload_number` | `on`, `4` threads | Regenera a cache automaticamente (crawl interno) em vez de esperar pela primeira visita — `4` = threads paralelas do crawler |
| `wpFastestCacheLoggedInUser` | `on` | Serve cache também a utilizadores autenticados (o plugin exclui automaticamente páginas com nonce/admin-bar dinâmicos, não quebra o WP admin) |
| `wpFastestCacheMobile` | `on` | **Free.** Não serve a versão desktop cacheada a dispositivos móveis (cache mobile separada da desktop, ficheiro próprio em `/cache/wpfc-mobile-cache`) |
| `wpFastestCacheMobileTheme` | `on` | **⚠ Só tem efeito com o addon Premium activo** (gate `class_exists("WpFastestCachePowerfulHtml")` em `inc/admin.php:1233`). Neste site a chave está gravada no JSON mas **é ignorada em runtime** porque `wp-fastest-cache-premium/` não está instalado — ver §13 |
| `wpFastestCacheNewPost` | `on` | Limpa a cache automaticamente ao publicar/actualizar conteúdo |
| `wpFastestCacheMinifyHtml` | `on` | Minifica HTML na saída |
| `wpFastestCacheMinifyCss` + `wpFastestCacheCombineCss` | `on` | Minifica e combina ficheiros CSS num único ficheiro |
| `wpFastestCacheGzip` | `on` | Comprime a resposta com gzip |
| `wpFastestCacheLBC` | `on` | Lazy Browser Caching — envia headers `Expires`/`Cache-Control` de longa duração para assets estáticos |
| `wpFastestCacheDisableEmojis` | `on` | Ver §5 |

### 1.1 Todas as chaves possíveis da option `WpFastestCache` (mapeadas do código-fonte)

Lista completa extraída de `grep -roh "wpFastestCache[A-Za-z_]*"` a todo o
código-fonte (`wpFastestCache.php`, `inc/*.php`, `templates/**/*.php`) —
não apenas as 13 activas neste site. Cada chave corresponde a um
`name="..."` de formulário que, quando marcado, é gravado via
`saveOption()`.

**Disponíveis na versão Free (sem gate `class_exists("WpFastestCachePowerfulHtml")`):**

| Chave | Free | O que faz |
|---|---|---|
| `wpFastestCacheStatus` | ✅ | Master switch da cache HTML |
| `wpFastestCachePreload` | ✅ | Preload automático (crawler) — ver §6 |
| `wpFastestCachePreload_number` | ✅ | Nº de threads paralelas do crawler de preload |
| `wpFastestCacheLoggedInUser` | ✅ | Não serve cache a utilizadores autenticados |
| `wpFastestCacheMobile` | ✅ | Cache mobile separada (ficheiros próprios, não é "tema mobile") |
| `wpFastestCacheNewPost` | ✅ | Limpa cache ao publicar |
| `wpFastestCacheNewPost_type` / `_type_all` / `_type_homepage` | ✅ | Âmbito da limpeza ao publicar — só a página nova, ou tudo, ou também a homepage (`templates/newpost.php`) |
| `wpFastestCacheUpdatePost` | ✅ | Limpa cache ao actualizar um post/página existente |
| `wpFastestCacheUpdatePost_type` / `_type_all` / `_type_post` | ✅ | Âmbito da limpeza ao actualizar (`templates/updatepost.php`) |
| `wpFastestCacheMinifyHtml` | ✅ | Minifica HTML |
| `wpFastestCacheMinifyCss` | ✅ | Minifica CSS |
| `wpFastestCacheCombineCss` | ✅ | Combina ficheiros CSS |
| `wpFastestCacheGzip` | ✅ | Gzip |
| `wpFastestCacheLBC` | ✅ | Leverage Browser Caching (headers de expiração) |
| `wpFastestCacheDisableEmojis` | ✅ | Remove script/CSS de emoji do WP core — ver §5 |
| `wpFastestCacheWidgetCache` | ✅ (link de doc é premium, mas o campo em si não está gated no template lido) | Cache de widgets para reduzir queries SQL — **confirmar no wp-admin**, o link de ajuda aponta para a página de marketing Premium mas o checkbox aparece fora do bloco `class_exists` no ficheiro `templates/` correspondente |
| `wpFastestCacheLanguage` | ✅ | Idioma da interface de admin do plugin (select, não afecta o frontend) |
| `wpFastestCachePage` | ✅ (interno) | Campo hidden do formulário que identifica qual sub-página foi submetida (`options`, `deleteCache`, `deleteCssAndJsCache`, `cacheTimeout`) — nunca persiste na option guardada |
| `wpFastestCacheTimeOut` / `_TimeOutHour` / `_TimeOutMinute` | ✅ | Cache Timeout **global legado** (1 única regra, agenda `wp_schedule_event` no hook `wp_fastest_cache`) — não confundir com o Cache Timeout Wizard (§8, `WpFastestCacheExclude`-like, guardado via `wp_fastest_cache_N`) |

**Só têm efeito com `wp-fastest-cache-premium/wpFastestCachePremium.php` activo (gate `class_exists("WpFastestCachePowerfulHtml")` em `inc/admin.php`) — neste site NÃO instalado, ver §13:**

| Chave | O que faria (Premium) |
|---|---|
| `wpFastestCacheMobileTheme` + `_themename` | Cache de um tema mobile dedicado (Mobile Cache) |
| `wpFastestCacheMinifyHtmlPowerFul` | Minificação de HTML mais agressiva ("Minify HTML Plus") |
| `wpFastestCacheMinifyCssPowerFul` | Minificação de CSS mais agressiva ("Minify Css Plus") |
| `wpFastestCacheMinifyJs` | Minifica ficheiros JS |
| `wpFastestCacheCombineJs` | Combina JS no `<head>` |
| `wpFastestCacheCombineJsPowerFul` | Combina JS no `<footer>` ("Combine Js Plus") |
| `wpFastestCacheRenderBlocking` + `_Css` | Elimina render-blocking JavaScript/CSS |
| `wpFastestCacheGoogleFonts` | Carrega Google Fonts de forma assíncrona |
| `wpFastestCacheLazyLoad` + `_type`, `_type_all`, `_type_exceptcontent`, `_keywords`, `_placeholder`, `_exclude_full_size_img` | Lazy load de imagens/iframes com regras avançadas de âmbito e placeholder customizado |
| `wpFastestCacheDelayJS` | Atrasa carregamento de scripts JS até scroll/movimento do rato |
| `wpFastestCachePremium` | Flag interna de licença Premium |

> **Nota crítica:** todo o bloco acima só é renderizado/gravado se
> `class_exists("WpFastestCachePowerfulHtml")` for verdadeiro, o que exige
> o plugin separado `wp-fastest-cache-premium` (licença paga) instalado e
> activo. **Não é apenas "desligado por omissão"** — nos sites do bundle
> Descomplicar (sem addon Premium comprado) estes checkboxes aparecem
> desativados/cinzentos no wp-admin (classe `questionCon disabled`) e os
> respectivos `$_POST` nunca chegam a `saveOption()`. Ver §13 para a
> matriz completa Free vs Premium.

**Chaves de infraestrutura confirmadas como ausentes (não é omissão de leitura):**

| Chave esperada | Estado | Porque fica assim |
|---|---|---|
| `WpFastestCacheVarnish` | ⚪ não configurado | Sem Varnish à frente do site — não aplicável. Ver §10.3 |
| `WpFastestCacheCDN` | ⚪ não configurado | A integração CDN nativa do WPFC não está activa; o purge Cloudflare é feito pelo App for Cloudflare®, não pelo WPFC. Ver §10 |
| `WpFastestCacheExclude` | ⚪ não configurado | Sem regras de exclusão de páginas/cookies/user-agents definidas. Ver §7 |
| `WpFastestCacheCSP` | ⚪ não configurado | Sem regras "Clearing Specific Pages" definidas. Ver §9 |
| `WpFastestCachePathSettings` | ⚪ não configurado | Caminho de cache por omissão (`wp-content/cache`, `wp-content/cache/wpfc-minified`). Ver §11 |
| `WpFastestCacheToolbarSettings` | ⚪ não configurado | Sem restrição de roles na toolbar de admin — ver §12 |

---

## 2. Purgar cache — comando nativo (NÃO é `wp cache flush`)

O plugin regista um comando WP-CLI próprio via `inc/cli.php`
(`WP_CLI::add_command('fastest-cache', 'wpfcCLI')`), carregado
automaticamente quando `WP_CLI` está definido — não precisa de nada extra
no `wp-config.php`. **`wp help fastest-cache` confirma ao vivo (16-08-2026)
que existe um único subcomando: `clear`** — não há `preload`, `status`,
`exclude` nem `cdn` via CLI; essas operações só existem no wp-admin/AJAX.

```bash
# Limpar toda a cache HTML (mantém ficheiros minificados existentes)
wp fastest-cache clear all --allow-root --path=$PATH

# Limpar TUDO, incluindo cache minificada (CSS/HTML combinados) — usar após deploy de CSS/JS
wp fastest-cache clear all and minified --allow-root --path=$PATH

# Limpar só a cache de um ou mais posts/páginas específicos
wp fastest-cache clear --post_id=123 --allow-root --path=$PATH
wp fastest-cache clear --post_id=123,456,789 --allow-root --path=$PATH
```

Código-fonte de `wpfcCLI::clear()` (`inc/cli.php`) — lógica exacta:

1. Se `--post_id=` estiver presente, itera cada ID (split por vírgula) e
   chama `singleDeleteCache(false, $post_id)` por post — **não** aceita
   `all` em conjunto com `--post_id`;
2. Senão, se `$args[0] == "all"`:
   - Se `$args[1] == "and"` e `$args[2] == "minified"` → `deleteCache(true)`;
   - Senão → `deleteCache()` (sem o `true`, não limpa minificados);
3. Qualquer outra combinação (`$args[0]` diferente de `all`, ou sintaxe
   incompleta de "and minified") → `wrong_usage()`, que imprime um bloco
   de erro com link para a doc oficial e sai com `WP_CLI::error_multi_line`.

Internamente, `deleteCache()` — a mesma função que corre quando se clica
"Delete Cache" no wp-admin — faz, por esta ordem:
1. Purga Varnish se `WpFastestCacheVarnish` estiver configurado (não é o
   caso nos sites do bundle — ver §10.3);
2. Chama `CdnWPFC::cloudflare_clear_cache()` — **só tem efeito se
   `WpFastestCacheCDN` tiver uma entrada `id == "cloudflare"` com
   `cdnurl`/`originurl` (email + API token) configurados**. Nos sites do
   bundle **não está configurado** — o purge Cloudflare real é feito pelo
   **App for Cloudflare®**, não por esta chamada. Não assumir que
   `wp fastest-cache clear all` purga o edge Cloudflare;
3. Recria a pasta de preload temporária e relança o crawler de preload
   (`set_preload()`);
4. Apaga `wp-content/cache/all`, `wp-content/cache/wpfc-minified` e
   `wp-content/cache/wpfc-mobile-cache` (ou os caminhos customizados de
   `WpFastestCachePathSettings`, ver §11).

---

## 3. Três camadas de cache — não confundir

| Camada | Plugin/mecanismo | Comando de purga | O que invalida |
|---|---|---|---|
| **Page cache** (HTML em disco) | WP Fastest Cache | `wp fastest-cache clear all and minified` | Ficheiros HTML/CSS/JS gerados em `wp-content/cache/*` |
| **Object cache** (queries à BD) | Redis Object Cache (`redis-cache`, DB 12, Predis) | `wp cache flush` | Chaves no Redis (queries, transients cacheados) |
| **Edge cache** (CDN) | Cloudflare, via App for Cloudflare® | purge no wp-admin do plugin ou API Cloudflare directa | Cache no edge Cloudflare (fora do servidor de origem) |

**Não conflitam entre si** — são camadas independentes e complementares:
o Redis acelera queries PHP mesmo quando o WPFC serve HTML estático (o
WPFC serve o ficheiro sem sequer bootar o WordPress completo em muitos
casos, mas quando bootar — ex. utilizador autenticado — o Redis acelera
essa execução). `wp cache flush` **não limpa a cache HTML do WPFC**, e
`wp fastest-cache clear all` **não limpa o Redis**. Confundir os dois é o
erro mais comum: "limpei a cache e a alteração continua sem aparecer" —
normalmente falta uma das três camadas.

---

## 4. Sequência de cache completa (sempre após alterações de config ou deploy)

Seguir o mesmo padrão do `/rank-math` (`Sequencia de cache`), com o passo
WPFC adicionado:

```bash
wp fastest-cache clear all and minified --allow-root --path=$PATH
wp cache flush --allow-root --path=$PATH
wp transient delete --all --allow-root --path=$PATH
wp rewrite flush --allow-root --path=$PATH
```

Seguido de **purga Cloudflare** (App for Cloudflare®, camada edge — fora
do WP-CLI, via wp-admin ou API Cloudflare com o token da zona). Alterações
que dependem de `robots.txt`, `/llms.txt`, headers ou CSS/JS combinado só
aparecem depois de purgar as três camadas — confirmado no achado real
do `bot_management`/`robots.txt` (`BUNDLE-Excelencia-WP.md` §2.4):
`robots.txt` tinha `cache-control: max-age=315360000` no Cloudflare, e só
mudou depois de purgar Cloudflare + WPFC juntos.

**Regra prática:** depois de qualquer alteração a CSS/JS/tema/Elementor,
purgar sempre **WPFC (`and minified`) + Cloudflare** juntos — nunca só um
dos dois. Alterações a options do WordPress sem impacto em HTML/CSS
(ex. Rank Math meta) só precisam do `wp cache flush` (Redis).

---

## 5. `wpFastestCacheDisableEmojis` — o que faz exactamente

Confirmado em `inc/cache.php:34` — quando esta opção está `on`, o plugin
remove o `<script>` inline `wp-emoji-release.min.js` e o CSS inline de
detecção de emoji que o WordPress core injecta por omissão em todo o
`<head>` (mecanismo nativo para navegadores antigos sem suporte a emoji
Unicode). **Ganho de performance pequeno mas real**: elimina um pedido
JS + um bloco de CSS inline em cada página, sem efeito visual em
navegadores modernos (emoji Unicode nativo funciona sem o script). Sem
riscos conhecidos de quebra — ao contrário de Minify JS/Combine JS
(Premium), não mexe em scripts de plugins/tema.

---

## 6. Preload — configuração completa e rebuild após deploy

`wpFastestCachePreload=on` + `wpFastestCachePreload_number=4` significa
que, após qualquer purga (`deleteCache()`), o plugin relança
automaticamente um crawler interno (`set_preload()`) com 4 threads
paralelas para regenerar a cache das páginas mais visitadas **antes** da
próxima visita real — evita que o primeiro visitante depois de um deploy
apanhe sempre a versão sem cache (mais lenta). Lógica em `inc/preload.php`
(894 linhas) e `inc/single-preload.php` (346 linhas, preload de um único
post após ser publicado/actualizado).

### 6.1 Método de preload (`templates/preload.php`)

O wizard de Preload no wp-admin oferece um `<select>` com dois métodos
(campo interno, não persiste directamente como chave simples — é
serializado dentro da config de preload):

| Método | O que faz |
|---|---|
| `default` | Ordena o conteúdo do mais recente ao mais antigo (`Contents from Newest to Oldest`) — é o método activo se nada for escolhido |
| `sitemap` | Usa um sitemap XML como fonte de URLs a pré-carregar, em vez de percorrer o conteúdo por data |

### 6.2 Tipos de conteúdo incluídos no preload (checkboxes arrastáveis/reordenáveis)

Quando o método é `default`, os seguintes tipos de conteúdo podem ser
marcados individualmente e a ordem entre eles é definida por
drag-and-drop (guardada em `wpFastestCachePreload_order`):

| Checkbox | Tipo de conteúdo |
|---|---|
| `wpFastestCachePreload_homepage` | Homepage |
| `wpFastestCachePreload_post` | Posts |
| `wpFastestCachePreload_category` | Categorias |
| `wpFastestCachePreload_page` | Páginas |
| `wpFastestCachePreload_tag` | Tags |
| `wpFastestCachePreload_attachment` | Anexos (media attachments com página própria) |
| `wpFastestCachePreload_customposttypes` | Custom Post Types registados no site |
| `wpFastestCachePreload_customTaxonomies` | Taxonomias customizadas |

Quando o método é `sitemap`, existe ainda `wpFastestCachePreload_sitemap`
para indicar o URL do sitemap XML a usar como fonte.

### 6.3 Rebuild após deploy

```bash
# Depois de um deploy (código/tema alterado), sequência completa:
wp fastest-cache clear all and minified --allow-root --path=$PATH
wp cache flush --allow-root --path=$PATH
# + purga Cloudflare (App for Cloudflare, fora do WP-CLI)
# O preload arranca sozinho a seguir ao clear — não precisa de comando extra.
# Confirmar que recriou a pasta de cache:
wp eval 'echo is_dir(WP_CONTENT_DIR . "/cache/all") ? "existe" : "vazio, aguardar preload";' --allow-root --path=$PATH
```

---

## 7. Exclusão de páginas, cookies e user-agents — `WpFastestCacheExclude`

Feature separada da option principal, gerida pelo "Exclude Page Wizard"
(`templates/exclude.php`) e persistida em **`wp_options.WpFastestCacheExclude`**
como um array JSON de objectos `{prefix, content, type}` — **não faz parte
do JSON de `WpFastestCache`**. Callback de gravação:
`wpfc_save_exclude_pages_callback()` em `wpFastestCache.php:714`.

```bash
# Ler as regras de exclusão configuradas
wp option get WpFastestCacheExclude --format=json --allow-root --path=$PATH
```

### 7.1 Estrutura de uma regra

| Campo | Valores possíveis | O que faz |
|---|---|---|
| `type` | `page`, `useragent`, `cookie`, `css`, `js` | A que se aplica a regra — página completa (não gera cache), pedido de um User-Agent específico, presença de um cookie, ou exclusão de um ficheiro CSS/JS individual da minificação/combinação |
| `prefix` | `homepage`, `category`, `tag`, `post`, `page`, `archive`, `attachment` (content types); `startwith`, `contain`, `exact`, `regex` (métodos); `googleanalytics`, `yandexclickid`, `woocommerce_items_in_cart` (especiais) | Como o `content` é comparado contra o `REQUEST_URI` (ou o cookie/user-agent) |
| `content` | string livre ou regex | O valor a comparar |

### 7.2 Regras nativas sempre presentes (hardcoded, não editáveis)

Independentemente da configuração, o wizard sempre lista estas regras
como pré-existentes e não removíveis (`editable: false` em
`WpFcExcludePages.insert_existing_rules()`):

| Tipo | Regra | Motivo |
|---|---|---|
| `page`, exact | `wp-login.php` | Nunca cachear a página de login |
| `page`, startwith | `wp-admin` | Nunca cachear o admin |
| `useragent`, contain | `facebookexternalhit` | Bots de preview social não devem receber cache potencialmente desatualizada |
| `useragent`, contain | `LinkedInBot` | idem |
| `useragent`, contain | `WhatsApp` | idem |
| `useragent`, contain | `Twitterbot` | idem |
| `cookie`, contain | `Admin` | Qualquer visitante com cookie de admin (`wordpress_logged_in_...` com role admin) nunca recebe cache |

### 7.3 Efeito no `.htaccess` (Apache) e no PHP (todos os servidores)

Ao gravar (`modify_htaccess_for_exclude()`), o plugin reescreve o bloco
`# Start WPFC Exclude ... # End WPFC Exclude` do `.htaccess` com regras
`mod_rewrite` equivalentes — **isto é a camada rápida (nginx/Apache
servem o miss sem sequer chamar o PHP)**. Em paralelo, `inc/cache.php`
lê `WpFastestCacheExclude` em runtime (`get_option("WpFastestCacheExclude")`,
linha 78) para aplicar as mesmas regras via PHP como segunda camada de
segurança (necessário em nginx, onde não há `.htaccess`).

### 7.4 Bloquear cache de uma página individual via editor

O plugin regista um botão no TinyMCE/Quicktags (`addButtonOnEditor()`,
`checkShortCode()`) que insere `[wpfcNOT]` no conteúdo — qualquer post/página
que contenha este shortcode nunca é cacheada (`$this->blockCache = true`),
sem precisar de criar uma regra de exclusão explícita.

### 7.5 Exclusão automática de wishlist (YITH WooCommerce Wishlist)

Se o plugin `yith-woocommerce-wishlist/init.php` estiver activo,
`exclude_urls()` (`inc/admin.php:163`) adiciona automaticamente uma regra
`exact` para o URL da página de wishlist, sempre que a config é gravada —
comportamento automático, não precisa de intervenção manual.

---

## 8. Cache Timeout — duas mecânicas distintas

### 8.1 Timeout global legado (`wpFastestCacheTimeOut`)

Uma única regra global, gravada como parte da própria option `WpFastestCache`
(`wpFastestCacheTimeOut`, `_TimeOutHour`, `_TimeOutMinute`). Ao gravar
(`addCacheTimeout()`, `inc/admin.php:203`), o plugin:
1. Limpa qualquer agendamento anterior no hook `wp_fastest_cache`
   (`wp_clear_scheduled_hook($this->slug())`, onde `slug() == "wp_fastest_cache"`);
2. Agenda um novo `wp_schedule_event()` no mesmo hook, com o schedule
   (`hourly`, `daily`, etc.) escolhido em `wpFastestCacheTimeOut` e a hora
   exacta calculada a partir de `TimeOutHour`/`TimeOutMinute`.

```bash
# Verificar se há um timeout global agendado
wp cron event list --allow-root --path=$PATH | grep wp_fastest_cache
```

### 8.2 Cache Timeout Wizard — múltiplas regras por página/tipo (`templates/timeout.php`)

Mecanismo mais granular: permite definir **N regras** de purga agendada,
cada uma associada a um subconjunto de páginas (`homepage`, `all`,
`startwith`, `exact`) e a uma frequência (`wp_get_schedules()`, incluindo
schedules customizados que tenham a flag `["wpfc"]` marcada). **Não usa
uma `wp_option` própria** — cada regra vira um evento WP-Cron individual
com hook `wp_fastest_cache_<indice>` (`wpfc_save_timeout_pages_callback()`,
`wpFastestCache.php:832`), e os parâmetros da regra (`prefix`, `content`,
`hour`, `minute`) viajam como argumentos serializados do próprio evento
cron — **inspecionáveis apenas via `wp cron event list` + `wp cron event run`**,
não via `wp option get`.

```bash
# Listar todas as regras de timeout agendadas (uma por evento wp_fastest_cache_N)
wp cron event list --allow-root --path=$PATH | grep 'wp_fastest_cache_'
```

Se o schedule escolhido for `daily`/`onceaday`, a UI mostra também um
selector de Hora/Minuto (fuso do servidor, mostrado ao vivo no wizard via
`current_time("H:i:s")`) para agendar a purga a uma hora fixa em vez de
"daqui a X".

### 8.3 Aviso "Disabled Cron" (`templates/disable_wp_cron.php`)

Se `DISABLE_WP_CRON` estiver definido como `true` no `wp-config.php`, o
botão "+ Add New Timeout" no wp-admin mostra um aviso a explicar que o
WP-Cron foi desligado inteiramente e nenhuma regra de timeout vai
disparar sozinha — só via cron real do sistema a chamar `wp-cron.php`, ou
`wp cron event run --due-now`.

---

## 9. Clearing Specific Pages (CSP) — `WpFastestCacheCSP`

Feature para **purgar páginas adicionais** sempre que a cache é limpa por
qualquer motivo (publicar/actualizar post, clique manual, CLI) —
útil para páginas agregadoras (ex. `/loja/`, `/blog/`) que mostram
conteúdo de múltiplos posts e por isso ficam desatualizadas sem serem
elas próprias editadas. Classe `ClearingSpecificPagesWPFC`
(`inc/clearing-specific-pages.php`), UI em `templates/clearing_specific_pages.php`.

```bash
# Ler as regras CSP configuradas
wp option get WpFastestCacheCSP --allow-root --path=$PATH
```

### 9.1 Estrutura

Array de objectos `{url, order}`, onde:
- `url` **tem de** começar pelo mesmo host que `get_option("home")` —
  validado por `check_url()`, senão a gravação falha com
  `wp_send_json_error()`;
- Pode conter **no máximo um** wildcard `(.*)`, validado por
  `check_wild_card()` — mais do que um wildcard, ou um wildcard mal
  colocado (não precedido de `/`), é rejeitado;
- Não pode conter `..` (protecção contra directory traversal,
  `preg_match("/\.{2,}/", ...)`);
- `order` é o identificador único da regra (usado para editar/remover).

### 9.2 Exemplo de uso típico

Se `/loja/` lista os últimos produtos e um produto novo é publicado,
adicionar uma regra CSP com `url = https://site.pt/loja/` garante que
`/loja/` é purgado junto com a cache do próprio produto, mesmo que
`wpFastestCacheNewPost_type` esteja configurado apenas para "a página
nova".

---

## 10. Integração CDN e Varnish

### 10.1 CDN genérica (MaxCDN / StackPath / BunnyCDN / CloudFront / "Other") — `WpFastestCacheCDN`

Classe `CdnWPFC` (`inc/cdn.php`, 650 linhas). A option
**`WpFastestCacheCDN`** guarda um **array JSON de integrações** (mais do
que uma CDN pode coexistir), cada entrada identificada por `id`:
`cloudflare`, `maxcdn`, `other` (genérico — cobre StackPath, BunnyCDN,
Amazon CloudFront, KeyCDN, CDN77, que são todos normalizados para `"other"`
internamente em `start_cdn_integration()`/`pause_cdn_integration()`/
`remove_cdn_integration()`).

```bash
wp option get WpFastestCacheCDN --format=json --allow-root --path=$PATH
```

Campos de uma entrada genérica (não-Cloudflare): `id`, `cdnurl` (URL do
CDN), `originurl` (URL de origem, normalmente o próprio domínio),
`status` (ausente = activo, `"pause"` = integração pausada sem remover a
config).

**Âmbito de reescrita de URLs (wizard "Other CDN", `templates/cdn/*`):**
- `templates/cdn/file_types.php` — checkboxes por extensão de ficheiro a
  servir via CDN: `aac, avif, css, eot, gif, jpeg, js, jpg, less, mp3,
  mp4, ogg, otf, pdf, png, svg, swf, ttf, webm, webp, woff, woff2`
  (todos marcados por omissão);
- `templates/cdn/specify_sources.php` — lista de palavras-chave: só URLs
  que **contenham** um dos keywords especificados são servidos via CDN
  (whitelist opcional, vazio = todos os tipos marcados acima);
- `templates/cdn/exclude_sources.php` — lista de palavras-chave: URLs que
  **contenham** um destes keywords **nunca** são servidos via CDN
  (blacklist, tem prioridade sobre a whitelist).

Validação em tempo real do URL do CDN (`CdnWPFC::check_url()`) bloqueia
explicitamente: IPv6, IPs decimais/hex/octal, `localhost`, e ranges
privados (`127.`, `10.`, `172.`, `169.`, `100.`, `198.`, `192.`) — com
mensagens de erro específicas conhecidas para CloudFront 403, BunnyCDN
403 e Speedsize 400.

### 10.2 Integração Cloudflare nativa do WPFC

**Distinta do App for Cloudflare®** — esta é a integração embutida no
próprio WP Fastest Cache, activada com `id == "cloudflare"` dentro de
`WpFastestCacheCDN`, campos `cdnurl` (email da conta, ou literal `"wpfc"`
se estiver a usar API Token em vez de Global API Key — ver
`cloudflare_generate_header()`) e `originurl` (a chave/token).

Ao configurar via wizard `templates/cdn/cloudflare.php`, o plugin executa
automaticamente e em sequência (`cloudflare_change_settings()`):
1. **Desactiva o Rocket Loader** da zona Cloudflare (`cloudflare_disable_rocket_loader()`) — evita conflito entre o Rocket Loader (que também reescreve JS) e o Combine/Minify JS do WPFC;
2. Purga a cache Cloudflare (`cloudflare_clear_cache()`);
3. **Define Browser Cache TTL para 6 meses** (`16070400` segundos,
   `cloudflare_set_browser_caching()`) — hardcoded, não configurável pela UI;
4. Se o plano Cloudflare for `free`, **remove automaticamente as regras
   WebP do `.htaccess`** (`cloudflare_remove_webp()`) — porque o plano
   grátis da Cloudflare já faz a sua própria conversão/entrega WebP via
   Polish, e as duas camadas juntas causam conflitos;
5. `cloudflare_disable_minify()` está **deprecated** (faz `return` antes
   de qualquer chamada à API) porque a Cloudflare descontinuou o Auto
   Minify legacy — o código morto continua no ficheiro mas nunca executa.

O Zone ID é resolvido automaticamente por `cloudflare_get_zone_id()`
(paginando `/zones?page=1..2&per_page=1000` da API Cloudflare e
comparando o hostname do site) e fica em cache serializado dentro do
próprio `WpFastestCacheCDN->zone_id` (função `unserialize()`/`serialize()`
directamente sobre um array PHP — não JSON).

```bash
# Confirmar se há integração Cloudflare nativa do WPFC configurada (distinta do App for Cloudflare®)
wp option get WpFastestCacheCDN --format=json --allow-root --path=$PATH | grep -o '"id":"cloudflare"'
```

### 10.3 Varnish (reverse proxy) — `WpFastestCacheVarnish`

Classe `VarnishWPFC` (`inc/varnish.php`). Guarda apenas
`{"server": "<host:porta>"}` (e opcionalmente `"status": "pause"`). Ao
purgar, envia um pedido HTTP `PURGE` (não `GET`/`POST`) para
`<schema>://<server>/.*` com o header `Host` apontado para o domínio real
do site — se o pedido falhar tenta trocar `https://`↔`http://` uma vez
antes de desistir, e trata explicitamente respostas `501` (método PURGE
não permitido pelo Varnish/hosting) com mensagem a sugerir contacto com o
hosting. **Chamado automaticamente dentro de `deleteCache()`** sempre que
`WpFastestCacheVarnish` existir e não estiver em pausa — não é preciso
correr nada manualmente depois de configurado.

```bash
wp option get WpFastestCacheVarnish --allow-root --path=$PATH
```

---

## 11. Customização do caminho da cache — `WpFastestCachePathSettings`

Wizard "Cache Path Customization" (`templates/cache_path.php`) permite
mudar o nome da pasta de cache dentro de `wp-content/` (por omissão
`cache`) e da pasta de assets minificados (por omissão `wpfc-minified`).
Útil quando outro plugin/CDN já usa `wp-content/cache/` para outra coisa,
ou por segurança-por-obscuridade em setups multi-tenant.

```bash
wp option get WpFastestCachePathSettings --allow-root --path=$PATH
```

Estrutura: `{"cachepath": "cache", "optimizedpath": "wpfc-minified"}` —
se a option não existir, o código assume estes dois valores por omissão
(`inc/admin.php:22-29` em `cache_path.php`). **Alterar isto implica que
todos os comandos de purga (`wp fastest-cache clear`, `deleteCache()`)
passam a apagar os novos caminhos** — não há migração automática de
ficheiros já cacheados no caminho antigo, ficam órfãos em disco até
serem apagados manualmente ou por rotação de logs.

---

## 12. Toolbar de admin e acções rápidas por post

### 12.1 Menu na admin bar (`inc/admin-toolbar.php`)

Classe `WpFastestCacheAdminToolbar` adiciona um nó "WP Fastest Cache" na
admin bar do WordPress (frontend e wp-admin), com sub-itens: "Clear Cache
of This Page" (só no frontend), "Clear All Cache", "Clear Cache and
Minified CSS/JS", e (se for multisite) "Clear Cache of All Sites". No
wp-admin, mostra ainda "Toolbar Settings" quando já se está na página de
opções do plugin.

### 12.2 Restringir a toolbar por role (`WpFastestCacheToolbarSettings`)

Wizard `templates/toolbar_settings.php` permite marcar quais **roles não
administrativos** (o `administrator` está sempre incluído e não aparece
na lista) veem o menu "WP Fastest Cache" na admin bar —
`wpfc_toolbar_save_settings_callback()` grava um array `{role: "1"}` em
`wp_options.WpFastestCacheToolbarSettings`.

```bash
wp option get WpFastestCacheToolbarSettings --allow-root --path=$PATH
```

### 12.3 Link "Clear Cache" na listagem de posts/páginas (`inc/column.php`)

Classe `WpFastestCacheColumn` injecta um link "Clear Cache" nas row
actions de `post_row_actions`/`page_row_actions` (a mesma linha onde
aparecem "Edit"/"Trash"/"View" na listagem do wp-admin), com um pedido
AJAX (`wpfc_clear_cache_column`) que chama `singleDeleteCache()` só para
esse post — equivalente a `wp fastest-cache clear --post_id=<ID>` mas
disparado pela UI sem passar pela CLI.

### 12.4 Integração WP-Polls (`inc/wp-polls.php`)

Se o plugin WP-Polls estiver activo, o WPFC intercepta a votação em
enquetes via AJAX próprio (`wpfc_wppolls_ajax_request`) para garantir que
o resultado do voto não fica "preso" numa página cacheada — sem isto, um
visitante veria sempre a enquete por votar mesmo depois de votar, porque
a página HTML estática não reflecte o estado de sessão.

---

## 13. Matriz Free vs Premium (addon `wp-fastest-cache-premium`)

Confirmado no código: `class_exists("WpFastestCachePowerfulHtml")` é o
gate central usado em `inc/admin.php` para decidir o que renderizar/gravar.
Essa classe só existe se o plugin separado
`wp-fastest-cache-premium/wpFastestCachePremium.php` estiver instalado e
activo (licença paga, `get_premium_version()` lê a versão do cabeçalho
desse ficheiro). **Nos sites do bundle Descomplicar este addon NÃO está
instalado** — confirmado por `find` no `wp-content/plugins/` do site
piloto, que só devolve a pasta `wp-fastest-cache/` (Free).

| Funcionalidade | Free | Premium | Onde no código |
|---|---|---|---|
| Page cache HTML, minify HTML/CSS, combine CSS, Gzip, Leverage Browser Caching | ✅ | ✅ | `inc/admin.php` (fora do gate) |
| Preload (crawler automático) | ✅ | ✅ | `inc/preload.php` |
| Exclusão de páginas/cookies/user-agents | ✅ | ✅ | `inc/cache.php`, `WpFastestCacheExclude` |
| Clearing Specific Pages | ✅ | ✅ | `inc/clearing-specific-pages.php` |
| CDN genérica (MaxCDN/Other) + Cloudflare nativa | ✅ | ✅ | `inc/cdn.php` |
| Varnish | ✅ | ✅ | `inc/varnish.php` |
| Cache Timeout (global e por regra) | ✅ | ✅ | `inc/admin.php`, `templates/timeout.php` |
| Disable Emojis | ✅ | ✅ | `inc/cache.php` |
| Mobile cache (separar cache mobile/desktop) | ✅ | ✅ | `wpFastestCacheMobile` |
| **Mobile Theme** (tema mobile dedicado) | ❌ | ✅ | `inc/admin.php:1233`, `wp-fastest-cache-premium/pro/library/mobile-cache.php` |
| **Minify HTML Plus / Minify Css Plus** | ❌ | ✅ | `inc/admin.php:1289,1311` |
| **Minify JS / Combine JS / Combine JS Plus** | ❌ | ✅ | `inc/admin.php:1330-1373` |
| **Render Blocking JS/CSS** | ❌ | ✅ | `inc/admin.php:1400`, doc: `wpfastestcache.com/premium/render-blocking-js/` |
| **Google Fonts optimizado** | ❌ | ✅ | `inc/admin.php:1426` |
| **Lazy Load** (imagens/iframes) | ❌ | ✅ | `inc/admin.php:1450`, `wp-fastest-cache-premium/pro/library/lazy-load.php` (incluído via `cache.php:987`) |
| **Delay JS** | ❌ | ✅ | `inc/admin.php:1488`, `wp-fastest-cache-premium/pro/library/delay-js.php` (incluído via `cache.php:875`) |
| **Image optimisation/compressão** | ❌ | ✅ | `wpFastestCache.php:214`, `WpFastestCacheImageOptimisation` |
| **Logs de actividade** | ❌ | ✅ | `wpFastestCache.php:1556`, `pro/library/logs.php` |
| **DB auto-cleanup** (limpeza de transients/revisões) | ❌ | ✅ | `inc/admin.php:2231`, `pro/templates/db-auto-cleanup.php` |
| **Static file caching avançado** | ❌ | ✅ | `wpFastestCache.php:249`, `pro/library/statics.php` |

**Gotcha de auditoria:** se uma option JSON `WpFastestCache` mostrar
chaves Premium marcadas `"on"` (ex. `wpFastestCacheMobileTheme`,
`wpFastestCacheLazyLoad`) **isso não prova que a funcionalidade está
activa** — só prova que a chave ficou gravada num momento em que o addon
Premium podia estar instalado, ou que veio de uma migração/import. A
única forma fiável de confirmar se o Premium está realmente activo é:

```bash
wp plugin list --path=$PATH --format=json | grep -i "fastest-cache"
# Se só aparecer "wp-fastest-cache" (sem "-premium"), todas as chaves Premium são no-op.
```

---

## 14. Gotchas / erros comuns

| Sintoma | Causa | Solução |
|---|---|---|
| "Limpei a cache e não mudou nada" | Confundir camadas — só correu `wp cache flush` (Redis) ou só `wp fastest-cache clear` (page cache), faltou Cloudflare | Sempre as 3 camadas juntas para mudanças visuais (§4) |
| `wp fastest-cache clear all` não purga Cloudflare | `WpFastestCacheCDN` sem entrada `cloudflare` com credenciais válidas — a chamada `CdnWPFC::cloudflare_clear_cache()` corre mas fica sem efeito por falta de email/API key/zone ID | Purgar Cloudflare à parte (App for Cloudflare® ou API) |
| Comando `wp fastest-cache` "command not found" | `inc/cli.php` só é carregado `if(defined('WP_CLI') && WP_CLI)` — falha se o WP-CLI não inicializar o plugin correctamente (ex. `--skip-plugins`) | Nunca usar `--skip-plugins` com este comando; confirmar `wp plugin is-active wp-fastest-cache` primeiro |
| `wp fastest-cache clear all and minified` dá "Wrong usage" | Sintaxe exacta exigida: exactamente `all`, `and`, `minified` como 3 argumentos posicionais separados por espaço — qualquer typo (`--minified`, `all-minified`) cai em `wrong_usage()` | Copiar o comando literal da doc, sem flags extra |
| Checkbox Premium (Lazy Load, Minify JS, Render Blocking...) não tem efeito nenhum apesar de aparecer marcado no JSON | Addon `wp-fastest-cache-premium` não está instalado — o checkbox nem chega a ser submetido no wp-admin (`disabled`), a chave só sobrevive na option se veio de outro contexto | Confirmar `wp plugin list` (§13) antes de investigar "porque é que a Lazy Load não funciona" |
| Minify JS/Combine JS activados "quebram" o site | Nos sites do bundle **estas opções nem estão disponíveis** (Premium-only) — se aparecerem activas nalgum sítio é sinal de config legada ou de outro plugin | Confirmar se o Premium está mesmo activo antes de desligar; se não estiver, a causa do problema é outra |
| `robots.txt`/`/llms.txt` não reflecte alteração recente | `max-age` alto no Cloudflare + cache HTML do WPFC — as duas mascaram a alteração na origem | Purgar WPFC + Cloudflare juntos (§4), não só um |
| `--post_id=` não limpa nada | ID de post inválido ou página não estava em cache (nunca visitada) | Confirmar que a página tem ficheiro em `wp-content/cache/all/<slug>/` (ou no caminho customizado de `WpFastestCachePathSettings`, §11) antes de assumir falha |
| Regra de exclusão gravada no wp-admin não bloqueia a cache em produção | Site em nginx (sem `.htaccess`) e `WpFastestCacheExclude` não está a ser lido correctamente pelo PHP, ou regex mal escapado (`prefix=regex`) | Testar a regra isoladamente com `wp option get WpFastestCacheExclude --format=json`, validar a regex fora do WordPress primeiro |
| Página agregadora (`/loja/`, `/blog/`) mostra conteúdo desatualizado mesmo com `New Post` activo | `wpFastestCacheNewPost_type` só limpa a página nova, não as páginas que a listam | Adicionar regra Clearing Specific Pages (§9) para essas páginas agregadoras |
| Cache Timeout Wizard "desaparece" depois de gravar | `DISABLE_WP_CRON` está `true` no `wp-config.php` — a regra fica registada como evento mas nunca dispara sozinha | Confirmar cron real do sistema a chamar `wp-cron.php`, ou usar `wp cron event run --due-now` manualmente/via systemd timer |

---

## 15. Decision tree — qual comando/opção usar

| Operação | Comando/Opção |
|---|---|
| Purgar tudo (HTML) | `wp fastest-cache clear all` |
| Purgar tudo incl. minificados (após deploy CSS/JS) | `wp fastest-cache clear all and minified` |
| Purgar só 1+ posts/páginas | `wp fastest-cache clear --post_id=ID[,ID...]` |
| Purgar object cache (Redis) | `wp cache flush` |
| Purgar edge (Cloudflare) | wp-admin App for Cloudflare® ou API Cloudflare directa (ou integração nativa WPFC se configurada, §10.2) |
| Ler config completa | `wp option get WpFastestCache --format=json` |
| Alterar 1 chave da config | `wp option update WpFastestCache '{"...json completo com a chave alterada..."}' --format=json` (é JSON simples, não serializado PHP — reescrever o objecto completo) |
| Confirmar se está a servir cache | `wp eval 'echo is_dir(WP_CONTENT_DIR."/cache/all") ? "sim" : "nao";'` |
| Ver regras de exclusão de páginas/cookies/UA | `wp option get WpFastestCacheExclude --format=json` (§7) |
| Ver regras de purga extra (páginas agregadoras) | `wp option get WpFastestCacheCSP` (§9) |
| Ver integrações CDN configuradas | `wp option get WpFastestCacheCDN --format=json` (§10) |
| Ver config Varnish | `wp option get WpFastestCacheVarnish` (§10.3) |
| Ver caminho de cache customizado | `wp option get WpFastestCachePathSettings` (§11) |
| Ver regras de Cache Timeout (por página) | `wp cron event list | grep wp_fastest_cache_` (§8.2) |
| Ver timeout global legado | `wp cron event list | grep 'wp_fastest_cache '` (hook exacto `wp_fastest_cache`, §8.1) |
| Confirmar se o addon Premium está activo | `wp plugin list --format=json | grep fastest-cache` (§13) |
| Bloquear cache de 1 página sem criar regra | Inserir `[wpfcNOT]` no conteúdo via botão do editor (§7.4) |

---

**Fonte:** `CONFIG-Plugins-Referencia.md` §3 (WP Fastest Cache) +
`BUNDLE-Excelencia-WP.md` §2.2/§2.4 (modelo de performance, achado do
purge Cloudflare+WPFC no `robots.txt`) + leitura directa e completa do
código-fonte do plugin v1.5.0 (Free, sem addon Premium instalado) no
servidor `server.descomplicar.pt`, site piloto `emanuelalmeida.pt`:
`wpFastestCache.php` (2746 linhas, 100% lido), `inc/admin.php` (2620
linhas, secções de settings/save/render lidas integralmente), `inc/cache.php`
(1460 linhas), `inc/preload.php` (894 linhas), `inc/css-utilities.php`
(766 linhas), `inc/cdn.php` (650 linhas, 100% lido), `inc/js-utilities.php`
(340 linhas), `inc/single-preload.php` (346 linhas), `inc/varnish.php`
(177 linhas, 100% lido), `inc/clearing-specific-pages.php` (100% lido),
`inc/admin-toolbar.php`, `inc/column.php`, `inc/wp-polls.php`, `inc/cli.php`
(100% lido), e todos os templates relevantes em `templates/` e
`templates/cdn/` (100% lidos) + `wp help fastest-cache` e `wp option
list --search='WpFastestCache*'` ao vivo em `emanuelalmeida.pt`,
16-08-2026.