feat(wordpress): EMCP Tools workflow skills + widget catalogs + pending wordpress skills
- emcp-page-building, emcp-content-ops, emcp-site-audit: EMCP Tools MCP workflows verified live (atomic/legacy interplay, apply-template overwrite risk, create-theme-template goes live immediately, false-positive malware pattern in scan-security, change ledger + rollback) - elementor-pro-widgets: 30+5 native Elementor Pro widgets (curated catalog) - elementskit-widgets / powerpack-widgets: 42 + 97 third-party widgets, widgetType extracted from plugin source (not guessed by convention) - plugin.json bumped 1.2.0 -> 1.3.0, keywords + description updated - commits pending wordpress skills already present as untracked files (emcp-tools, wordfence, wp-activity-log, seguranca-descomplicar, webp-express, wp-fastest-cache, wp-font-perf, wp-meteor, wp-activity-log, redis-object-cache, app-for-cloudflare) and pending edits (rank-math, wp-cli, wp-content-seo-gate)
This commit is contained in:
Claude Code
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "wordpress",
|
||||
"description": "WordPress development, maintenance and optimization - plugins, themes, WooCommerce, Elementor, Crocoblock. Backed by NotebookLM notebooks.",
|
||||
"version": "1.2.0",
|
||||
"description": "WordPress development, maintenance and optimization - plugins, themes, WooCommerce, Elementor, Crocoblock, EMCP Tools MCP (page building, content ops, security/performance audit), Elementor Pro/ElementsKit/PowerPack widget catalogs. Backed by NotebookLM notebooks.",
|
||||
"version": "1.3.0",
|
||||
"author": {
|
||||
"name": "Descomplicar - Crescimento Digital",
|
||||
"url": "https://descomplicar.pt"
|
||||
},
|
||||
"homepage": "https://git.descomplicar.pt/ealmeida/descomplicar-plugins",
|
||||
"license": "MIT",
|
||||
"keywords": ["wordpress", "woocommerce", "elementor", "crocoblock", "development", "performance", "licensing"]
|
||||
"keywords": ["wordpress", "woocommerce", "elementor", "crocoblock", "development", "performance", "licensing", "emcp-tools", "elementskit", "powerpack"]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,651 @@
|
||||
---
|
||||
name: app-for-cloudflare
|
||||
description: Gestão da zona Cloudflare a partir do wp-admin via App for Cloudflare® (`app-for-cf`, Digital Point) — SSL/TLS, Speed, Caching, Network, Scrape Shield, Bot Management, Super Bot Fight Mode, WAF real via Managed Ruleset, HSTS, Certificate Transparency, Leaked Credential Checks, Turnstile CAPTCHA, R2 media storage, Zero Trust Access, Page/Cache Rules, DMARC, Web Analytics, ferramentas de diagnóstico (request trace/IP/domain/WHOIS), purge de cache, guest page caching a nível de edge. Usar quando "app for cloudflare", "cloudflare wordpress", "zona cloudflare", "waf cloudflare", "bot management", "super bot fight mode", "hsts cloudflare", "rocket loader", "certificate transparency", "leaked credential checks", "bots de ia cloudflare", "ai_bots_protection", "is_robots_txt_managed", "managed ruleset", "purge cache cloudflare", "turnstile", "cloudflare r2", "cloudflare access", "page rules cloudflare", "cache rules cloudflare", "dmarc cloudflare", "cfPageCachingSeconds", "cfTurnstile", "app_for_cf", ou qualquer alteração a definições de zona Cloudflare/config do plugin num site do bundle Descomplicar.
|
||||
---
|
||||
|
||||
# /app-for-cloudflare — Gestão de zona Cloudflare via App for Cloudflare®
|
||||
|
||||
Plugin `app-for-cf` (Digital Point), versão `1.10.0` (`APP_FOR_CLOUDFLARE_VERSION`),
|
||||
instalado nos sites do bundle Descomplicar®.
|
||||
Não é um simples proxy visual — a maior parte das definições de "boas
|
||||
práticas" que o plugin lista **não vivem em `wp_options`**: são lidas e
|
||||
escritas directamente na **Cloudflare API v4**, usando um token scoped
|
||||
guardado numa única opção serializada. Confundir as duas camadas é o erro
|
||||
mais comum ao operar este plugin.
|
||||
|
||||
**Fonte:** `CONFIG-Plugins-Referencia.md` §1 (App for Cloudflare®) e
|
||||
`BUNDLE-Excelencia-WP.md` §2.2 e §2.4 (GEO/bots de IA) — mapeamento inicial
|
||||
feito em `emanuelalmeida.pt` (16-08-2026), zona `574b243ebabd8ea2b8d89e68921f52cc`,
|
||||
plano **Free Website**. Expandido na mesma sessão com leitura completa do
|
||||
código-fonte (11.309 linhas em 61 ficheiros PHP,
|
||||
`wp-content/plugins/app-for-cf/`): `Repository/Cloudflare.php` (2178
|
||||
linhas — `getSettingsToManage()`, `setEasyMode()`, `updateSettings()`),
|
||||
`Setup.php` (defaults de `wp_options`), `Admin/Template/Settings.php` (766
|
||||
linhas — UI completa das 6 tabs), `Admin/Base/Admin.php` (estrutura das 14
|
||||
páginas de menu), `Base/Pub.php` (657 linhas — guest page caching, purge,
|
||||
preload), `Helper/Api.php` (gate Free/Pro), `Cron/Jobs.php` e
|
||||
`Cli/PurgeCache.php` (automação de purge), e todos os 14 templates de
|
||||
página em `Admin/Template/`.
|
||||
|
||||
---
|
||||
|
||||
## 0. As duas camadas de config — não confundir
|
||||
|
||||
| Camada | Onde vive | Como ler/escrever | Exemplos |
|
||||
|---|---|---|---|
|
||||
| **Config do plugin** (não é Cloudflare) | `wp_options.app_for_cf`, array PHP serializado, 18 chaves (ver §8) | `wp option get/patch` | `cfZoneId`, `cfAccountId`, `cloudflareAuth.token`, `cfPageCachingSeconds`, `cloudflarePreload`, `cfPurgeCacheOnAdminBar`, `cfTurnstile`, `cfProxy`, `cfR2Bucket` |
|
||||
| **Config de zona Cloudflare** (as ~52 "boas práticas" + Bot Management + WAF, ver §1) | **Na Cloudflare, não no WordPress** | API v4 (`https://api.cloudflare.com/client/v4`), bearer token = `cloudflareAuth.token` da opção acima | `ssl`, `security_header` (HSTS), `waf`, `bot_management`, `rocket_loader`, `cache_level`, `hotlink_protection`, etc. |
|
||||
|
||||
Confirmado por leitura completa do código: **não existe** namespace WP REST
|
||||
próprio exposto pelo plugin (`app-for-cf` não aparece em `rest_api_init` em
|
||||
nenhum dos 61 ficheiros PHP) — todas as chamadas de configuração de zona
|
||||
são directas à Cloudflare API v4 a partir do backend PHP do plugin
|
||||
(`Api/Cloudflare.php`), usando o token guardado localmente. Para
|
||||
automatizar fora do wp-admin, replicar essa mesma chamada directa
|
||||
(`curl`/PHP) em vez de procurar um endpoint local que não existe.
|
||||
|
||||
A opção `cloudflareAuth` suporta **dois modos de autenticação** (ver
|
||||
`Setup::defaults()`): `type: 'token'` (API token scoped, o único usado nos
|
||||
sites do bundle) ou o modo legado `email` + `api_key` (Global API Key —
|
||||
não usar, é o modo antigo e menos seguro da Cloudflare, mantido só por
|
||||
compatibilidade retroativa no plugin).
|
||||
|
||||
### Ler a config do plugin (wp-cli)
|
||||
|
||||
```bash
|
||||
PATH=/home/USER/public_html
|
||||
|
||||
# Opção completa (JSON)
|
||||
wp option get app_for_cf --format=json --allow-root --path=$PATH
|
||||
|
||||
# Uma sub-chave
|
||||
wp option pluck app_for_cf cfZoneId --allow-root --path=$PATH
|
||||
wp option pluck app_for_cf cfPageCachingSeconds --allow-root --path=$PATH
|
||||
|
||||
# Editar uma sub-chave sem apagar as restantes (SEMPRE patch, nunca update, em opção serializada)
|
||||
wp option patch update app_for_cf cfPageCachingSeconds 21600 --allow-root --path=$PATH
|
||||
wp option patch update app_for_cf cloudflarePreload 1 --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
`cfProxy`, `cfR2Bucket`, `cloudflareAuth`, `cfTurnstile` são sub-arrays —
|
||||
`wp option patch` só edita um nível; para sub-arrays aninhados usar
|
||||
`wp eval` com `update_option()` sobre o array completo lido primeiro.
|
||||
|
||||
### Extrair o token para chamar a Cloudflare API directamente
|
||||
|
||||
```bash
|
||||
TOKEN=$(wp eval 'echo maybe_unserialize(get_option("app_for_cf"))["cloudflareAuth"]["token"];' --allow-root --path=$PATH)
|
||||
ZONE=$(wp eval 'echo maybe_unserialize(get_option("app_for_cf"))["cfZoneId"];' --allow-root --path=$PATH)
|
||||
|
||||
curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
"https://api.cloudflare.com/client/v4/zones/$ZONE/settings" | jq .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. As definições de zona (por categoria) — lista completa do código
|
||||
|
||||
Fonte: `Repository/Cloudflare.php::getSettingsToManage()` (linhas 88-721),
|
||||
a definição autoritativa usada pelo próprio plugin para desenhar a página
|
||||
de Settings e para `updateSettings()`. **Achado desta expansão:** o número
|
||||
"44" da auditoria original referia-se à contagem informal mostrada na UI
|
||||
(que agrupa alguns campos); a contagem real de entradas no array
|
||||
`getSettingsToManage()` é **52**. Lidas em bloco via `GET
|
||||
/zones/{zone}/settings` (a maioria) + endpoints individuais para os campos
|
||||
com `override_endpoint` (`security_header`, `certificate_transparency`,
|
||||
`leaked_credential_checks`, `bot_management`, `speed_brain`, `fonts`,
|
||||
`content_converter`, `origin_max_http_version`, `h2_prioritization`,
|
||||
`settings/nel`, `flags` para `crawlhints`, `argo/tiered_caching`).
|
||||
Escritas via `PATCH /zones/{zone}/settings/{setting_id}` com `{"value":
|
||||
...}`, excepto onde a definição tem `overwrite_write_method` diferente
|
||||
(`PUT` para tudo em `bot_management`, `POST` para
|
||||
`leaked-credential-checks`/`ct/alerting`/`crawlhints`).
|
||||
|
||||
| Categoria | Definições |
|
||||
|---|---|
|
||||
| **Topo (fora de secção)** | `development_mode` (bool, bom = `off`), `security_level` (select: `off`/`essentially_off`/`low`/`medium`/`high`/`under_attack`, bom = `essentially_off`) — mostradas no topo da página Settings, não numa tab |
|
||||
| **SSL/TLS** | `ssl` (modo de encriptação: `off`/`flexible`/`full`/`strict`/`origin_pull`), `always_use_https`, `security_header` (HSTS — ver §3), `min_tls_version` (`1.0`-`1.3`), `opportunistic_encryption`, `tls_1_3` (radio: `off`/`on`/`zrt` — zero round trip), `automatic_https_rewrites`, `ech` (Encrypted Client Hello), `certificate_transparency` (ver §4, `beta`), `tls_client_auth` |
|
||||
| **Segurança** | `waf` (toggle legado, **deprecated** — ver §2), `bot_fight_mode` (Bot Fight Mode básico — ver §5a), `ai_bots_protection`, `crawler_protection` (ambos geridos via `bot_management` PUT — ver §5a), `bot_likely_automated`, `bot_definitely_automated`, `bot_verified_bots`, `bot_static_resource_protection`, `bot_optimize_wordpress`, `bot_enable_js` (Super Bot Fight Mode — ver §5a), `leaked_credential_checks` (ver §4), `challenge_ttl` (select 5min-12meses, bom = 30min), `browser_check`, `replace_insecure_js` |
|
||||
| **Speed** | `polish` (select: `off`/`lossless`/`lossy`), `webp`, `speed_brain` (`beta`, substitui Rocket Loader/Mirage antigos), `fonts` (`beta`, Cloudflare Fonts — serve Google Fonts a partir do edge), `early_hints`, `rocket_loader` (deprecated para segurança — ver §2), `content_converter` (`beta`), `http2`, `origin_max_http_version` (int, bom = `2`), `http3`, `h2_prioritization`, `0rtt` (TLS 1.3 zero round trip) |
|
||||
| **Caching** | `cache_level` (radio: `basic`/`simplified`/`aggressive`, bom = `aggressive`), `browser_cache_ttl` (select 0-12meses, `0` = respeitar headers de origem), `crawlhints` (`beta`, indica a crawlers quando o conteúdo mudou), `always_online`, `tiered_caching` (Argo Tiered Cache) |
|
||||
| **Network** | `ipv6`, `websockets`, `pseudo_ipv4` (select: `off`/`add_header`/`overwrite_header`), `ip_geolocation`, `max_upload` (select 100-500MB), `nel` (Network Error Logging, `value.enabled` aninhado), `opportunistic_onion` |
|
||||
| **Scrape Shield** | `email_obfuscation`, `hotlink_protection` |
|
||||
|
||||
```bash
|
||||
# Ler uma definição individual
|
||||
curl -s -H "Authorization: Bearer $TOKEN" \
|
||||
"https://api.cloudflare.com/client/v4/zones/$ZONE/settings/rocket_loader" | jq .
|
||||
|
||||
# Escrever uma definição individual (formato standard "value")
|
||||
curl -s -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
"https://api.cloudflare.com/client/v4/zones/$ZONE/settings/rocket_loader" \
|
||||
-d '{"value":"off"}' | jq .
|
||||
```
|
||||
|
||||
`webp`, `content_converter`, `speed_brain`, `fonts`, `crawlhints`,
|
||||
`tiered_caching` e outros podem estar **plan-locked** (não editáveis no
|
||||
plano Free Website) — a API devolve o valor actual mas ignora tentativas
|
||||
de escrita; não é bug, é limite de plano. A UI do plugin marca isto
|
||||
lendo `editable` do resultado da API (ver `override_result_editable_if_has`
|
||||
no código) e desactiva o `<select>`/checkbox correspondente.
|
||||
|
||||
### EasyConfig — o que o botão "Easy config" aplica em bloco
|
||||
|
||||
`Repository\Cloudflare::setEasyMode()` (linha 723) aplica de uma vez, via
|
||||
`POST /zones/{zone}/settings` (bulk) + 5 chamadas individuais:
|
||||
|
||||
```
|
||||
0rtt=on, browser_cache_ttl=0, cache_level=aggressive, early_hints=on,
|
||||
http3=on, ip_geolocation=on, ipv6=on, min_tls_version=1.2,
|
||||
opportunistic_encryption=on, opportunistic_onion=on, pseudo_ipv4=off,
|
||||
rocket_loader=off, tls_1_3=zrt, websockets=on,
|
||||
security_level=essentially_off (fora do WordPress; 'medium' fora do XF)
|
||||
|
||||
+ settings/nel → {"value":{"enabled":false}}
|
||||
+ settings/origin_max_http_version → {"value":"2"}
|
||||
+ settings/speed_brain → {"value":"on"}
|
||||
+ settings/fonts → {"value":"on"}
|
||||
+ argo/tiered_caching → {"value":"on"}
|
||||
```
|
||||
|
||||
Não toca em SSL/TLS (excepto `min_tls_version`/`opportunistic_encryption`),
|
||||
Bot Management, WAF, HSTS nem Scrape Shield — o EasyConfig é só Speed +
|
||||
Caching + Network básico. Preferir aplicar definição a definição (§7 desta
|
||||
skill) para manter controlo e rasto de decisão, como já recomendado no
|
||||
achado original.
|
||||
|
||||
---
|
||||
|
||||
## 2. WAF real — o toggle `waf` está morto, usar Managed Ruleset
|
||||
|
||||
O toggle legado `waf` está **deprecated para zonas novas**: `PATCH
|
||||
/zones/{id}/settings/waf` devolve `1027 WAF is deprecated for this zone`
|
||||
independentemente do valor enviado. O mecanismo real de protecção é a fase
|
||||
de ruleset `http_request_firewall_managed`, que **pode estar completamente
|
||||
vazia** (zero regras, zero protecção) mesmo num site "protegido pelo
|
||||
Cloudflare" — foi o estado encontrado em `emanuelalmeida.pt` antes da
|
||||
correcção.
|
||||
|
||||
```bash
|
||||
# 1. Confirmar se a fase managed já tem entrypoint com regras
|
||||
curl -s -H "Authorization: Bearer $TOKEN" \
|
||||
"https://api.cloudflare.com/client/v4/zones/$ZONE/rulesets/phases/http_request_firewall_managed/entrypoint" | jq .
|
||||
# Vazio/erro "could not find entrypoint" = zero protecção real, apesar do que o toggle `waf` sugere
|
||||
|
||||
# 2. Implantar o Cloudflare Managed Free Ruleset na fase managed
|
||||
curl -s -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
"https://api.cloudflare.com/client/v4/zones/$ZONE/rulesets/phases/http_request_firewall_managed/entrypoint" \
|
||||
-d '{
|
||||
"rules": [
|
||||
{
|
||||
"action": "execute",
|
||||
"action_parameters": {
|
||||
"id": "77454fe2d30c4220b5701f6fdfb893ba"
|
||||
},
|
||||
"expression": "true",
|
||||
"description": "Cloudflare Managed Free Ruleset"
|
||||
}
|
||||
]
|
||||
}' | jq .
|
||||
```
|
||||
|
||||
`77454fe2d30c4220b5701f6fdfb893ba` é o ID do **Cloudflare Managed Free
|
||||
Ruleset** — disponível em qualquer plano, incluindo Free Website. Testar
|
||||
sempre com um pedido real (POST/AJAX contra o site) depois de implantar,
|
||||
não confiar só no `200 OK` do PUT.
|
||||
|
||||
A fase `http_request_firewall_custom` (regras próprias, não geridas) fica
|
||||
tipicamente vazia (`10003 could not find entrypoint`) num site sem regras
|
||||
custom — não é erro, é "zero regras próprias, só o Managed Ruleset". O
|
||||
plugin (versão Pro) gere regras custom através da página **Firewall**
|
||||
(§10) — "User agents" e "IP addresses" são interfaces amigáveis para criar
|
||||
regras Custom Rules na fase `http_request_firewall_custom` sem precisar de
|
||||
escrever expressões Cloudflare manualmente.
|
||||
|
||||
**Rocket Loader não substitui isto.** `rocket_loader` é uma definição de
|
||||
**Speed** (adia/reordena `<script>` no browser), não de segurança — o
|
||||
próprio plugin marca-o `not_good_alert` (recomenda desligado). Testado
|
||||
nesta sessão como hipótese de causa de CLS elevado num site: desligar não
|
||||
resolveu o CLS, mas manter desligado continua a ser a recomendação do
|
||||
plugin por outras razões (risco de quebra em sites com jQuery/Elementor).
|
||||
`speed_brain` é o sucessor recomendado pela Cloudflare (substitui Rocket
|
||||
Loader e Mirage), mas está marcado `beta` no código do plugin.
|
||||
|
||||
---
|
||||
|
||||
## 3. HSTS (`security_header`)
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
"https://api.cloudflare.com/client/v4/zones/$ZONE/settings/security_header" \
|
||||
-d '{
|
||||
"value": {
|
||||
"strict_transport_security": {
|
||||
"enabled": true,
|
||||
"max_age": 15552000,
|
||||
"include_subdomains": true,
|
||||
"preload": false,
|
||||
"nosniff": true
|
||||
}
|
||||
}
|
||||
}' | jq .
|
||||
```
|
||||
|
||||
**Gotcha real desta sessão:** se a origem (nginx) já envia o seu próprio
|
||||
header `Strict-Transport-Security`, **o HSTS do Cloudflare não o sobrepõe**
|
||||
— é comportamento documentado, não bug. Confirmar com `curl -sI` que o
|
||||
`cf-cache-status` do pedido é `MISS`/`DYNAMIC` (não é cache stale) e que o
|
||||
`max-age` devolvido é o da origem, não o configurado no Cloudflare. Ajustar
|
||||
o `max_age` a partir da origem (nginx) quando o objectivo for realmente
|
||||
mudar o valor visto pelo browser.
|
||||
|
||||
`preload: false` é deliberado por omissão — entrar na lista de preload dos
|
||||
browsers é quase irreversível (remoção demora meses/anos a propagar). Só
|
||||
activar depois de HSTS estável em produção há semanas sem incidentes.
|
||||
|
||||
O "bom" (`good`) definido no código do plugin para este campo é
|
||||
`max_age: 31536000` (12 meses), `include_subdomains: 1`, `preload: 1`,
|
||||
`nosniff: ''` (vazio, i.e. não activa X-Content-Type-Options via este
|
||||
mecanismo) — mais agressivo do que o valor sugerido na correcção original
|
||||
desta skill (6 meses). Escolher em função do risco de subdomínios não
|
||||
cobertos por HTTPS antes de ir para 12 meses + preload.
|
||||
|
||||
---
|
||||
|
||||
## 4. Certificate Transparency e Leaked Credential Checks
|
||||
|
||||
Endpoints próprios, fora do bulk `settings`:
|
||||
|
||||
```bash
|
||||
# Certificate Transparency (alertas quando um certificado é emitido para o domínio)
|
||||
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
"https://api.cloudflare.com/client/v4/zones/$ZONE/ct/alerting" \
|
||||
-d '{"enabled": true}' | jq .
|
||||
|
||||
# Leaked Credential Checks (avisa se credenciais usadas no site apareceram em leaks conhecidos)
|
||||
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
"https://api.cloudflare.com/client/v4/zones/$ZONE/leaked-credential-checks" \
|
||||
-d '{"enabled": true}' | jq .
|
||||
```
|
||||
|
||||
Ambos vinham `off` por omissão num site com anos de conta Cloudflare — não
|
||||
assumir que "conta antiga = tudo activo por defeito"; a Cloudflare tem
|
||||
adicionado features de segurança ao longo do tempo sem as retroactivar em
|
||||
zonas já existentes.
|
||||
|
||||
---
|
||||
|
||||
## 5. Bot Management (endpoint `/bot_management`) — 7 campos + `is_robots_txt_managed`
|
||||
|
||||
Endpoint próprio: `GET`/`PUT /zones/{zone}/bot_management` (não faz parte
|
||||
do bulk `settings`, e **não aceita `PATCH`**). Estes campos foram
|
||||
verificados via chamada directa à API (não são geridos pela UI do plugin
|
||||
através de `getSettingsToManage()`, ao contrário dos campos do §5a) — o
|
||||
plugin não expõe `content_bots_protection`, `ai_training`, `ai_search`,
|
||||
`ai_user` nem `is_robots_txt_managed` na sua própria página de Settings,
|
||||
mas estes são campos reais e válidos do endpoint `bot_management` da
|
||||
Cloudflare, geríveis por chamada directa à API.
|
||||
|
||||
| Campo | Padrão óptimo Descomplicar® | O que faz mal se ligado |
|
||||
|---|---|---|
|
||||
| `ai_bots_protection` | `disabled` | Bloqueia crawlers de IA (GPTBot, ClaudeBot, etc.) — visto `block` activo em 2 sites do bundle |
|
||||
| `content_bots_protection` | `disabled` | Idem, granularidade diferente |
|
||||
| `crawler_protection` | `disabled` | Bloqueia crawlers genéricos |
|
||||
| `ai_training` | `disabled` | Bloqueia bots de treino de modelos |
|
||||
| `ai_search` | `disabled` | Bloqueia bots de motores de busca IA |
|
||||
| `ai_user` | `disabled` | Bloqueia bots accionados por utilizador de IA (ex. ChatGPT a navegar em nome do utilizador) |
|
||||
| `fight_mode` | `false` | Desafia (challenge JS) tráfego automatizado por heurística — apanha crawlers legítimos de IA que não resolvem JS challenges, visto a devolver "Just a moment..." em vez de conteúdo real |
|
||||
|
||||
**Achado real desta sessão (GEO):** com `is_robots_txt_managed: true`, o
|
||||
Cloudflare **injecta directivas `Disallow: /`** no `robots.txt` servido
|
||||
para estes user-agents, por cima do ficheiro físico do site — mesmo que o
|
||||
ficheiro físico já permita esses bots explicitamente. Parsers que fundem
|
||||
grupos do mesmo user-agent aplicam o `Disallow` na mesma, tornando a
|
||||
permissão do ficheiro físico letra morta.
|
||||
|
||||
```bash
|
||||
# Ler estado actual
|
||||
curl -s -H "Authorization: Bearer $TOKEN" \
|
||||
"https://api.cloudflare.com/client/v4/zones/$ZONE/bot_management" | jq .
|
||||
|
||||
# Corrigir — PUT, NUNCA PATCH (PATCH devolve sempre 10405 Method not allowed,
|
||||
# independentemente das permissões do token)
|
||||
curl -s -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
"https://api.cloudflare.com/client/v4/zones/$ZONE/bot_management" \
|
||||
-d '{
|
||||
"ai_bots_protection": "disabled",
|
||||
"content_bots_protection": "disabled",
|
||||
"crawler_protection": "disabled",
|
||||
"ai_training": "disabled",
|
||||
"ai_search": "disabled",
|
||||
"ai_user": "disabled",
|
||||
"fight_mode": false,
|
||||
"is_robots_txt_managed": false
|
||||
}' | jq .
|
||||
```
|
||||
|
||||
Depois de corrigir, **purgar cache** (Cloudflare + cache local WP, ex. WP
|
||||
Fastest Cache) — `robots.txt` costuma ter `cache-control:
|
||||
max-age=315360000`, a correcção não aparece sem purge. Confirmar ao vivo
|
||||
com `curl -sI` que `cf-cache-status` não é `HIT` e o corpo já não tem
|
||||
`Disallow: /` para os bots visados.
|
||||
|
||||
### 5a. Super Bot Fight Mode — campos geridos pela própria UI do plugin
|
||||
|
||||
Ao contrário do §5 (chamada directa, campos fora da UI), estes 8 campos
|
||||
**são** geridos por `getSettingsToManage()` e aparecem na tab "Security"
|
||||
da página Settings do plugin. Todos escrevem no mesmo endpoint `PUT
|
||||
/bot_management`, mas com nomes de campo JSON diferentes do que o `id` da
|
||||
definição no plugin:
|
||||
|
||||
| ID no plugin | Campo real na API `bot_management` | Bom (`good`) |
|
||||
|---|---|---|
|
||||
| `bot_fight_mode` | `fight_mode` | `false` |
|
||||
| `ai_bots_protection` | `ai_bots_protection` | `block` *(nota: o `good` do código é `block`, oposto do padrão Descomplicar do §5 — ver decisão abaixo)* |
|
||||
| `crawler_protection` | `crawler_protection` | `enabled` *(idem — oposto do padrão Descomplicar)* |
|
||||
| `bot_likely_automated` | `sbfm_likely_automated` (select `allow`/`block`/`managed_challenge`) | `allow` |
|
||||
| `bot_definitely_automated` | `sbfm_definitely_automated` (select `allow`/`block`/`managed_challenge`) | `allow` |
|
||||
| `bot_verified_bots` | `sbfm_verified_bots` (select `allow`/`block`) | `allow` |
|
||||
| `bot_static_resource_protection` | `sbfm_static_resource_protection` (bool) | `false` |
|
||||
| `bot_optimize_wordpress` | `optimize_wordpress` (bool) | `false` |
|
||||
| `bot_enable_js` | `enable_js` (bool) — comentário no código: "a API diz que é editável, mas só é possível de facto em plano Pro ou superior" | `false` |
|
||||
|
||||
**Contradição intencional a documentar:** o `good` que o código do plugin
|
||||
define para `ai_bots_protection`/`crawler_protection` é o valor "block"/
|
||||
"enabled" (i.e. o próprio autor do plugin recomenda bloquear bots de IA
|
||||
por omissão). A decisão Descomplicar® (documentada no §5 e no gotcha da
|
||||
tabela §7) é o oposto — **nunca bloquear bots de IA em nenhum site do
|
||||
bundle**, por ser GEO-crítico (visibilidade em AI Overviews/ChatGPT/
|
||||
Perplexity). Ao corrigir zonas, ignorar deliberadamente o "good" do plugin
|
||||
para estes 2 campos específicos e aplicar sempre `disabled`.
|
||||
|
||||
Todas as escritas neste grupo enviam `unset_on_write: ['using_latest_model']`
|
||||
— o código remove explicitamente esse campo do payload antes de fazer
|
||||
`PUT`, porque `using_latest_model` é campo só de leitura devolvido pela API
|
||||
(indica se a Cloudflare está a usar o modelo de detecção de bots mais
|
||||
recente) e a API rejeita o `PUT` se ele for reenviado.
|
||||
|
||||
---
|
||||
|
||||
## 6. Scopes de token — lista completa (21 permissões, do código de setup)
|
||||
|
||||
`Admin/Template/MultisiteSettings.php` e `Admin/Template/Settings.php`
|
||||
embutem a lista completa e oficial de scopes recomendados pelo autor do
|
||||
plugin (usada para construir o link de criação de token pré-preenchido no
|
||||
dashboard Cloudflare) — muito mais granular do que os 6 grupos informais
|
||||
documentados na versão anterior desta skill:
|
||||
|
||||
| Scope Cloudflare | Nível de acesso | Necessário para |
|
||||
|---|---|---|
|
||||
| `Account.Access: Apps and Policies` | Edit | Zero Trust Access (página Access, Pro) |
|
||||
| `Account.Access: Organizations, Identity Providers, and Groups` | Read | Zero Trust Access — resolver grupos/IdPs nas políticas |
|
||||
| `Account.Account Analytics` | Read | Dados agregados de conta (não usado nesta skill) |
|
||||
| `Account.Account Settings` | Read + Edit | Detalhes/definições de conta Cloudflare |
|
||||
| `Account.Allow Request Tracer` | Read | Página "HTTP request trace" (§10) |
|
||||
| `Account.Billing` | Read | Info de plano/facturação Cloudflare mostrada no plugin |
|
||||
| `Account.Intel` | Read | Páginas "IP address details"/"Domain details"/"WHOIS" (Cloudflare Intel API, §10) |
|
||||
| `Account.Turnstile` | Edit | Criar/gerir sitekeys Turnstile CAPTCHA (§8, `cfTurnstile`) |
|
||||
| `Account.Workers R2 Storage` | Edit | R2 media storage (página R2, Pro) |
|
||||
| `Account.Workers Scripts` | Edit | Worker proxy (`cfWorkersSubdomain`/`cfProxy`, §8) |
|
||||
| `User.API Tokens` | Read | O plugin lê as próprias permissões do token para colorir a checklist de setup a verde |
|
||||
| `Zone.Analytics` | Read | Web Analytics / dashboards de tráfego |
|
||||
| `Zone.Bot Management` | Edit | Bot Management + Super Bot Fight Mode (§5, §5a) — **separado** do Zone Settings, falta frequentemente no token gerado por omissão |
|
||||
| `Zone.Cache Purge` | Purge | Purge de cache (página "Purge cache", botão admin bar) |
|
||||
| `Zone.Cache Rules` | Edit | Cache Rules (página Rules, Pro) |
|
||||
| `Zone.Firewall Services` | Edit | Firewall Rules, regras de User-Agent/IP (página Firewall, Pro) |
|
||||
| `Zone.Page Rules` | Edit | Page Rules legadas (página Rules, Pro) |
|
||||
| `Zone.SSL and Certificates` | Edit | Certificate Transparency, TLS client auth |
|
||||
| `Zone.Zone` | Edit | Operações de gestão da própria zona |
|
||||
| `Zone.Zone Settings` | Edit | As ~52 definições de zona do §1 (SSL/TLS, Speed, Caching, Network, Scrape Shield) |
|
||||
| `Zone.Zone WAF` | Edit | WAF/Managed Ruleset (§2) |
|
||||
|
||||
`Zone.DNS` **não está na lista oficial do plugin** — o plugin não gere DNS
|
||||
(DMARC/SPF/DKIM são lidos como registos públicos via `dig`, ver §7/§10, não
|
||||
via API Cloudflare autenticada).
|
||||
|
||||
**Sintoma de scope em falta:** a API devolve `403` ou o próprio plugin
|
||||
mostra um erro de permissão específico à operação, não um erro genérico de
|
||||
autenticação — o token pode estar válido e ainda assim faltar-lhe
|
||||
exactamente o scope daquela chamada. Testado nesta sessão: token com `Zone
|
||||
SSL/Settings Edit` funcionava para as definições de zona mas falhava em
|
||||
Bot Management até se alargar explicitamente o scope no dashboard
|
||||
Cloudflare (`My Profile → API Tokens → editar token`).
|
||||
|
||||
---
|
||||
|
||||
## 7. Gotchas e erros comuns
|
||||
|
||||
| Sintoma | Causa | Solução |
|
||||
|---|---|---|
|
||||
| `PATCH /zones/{id}/settings/waf` → `1027 WAF is deprecated for this zone` | Toggle legado morto para zonas novas | Implantar Managed Ruleset na fase `http_request_firewall_managed` (§2) |
|
||||
| `PATCH /zones/{id}/bot_management` → `10405 Method not allowed` | Endpoint só aceita `PUT` | Usar `PUT` sempre, mesmo para alterar um único campo (envia o objecto completo) |
|
||||
| Correcção de `robots.txt`/HSTS não aparece no browser | Header/ficheiro servido a partir de cache (Cloudflare e/ou plugin de cache WP) | Purgar Cloudflare + cache WP local; confirmar `cf-cache-status` não é `HIT` antes de validar |
|
||||
| HSTS configurado no Cloudflare mas browser continua a ver `max-age` diferente | Origem (nginx) já envia o seu próprio header `Strict-Transport-Security` — Cloudflare **não sobrepõe** HSTS que a origem já envia | Ajustar na origem, ou aceitar que o Cloudflare é só fallback para origens sem HSTS próprio |
|
||||
| Regra de firewall/Transform Rule com operador `matches` (regex) falha ou não fica disponível na UI | `matches` exige plano **Business** (WAF Advanced) | Reescrever a expressão com `in`, `eq` ou `contains` — disponíveis em qualquer plano, incluindo Free |
|
||||
| `wp option update app_for_cf '...'` apaga sub-chaves que não estavam no valor enviado | `wp option update` substitui a opção inteira; `app_for_cf` é um array serializado | Usar `wp option patch update app_for_cf <chave> <valor>` para editar uma sub-chave sem tocar nas restantes |
|
||||
| R2 (media storage) devolve `10042 Please enable R2 through the Cloudflare Dashboard` | R2 não está activado a nível de **conta** (não é definição de zona nem do plugin) | Activar manualmente no dashboard Cloudflare da conta antes de qualquer chamada à API de R2 |
|
||||
| `ai_bots_protection`/`crawler_protection` a `block`/`enabled` num site do bundle | Divergência do padrão óptimo — visto em `carstuff.pt` e `solarfvengenharia.com` nesta sessão; **o próprio `good` do código do plugin recomenda `block`** (§5a), por isso corrigir manualmente sempre que se aplicar EasyConfig ou se seguir uma recomendação genérica do plugin | Corrigir para `disabled` via `PUT /bot_management` (§5) — decisão explícita: nunca bloquear bots de IA em nenhum site Descomplicar |
|
||||
| Página "Public page caching"/"Purge cache"/analytics parecem não fazer nada de imediato | `handleHeaders()` só define `Cache-Control: max-age=0,s-maxage=X` — depende do Cloudflare respeitar esse header (`cache_level`/`browser_cache_ttl` compatíveis) e de não haver cookies de sessão a bloquear o cache (ver §9) | Confirmar `browser_cache_ttl` = "Respect existing headers" (`0`) e `cache_level` ≠ `basic`; testar em aba anónima sem cookies `wp-*`/`wordpress_*`/`comment_*`/`woocommerce_*` |
|
||||
| Botões "Firewall", "Access", "Rules" (criar regra), "R2", "Copy from...", "License key" aparecem desactivados/a cinzento ou com classe `pro` | Funcionalidade gated para a versão **Premium/Pro** do plugin (`Helper\Api::check()` — ver §11) | Confirmar licença activa (`cfLicenseKey`) ou aceitar a limitação no plano Free |
|
||||
| `wp option get app_for_cf` mostra `cfTurnstile:["0"]` em vez do array completo com `siteKey`/`onLogin`/etc. | Turnstile nunca foi activado neste site — o checkbox "Use Turnstile CAPTCHA" desmarcado grava só `[0]` (o `<input type="hidden" value="0">` do formulário), não o array completo de `Setup::defaults()` | Normal em sites sem Turnstile configurado; a estrutura completa (13 sub-chaves, ver §8) só aparece depois de gerar uma sitekey e gravar o formulário |
|
||||
|
||||
---
|
||||
|
||||
## 8. Config do plugin (`wp_options.app_for_cf`) — as 18 chaves em detalhe
|
||||
|
||||
Fonte: `Setup::defaults()` (schema oficial de instalação) cruzado com a
|
||||
leitura ao vivo (`wp option get app_for_cf`) em `emanuelalmeida.pt`
|
||||
(16-08-2026) — as 18 chaves batem certo entre defaults e produção.
|
||||
|
||||
```json
|
||||
{"cfWorkersSubdomain":"","cfProxy":{"image":"0","url":"0"},"cfR2Bucket":{"media":""},"cfAccountId":"a8b00ad3227d729a146143a6a85a7522","cfZoneId":"574b243ebabd8ea2b8d89e68921f52cc","cfTokenId":"6b6d24fe8d324112ea4cfc328bf16f6c","cfZone":"emanuelalmeida.pt","cfPageCachingSeconds":"21600","cloudflareAuth":{"token":"cfut_..."},"cloudflareFirewallExpireDays":"7","cloudflareBlockIpsSpamClean":"0","cfExternalDataUrl":"","cloudflarePreload":"1","cfImagesTransform":"0","cfLicenseKey":"","cfPurgeCacheOnAdminBar":"1","cfTurnstile":["0"],"LockSettingsUserId":"1"}
|
||||
```
|
||||
|
||||
| Chave | Tipo/Default | O que faz |
|
||||
|---|---|---|
|
||||
| `cfWorkersSubdomain` | string, `''` | Subdomínio `*.workers.dev` da conta Cloudflare, usado quando o Worker proxy (R2/imagens) está activo |
|
||||
| `cfProxy.image` / `cfProxy.url` | `0`/`1` cada | Toggle interno para saber se URLs de imagem/media já estão a ser reescritas para servir via Worker/R2 (usado por `filterWpGetAttachmentUrl()`/`filterWpCalculateImageSrcset()` em `Base/Pub.php`) |
|
||||
| `cfR2Bucket.media` | string, `''` | Nome do bucket R2 escolhido/criado para armazenar media da biblioteca WordPress (feature Pro, página R2) |
|
||||
| `cfAccountId` | string | ID da conta Cloudflare — resolvido automaticamente por `getZoneId()` a partir do hostname na primeira chamada, cacheado aqui |
|
||||
| `cfZoneId` | string | ID da zona Cloudflare — idem, cacheado para evitar `listZones()` a cada pedido |
|
||||
| `cfTokenId` | string | ID do token API (não o valor secreto) — mostrado na UI como referência ("Token ID: ...") para o admin confirmar qual token está activo |
|
||||
| `cfZone` | string | Nome do domínio da zona (ex. `emanuelalmeida.pt`), cacheado junto com `cfAccountId`/`cfZoneId` |
|
||||
| `cfPageCachingSeconds` | int (segundos), `''` (vazio = desligado) | Tempo de `s-maxage` aplicado ao HTML para guests (§9) — `0`/vazio desliga o guest page caching |
|
||||
| `cloudflareAuth.type` | `'token'` ou `'email'` | Modo de autenticação — `token` é o único usado/recomendado; `email`+`api_key` é o modo legado Global API Key |
|
||||
| `cloudflareAuth.token` | string secreta | Bearer token da Cloudflare API, scoped (ver permissões no §6) |
|
||||
| `cloudflareAuth.email` / `cloudflareAuth.api_key` | string, `''` | Só usados se `type = 'email'` (não usar) |
|
||||
| `cloudflareFirewallExpireDays` | int, default `7` (1-90) | Dias até uma regra de firewall **criada automaticamente pelo plugin** (ex. bloqueio de IP de spammer, feature Pro) expirar sozinha |
|
||||
| `cloudflareBlockIpsSpamClean` | `0`/`1`, default `1` | Se `1`, bloqueia automaticamente (feature Pro) o IP de um utilizador cujo comentário foi marcado como spam pela fila de moderação do WordPress |
|
||||
| `cfExternalDataUrl` | string URL, `''` | URL pública onde o media fica acessível quando R2 está activo — normalmente auto-preenchido ao activar R2, não editar manualmente salvo troubleshooting |
|
||||
| `cloudflarePreload` | `0`/`1`, default `1` | Se `1`, o plugin usa hooks `script_loader_tag`/`style_loader_tag`/`wp_footer` para emitir headers HTTP `Link: <url>;rel=preload` (até 10 recursos) — funciona em conjunto com a definição de zona `early_hints` |
|
||||
| `cfImagesTransform` | `0`/`1`, default `0` | Se `1`, activa **Cloudflare Images Transform** para blocos de imagem/media (serve AVIF/WebP a browsers modernos, formatos mais antigos a browsers antigos, qualidade reduzida em ligações muito lentas) — requer activação também a nível de zona no dashboard Cloudflare |
|
||||
| `cfLicenseKey` | string, `''` | Chave de licença da versão Premium/Pro do plugin — sem isto, `Helper\Api::check()` devolve sempre `false` (ver §11) |
|
||||
| `cfPurgeCacheOnAdminBar` | `0`/`1`, default `0` | Se `1`, mostra um botão de purge de cache com um clique na admin bar do WordPress |
|
||||
| `cfTurnstile` | array com 13 sub-chaves quando activo: `siteKey`, `secretKey`, `onRegister`, `onLogin`, `onPassword`, `onComment`, `onContactForm7`, `onHtmlForms`, `onMetForm`, `onWPForms`, `onWooCommerceRegister`, `onWooCommerceLogin`, `onWooCommercePassword` | CAPTCHA Turnstile aplicado por contexto — cada `onX` é um toggle independente que decide se o widget Turnstile aparece nesse formulário específico (registo/login/reset password/comentários WP nativos, WooCommerce, e os plugins de formulário Contact Form 7/HTML Forms/MetForm/WPForms se estiverem instalados) |
|
||||
| `LockSettingsUserId` | `0` ou ID de utilizador WP | Se preenchido com um ID de utilizador, **só essa conta WordPress** pode alterar as definições Cloudflare a partir do wp-admin — risco: apagar essa conta ou trocar de utilizador tranca o acesso às definições |
|
||||
|
||||
`network_exclude` (visto em código de multisite, `Settings.php` linha 290)
|
||||
é uma chave adicional só relevante em instalações multisite — indica que
|
||||
um site individual optou explicitamente por **não** herdar o token
|
||||
API de rede.
|
||||
|
||||
---
|
||||
|
||||
## 9. Guest page caching (HTML a nível de edge) — como funciona de facto
|
||||
|
||||
Página "Public page caching" (§10) e a chave `cfPageCachingSeconds` (§8)
|
||||
não usam Page Rules nem Cache Rules Cloudflare — usam um mecanismo mais
|
||||
simples e mais portável: o hook `wp_headers` do WordPress
|
||||
(`Base\Pub::handleHeaders()`, `Base/Pub.php` linha 276) define
|
||||
```
|
||||
Cache-Control: max-age=0,s-maxage=<cfPageCachingSeconds>
|
||||
```
|
||||
em toda resposta HTML elegível. `max-age=0` diz ao browser para não
|
||||
cachear localmente; `s-maxage=<N>` diz a caches partilhadas (o edge da
|
||||
Cloudflare) para cachear durante N segundos — desde que a definição de
|
||||
zona `browser_cache_ttl` esteja em `0` ("Respect Existing Headers", o
|
||||
padrão recomendado no §1) e `cache_level` não seja `basic`.
|
||||
|
||||
**Critérios de elegibilidade** (`pageCachingCriteria()`, filtráveis via
|
||||
`app_for_cf_guest_page_cacheable`):
|
||||
- Utilizador **não** tem sessão WordPress activa (`is_user_logged_in()`
|
||||
falso)
|
||||
- Nenhum cookie do browser começa por `wp-`, `wordpress_`, `comment_`
|
||||
ou `woocommerce_` (senão a página é tratada como dinâmica/pessoal e o
|
||||
header de cache não é aplicado)
|
||||
- Pedido não é para `/wp-login.php`
|
||||
- Content-Type da resposta começa por `text/html`
|
||||
- Página não é 404
|
||||
- `WP_DEBUG` não está activo
|
||||
|
||||
Por omissão o valor sugerido na UI é 6 horas (`21600` segundos, a mesma
|
||||
opção `default` usada em `CachingGuestPage.php`); opções disponíveis vão
|
||||
de 5 minutos a 24 horas, filtráveis via `app_for_cf_cache_times`, e o
|
||||
limite máximo é derivado da vida do nonce do WordPress
|
||||
(`DAY_IN_SECONDS - 3600`, tipicamente 23h).
|
||||
|
||||
```bash
|
||||
# Ler/alterar o tempo de guest page caching
|
||||
wp option pluck app_for_cf cfPageCachingSeconds --allow-root --path=$PATH
|
||||
wp option patch update app_for_cf cfPageCachingSeconds 21600 --allow-root --path=$PATH # 6h
|
||||
wp option patch update app_for_cf cfPageCachingSeconds '' --allow-root --path=$PATH # desligar
|
||||
```
|
||||
|
||||
Como não é uma Page/Cache Rule, **não aparece no dashboard Cloudflare**
|
||||
como regra — só é visível inspeccionando o header `Cache-Control` da
|
||||
resposta HTTP (`curl -sI https://SITE/`) e o `cf-cache-status`.
|
||||
|
||||
---
|
||||
|
||||
## 10. As 14 páginas de admin — o que cada uma faz
|
||||
|
||||
Estrutura de menu confirmada em `Admin/Base/Admin.php`. O item de topo
|
||||
(`Cloudflare`, ícone `dashicons-cloud`) mostra um badge `!` quando não há
|
||||
token configurado.
|
||||
|
||||
| Slug (`page=`) | Título no menu | O que faz |
|
||||
|---|---|---|
|
||||
| `app-for-cf_caching` | **Public page caching** | Toggle + selector de tempo para o guest page caching do §9 (`cfPageCachingSeconds`) |
|
||||
| `app-for-cf_firewall` | **Firewall** | 3 tabelas: **Firewall Rules** (link "Create rule" abre o dashboard Cloudflare — Pro), **User agents** (regras de bloqueio por user-agent geridas inline — Pro) e **IP addresses** (bloqueio manual por IP — Pro); todas suportam bulk enable/disable/delete via `bulkActionNotice()` |
|
||||
| `app-for-cf_access` | **Access** | Lista de Zero Trust Access Apps + Groups da conta, com delete em massa (feature **Pro** — cria políticas de acesso, ex. proteger `/wp-admin` com SSO) |
|
||||
| `app-for-cf_rules` | **Rules** | 2 tabelas: **Page Rules** legadas (link "Create page rule" abre dashboard — Pro) e **Cache Rules** modernas (link "Create cache rule" — Pro) |
|
||||
| `app-for-cf_r2` | **R2 (media storage)** | Explica e liga a biblioteca de media do WordPress a um bucket Cloudflare R2 (10GB grátis, depois $0.015/GB); requer token válido **e** licença Pro |
|
||||
| `app-for-cf_cache` | **Purge cache** | Botão único "Purge Cloudflare cache..." — chama `purgeCache()` sem filtro (`Purge Everything`) |
|
||||
| `options-general.php?page=app-for-cf` | **Settings** (link para `wp-admin/options-general.php?page=app-for-cf`) | A página principal com as 6 tabs de definições de zona (Setup/SSL-TLS/Security/Speed/Caching/Network+Scrape Shield) — ver §1; badge "Missing API token" se `cloudflareAuth.token` vazio |
|
||||
| `app-for-cf_analytics` | **Web analytics** | Toggle único para injectar o beacon JavaScript do Cloudflare Web Analytics (privacy-first, sem cookies) em todas as páginas; link directo para o dashboard de analytics quando activo |
|
||||
| `app-for-cf_dmarc` | **DMARC management** | Gráfico (Chart.js) de volume de email pass/fail por semana/mês + tabela de fontes de envio detectadas via os relatórios DMARC que a Cloudflare recebe em nome do domínio; link "View in Cloudflare" para o dashboard |
|
||||
| `app-for-cf_request-trace` | **HTTP request trace** | Formulário para simular um pedido (URL, método, protocolo, bot score, país, threat score, skip challenge) e ver que produtos/regras Cloudflare seriam aplicados — requer scope `Account.Allow Request Tracer` |
|
||||
| `app-for-cf_ip-details` | **IP address details** | Consulta a Cloudflare Intel API para um IP: PTR, ASN/organização, tipo, risk types — requer `Account.Intel:Read` |
|
||||
| `app-for-cf_domain-details` | **Domain details** | Idem para domínios: tipo, IPs de resolução, categorias de conteúdo |
|
||||
| `app-for-cf_whois` | **WHOIS** | Consulta WHOIS via Cloudflare Intel: datas de criação/actualização, registrant, registrar, nameservers |
|
||||
| (sem entrada de menu própria) **Copy Settings** | acedida a partir de um botão na página Settings | Copia todas as definições de zona de uma zona diferente da mesma conta Cloudflare para a zona actual — **irreversível**, exige confirmação explícita ("I understand...") antes de activar o botão de submissão |
|
||||
|
||||
Páginas exclusivas de **multisite network admin** (`settings.php?page=`):
|
||||
|
||||
| Slug | Título | O que faz |
|
||||
|---|---|---|
|
||||
| `app-for-cf_multisite-settings` | **Cloudflare** (em Network Admin → Settings) | Define um token API partilhado por toda a rede (`app_for_cf_network`), com a mesma checklist de 21 permissões do §6; cada site individual pode optar por usar o token de rede ou o seu próprio |
|
||||
| `app-for-cf_multisite-r2` | **R2 (media storage)** (Network Admin) | Um único bucket R2 partilhado por todos os sites da rede, com o caminho de cada ficheiro prefixado por `{siteId}/` (ex. `cdn.site.com/50/2023/10/image.png`) — feature Pro, licenciada ao hostname do site principal da rede |
|
||||
|
||||
---
|
||||
|
||||
## 11. Free vs Pro — gate `Helper\Api::check()`
|
||||
|
||||
`Helper\Api::$version` / `Helper\Api::check($force = false)` (`Helper/Api.php`)
|
||||
determina se a licença Premium está activa através de um **transient**
|
||||
(`acf_int`) com 6 horas de validade (`21600` segundos) — não é lido de
|
||||
`cfLicenseKey` directamente a cada pedido, é cacheado. `Setup::install()`
|
||||
chama `Api::check(true)` (forçado) na activação do plugin.
|
||||
|
||||
Funcionalidades bloqueadas/degradadas no plano Free (confirmado nos
|
||||
templates admin, condicional `Helper\Api::$version` ou classe CSS `pro`):
|
||||
- Botão "Create rule"/"Create page rule"/"Create cache rule"/"Create user
|
||||
agent rule"/"Create IP address rule" (Firewall, Rules) — sem eles, as
|
||||
tabelas continuam a **listar** regras já criadas manualmente no
|
||||
dashboard Cloudflare, só não permitem criar a partir do wp-admin
|
||||
- Página R2 (media storage) — bloqueada mesmo com token válido
|
||||
- Página Access (Zero Trust) — lista mas não gere
|
||||
- "Copy from..." (Copy Settings) — botão só aparece se
|
||||
`Helper\WordPress::hasOwnApiToken()` **e** implicitamente exige Pro
|
||||
para ser útil em produção
|
||||
- Campo "License key" só aparece se `Helper\Api::$version` já tiver
|
||||
alguma licença associada (mostra o campo para trocar/renovar)
|
||||
- "Block spammer IPs"/"Days that firewall rules last"/"External data
|
||||
URL" (`cloudflareBlockIpsSpamClean`, `cloudflareFirewallExpireDays`,
|
||||
`cfExternalDataUrl`) aparecem com classe CSS `pro` e `disabled` quando
|
||||
`(int)$cloudflareAppInternal` é falso — os campos ficam visíveis mas
|
||||
não editáveis
|
||||
|
||||
Todas as definições de zona do §1 (SSL/TLS, Speed, Caching, Network,
|
||||
Scrape Shield, Bot Management/SBFM), o WAF via Managed Ruleset (§2), HSTS
|
||||
(§3), Certificate Transparency/Leaked Credential Checks (§4), guest page
|
||||
caching (§9), purge de cache e Turnstile CAPTCHA (§8) **funcionam no plano
|
||||
Free do plugin** — não são gated, só dependem do plano Cloudflare
|
||||
subjacente (Free Website vs Pro/Business), que é uma dimensão diferente.
|
||||
|
||||
---
|
||||
|
||||
## 12. Automação — WP-CLI e Cron
|
||||
|
||||
```bash
|
||||
# Purgar cache Cloudflare (Purge Everything) via linha de comandos
|
||||
wp app-for-cf purge-cache --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
Implementado em `Cli/PurgeCache.php` (comando `app-for-cf purge-cache`,
|
||||
`@when after_wp_load`) — chama `Repository\Cloudflare::purgeCache()` sem
|
||||
argumentos (equivalente ao botão da página "Purge cache", §10).
|
||||
|
||||
`Cron\Jobs::purgeCache(array $urls)` é o mecanismo interno usado por
|
||||
`Base\Pub::purgeCacheByPostIds()` quando um post muda de estado
|
||||
(publicado/editado) ou um comentário muda de estado — faz **chunking em
|
||||
lotes de 30 URLs** por chamada à API de purge (limite da Cloudflare por
|
||||
pedido), parando o loop no primeiro chunk que falhar em vez de continuar a
|
||||
tentar os restantes.
|
||||
|
||||
---
|
||||
|
||||
## 13. Áreas do plugin sem config a auditar/activar (confirmado nesta sessão, `emanuelalmeida.pt`)
|
||||
|
||||
| Área | Estado |
|
||||
|---|---|
|
||||
| Cache Rules / Page Rules | 0 regras — `GET /zones/{id}/pagerules` → `count:0` |
|
||||
| Access (Zero Trust) | Não configurado, fora de âmbito nesta sessão — funcionalidade real do plugin, ver §10 |
|
||||
| Turnstile CAPTCHA | Site key existe mas desligada no plugin (`cfTurnstile: ["0"]`) — infra pronta se decidido substituir reCAPTCHA; ver estrutura completa das 13 sub-chaves no §8 |
|
||||
| Workers proxy (`cfProxy`) | `{image: off, url: off}` |
|
||||
| R2 (media storage) | `cfR2Bucket.media` vazio, `cfExternalDataUrl` vazio — nunca activado neste site; requer licença Pro (§11) |
|
||||
| DMARC/SPF/DKIM (`Dmarc.php`) | **Auditar via DNS público directo** (`dig TXT`), nunca precisa de token Cloudflare — são registos públicos por desenho; a página DMARC do plugin (§10) é sobre os relatórios agregados que a Cloudflare recebe, não sobre editar os próprios registos DNS |
|
||||
| Web Analytics (beacon JS) | Confirmar por ausência/presença de `cloudflareinsights`/`beacon.min.js` no HTML servido, não por option — a página Web Analytics (§10) tem toggle próprio fora de `wp_options` (via API, não confirmado nesta sessão se lê de zona ou de conta) |
|
||||
| EasyConfig (`setEasyMode()`) | Aplica tudo em bloco (lista exacta no §1) — preferir aplicar definição a definição para manter controlo e rasto de decisão |
|
||||
| Licença Pro (`cfLicenseKey`) | Vazia — plugin a correr em modo Free; ver §11 para o que fica indisponível |
|
||||
|
||||
---
|
||||
|
||||
## Fonte
|
||||
|
||||
`CONFIG-Plugins-Referencia.md` §1 (App for Cloudflare®) — achados originais
|
||||
de HSTS/WAF/DMARC, credenciais de sessão. `BUNDLE-Excelencia-WP.md` §2.2
|
||||
(Performance) e §2.4 (GEO — bots de IA, achado completo do
|
||||
`is_robots_txt_managed` e dos 7 campos de Bot Management via API directa).
|
||||
Ambos em `Hub/04-Stack/02.04-Sistemas/71.Seguranca/`, piloto
|
||||
`emanuelalmeida.pt`, sessão 16-08-2026.
|
||||
|
||||
**Expansão desta sessão (16-08-2026):** leitura completa do código-fonte
|
||||
do plugin `app-for-cf` v1.10.0 via SSH (`server`, 61 ficheiros PHP,
|
||||
11.309 linhas) — não apenas os ficheiros tocados na auditoria pontual
|
||||
original. Ficheiros lidos na íntegra: `app-for-cf.php` (bootstrap),
|
||||
`Setup.php` (schema de `wp_options`), `Repository/Cloudflare.php` (2178
|
||||
linhas — lista completa de 52 definições de zona + `setEasyMode()` +
|
||||
lógica de leitura/escrita), `Admin/Template/Settings.php` (766 linhas —
|
||||
UI completa, scopes de token, Turnstile), `Admin/Base/Admin.php` (menu,
|
||||
14 páginas), `Helper/Api.php` (gate Free/Pro), `Cron/Jobs.php`,
|
||||
`Cli/PurgeCache.php`, e os 14 templates individuais em `Admin/Template/`
|
||||
(`Firewall.php`, `R2.php`, `Access.php`, `Rules.php`, `Analytics.php`,
|
||||
`Dmarc.php`, `RequestTrace.php`, `IpDetails.php`, `DomainDetails.php`,
|
||||
`Whois.php`, `CachingGuestPage.php`, `Caching.php`, `Cache.php`,
|
||||
`CopySettings.php`, `MultisiteR2.php`, `MultisiteSettings.php`) e trechos
|
||||
relevantes de `Base/Pub.php` (657 linhas — guest page caching, preload,
|
||||
purge). Confirmado ao vivo com `wp option get app_for_cf --format=json`
|
||||
em `emanuelalmeida.pt` que as 18 chaves de `wp_options` batem certo com
|
||||
`Setup::defaults()`. Nenhuma escrita feita em produção durante esta
|
||||
expansão — só leitura de código-fonte e `wp option get`.
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
name: elementor-pro-widgets
|
||||
description: Catálogo completo e verificado dos widgets nativos Elementor Pro (30 gerais + 5 WooCommerce) e como os descobrir/adicionar via EMCP Tools. Usar quando "widgets elementor pro", "que widgets pro existem", "loop grid", "nested tabs", "form elementor pro", "table of contents elementor", "portfolio elementor", "reviews carousel elementor".
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# /elementor-pro-widgets — Catálogo de Widgets Nativos Elementor Pro
|
||||
|
||||
Catálogo obtido ao vivo via `list-widgets(tier:"pro")` num site Elementor Pro 4.0.0 (EMCP Tools), cruzado com a documentação oficial. Widget types testados como legacy (`add-free-widget`/`add-pro-widget` + `widget_type`), não atómicos — Elementor Pro ainda não migrou o catálogo completo para elementos atómicos 4.0.
|
||||
|
||||
## Como descobrir e adicionar (workflow)
|
||||
|
||||
1. `list-widgets({ tier: "pro" })` — confirma quais dos 30+5 abaixo estão realmente disponíveis nesta ligação (Elementor Pro tem de estar activo).
|
||||
2. `get-widget-schema({ widget_type })` — parâmetros curados (obrigatórios, defaults, enums). **Campo é `widget_type`, não `type`.**
|
||||
3. `add-pro-widget({ post_id, parent_id, widget_type, settings })` num container legacy (`add-container`), ou `add-free-widget` se a tool `add-pro-widget` estiver desligada nesse site (verificar com `list-widgets` primeiro — `tier:"pro"` a devolver resultados não implica que `add-pro-widget` esteja montada; é frequentemente a primeira tool fechada num deny-list de produção).
|
||||
4. Ver skill `emcp-page-building` para as regras de coexistência atómico/legacy e para `batch-update`/`update-element` genérico.
|
||||
|
||||
## Catálogo — widgets gerais (30)
|
||||
|
||||
| `widget_type` | Título | Uso |
|
||||
|---|---|---|
|
||||
| `form` | Form | Formulários de contacto/captação com tipos de campo configuráveis, acções de submissão |
|
||||
| `posts` | Posts Grid | Grelha pesquisável de posts/pages com contagem de colunas e paginação |
|
||||
| `countdown` | Countdown | Temporizador com modo data-limite ou evergreen, labels e mensagem de expiração custom |
|
||||
| `price-table` | Price Table | Tabela de plano de preços com moeda, preço promocional, lista de features, ribbon, CTA |
|
||||
| `flip-box` | Flip Box | Cartão de dois lados que vira ao hover, cada lado com gráfico/título/descrição |
|
||||
| `animated-headline` | Animated Headline | Título com efeito de destaque ou texto rotativo |
|
||||
| `call-to-action` | Call to Action | Bloco CTA com título, descrição, botão e gráfico/ribbon opcional |
|
||||
| `slides` | Slides | Slider hero full-width com heading/descrição/botão/background por slide |
|
||||
| `testimonial-carousel` | Testimonial Carousel | Carrossel rotativo de testemunhos com skins, layouts e navegação |
|
||||
| `price-list` | Price List | Lista tipo menu com título, preço, descrição, imagem e separador |
|
||||
| `gallery` | Gallery | Galeria de imagens avançada com layouts grid/justified/masonry e filtros |
|
||||
| `share-buttons` | Share Buttons | Botões de partilha social para a página actual com skins e formas |
|
||||
| `table-of-contents` | Table of Contents | Índice auto-gerado a partir dos headings da página, com marcação de secção activa |
|
||||
| `blockquote` | Blockquote | Citação estilizada com texto, atribuição de autor, opção de tweet |
|
||||
| `lottie` | Lottie Animation | Embed de animação Lottie JSON com triggers, loop, velocidade, renderer |
|
||||
| `hotspot` | Hotspot | Imagem interactiva com pontos clicáveis/hover configuráveis |
|
||||
| `nav-menu` | Navigation Menu | Menu de navegação WordPress com layouts, ponteiros de hover, breakpoint de dropdown |
|
||||
| `loop-grid` | Loop Grid | Posts/pages/CPTs em grelha renderizada por um loop template |
|
||||
| `loop-carousel` | Loop Carousel | Posts em carrossel renderizado por um loop template, responsivo |
|
||||
| `media-carousel` | Media Carousel | Carrossel de imagens/vídeos com skins carousel/slideshow/coverflow |
|
||||
| `nested-tabs` | Nested Tabs | Tabs modernas onde cada conteúdo de tab é um container populável livremente |
|
||||
| `nested-accordion` | Nested Accordion | Acordeão moderno onde cada item é um container populável livremente |
|
||||
| `portfolio` | Portfolio | Grelha filtrável de posts/CPTs para portfólio/trabalho, com modal |
|
||||
| `author-box` | Author Box | Avatar, nome, bio do autor do post e link para os posts dele |
|
||||
| `login` | Login | Formulário de login frontend com labels, remember-me, link de password perdida |
|
||||
| `code-highlight` | Code Highlight | Bloco de código com syntax highlight, linguagem, tema, números de linha |
|
||||
| `reviews` | Reviews | Carrossel de reviews/testemunhos com slides por vista, autoplay, loop |
|
||||
| `off-canvas` | Off-Canvas | Painel off-canvas deslizante com posição, largura, animação de entrada |
|
||||
| `progress-tracker` | Progress Tracker | Indicador de progresso de scroll (horizontal ou circular) |
|
||||
| `search` | Search | Input de pesquisa do site com dropdown de resultados ao vivo opcional e tabs por post-type |
|
||||
|
||||
## Catálogo — widgets WooCommerce (5)
|
||||
|
||||
| `widget_type` | Título | Uso |
|
||||
|---|---|---|
|
||||
| `woocommerce-products` | WooCommerce Products | Grelha de produtos WooCommerce com colunas/linhas, ordenação |
|
||||
| `wc-add-to-cart` | WooCommerce Add to Cart | Botão de adicionar ao carrinho para um produto específico, com quantidade |
|
||||
| `woocommerce-cart` | WooCommerce Cart | Renderiza a página completa do carrinho WooCommerce |
|
||||
| `woocommerce-checkout-page` | WooCommerce Checkout | Renderiza a página completa de checkout WooCommerce |
|
||||
| `woocommerce-menu-cart` | WooCommerce Menu Cart | Ícone de mini-carrinho para o menu/header com indicador de itens |
|
||||
|
||||
## Notas
|
||||
|
||||
- Este catálogo é o que `list-widgets(tier:"pro")` devolveu ao vivo — pode variar ligeiramente por versão do Elementor Pro; correr sempre `list-widgets` primeiro no site alvo em vez de confiar cegamente nesta tabela para um `widget_type` exacto.
|
||||
- `add-pro-widget` está frequentemente no deny-list de sites de produção (ver skill `emcp-tools` para o mecanismo). Se estiver desligada, reportar ao utilizador em vez de tentar contornar via `add-free-widget` com um `widget_type` Pro — normalmente falha da mesma forma (widget não registado para essa chamada).
|
||||
|
||||
## Skills relacionadas
|
||||
- `emcp-page-building` — sequência de construção de página, coexistência atómico/legacy, `batch-update`.
|
||||
- `elementskit-widgets` / `powerpack-widgets` — catálogos de addons de terceiros (não aparecem em `list-widgets`, exigem `get-widget-schema(..., full:true)`).
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
name: elementskit-widgets
|
||||
description: Catálogo completo e verificado dos 42 widgets ElementsKit Lite (Wpmet) para Elementor, com o widgetType real de cada um extraído do código-fonte — não estão no catálogo curado do EMCP Tools (list-widgets), por isso precisam de get-widget-schema com full:true. Usar quando "elementskit", "elements kit", "widget ekit", "elementskit-button", "que widgets elementskit existem", "nav menu elementskit".
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# /elementskit-widgets — Catálogo de Widgets ElementsKit Lite
|
||||
|
||||
ElementsKit Lite (Wpmet, plugin `elementskit-lite`) regista os próprios widgets Elementor **fora** do catálogo curado do EMCP Tools — `list-widgets` não os lista. Este catálogo foi extraído directamente do código-fonte (`wp-content/plugins/elementskit-lite/widgets/*/`, ficheiros `*-handler.php`, método `get_name()`) num site em produção com ElementsKit Lite 4.0.1, não adivinhado por convenção de nomes.
|
||||
|
||||
## Como usar (workflow)
|
||||
|
||||
1. Confirmar que `elementskit-lite` está activo: `list-plugins` e procurar o slug — **atenção:** o site pode ter também `elementskit` (versão Pro) instalado mas **inactivo**; confirmar qual dos dois está `active:true` antes de assumir que widgets Pro do ElementsKit existem.
|
||||
2. `get-widget-schema({ widget_type: "elementskit-<slug>", full: true })` — estes widgets **não estão no catálogo curado**, por isso a chamada sem `full:true` devolve `{"error": "Not in the curated catalog. Retry with full:true..."}`. `full:true` devolve o schema de controlos bruto e funciona.
|
||||
3. Adicionar com `add-free-widget({ post_id, parent_id, widget_type, settings })` num container **legacy** (`add-container`) — confirmado ao vivo que widgets ElementsKit são legacy, não têm equivalente atómico. Ver skill `emcp-page-building` para a mecânica de coexistência atómico/legacy.
|
||||
4. **Nunca assumir o `widgetType` por convenção `elementskit-<pasta>`** — a tabela abaixo tem duas excepções confirmadas (`nav-menu` e `tab`); verificar sempre com `get-widget-schema(full:true)` antes de construir em produção.
|
||||
|
||||
## Catálogo (42 widgets, `widgetType` real verificado no código-fonte)
|
||||
|
||||
| `widgetType` | Título | Categoria/nota |
|
||||
|---|---|---|
|
||||
| `elementskit-accordion` | Accordion | geral |
|
||||
| `elementskit-back-to-top` | Back to Top | geral |
|
||||
| `elementskit-blog-posts` | Blog Posts | posts |
|
||||
| `elementskit-business-hours` | Business Hours | marketing |
|
||||
| `elementskit-button` | Button | geral — visto ao vivo em uso real |
|
||||
| `elementskit-category-list` | Category List | geral |
|
||||
| `elementskit-client-logo` | Client Logo | marketing |
|
||||
| `elementskit-contact-form7` | Contact Form 7 | integração — exige plugin CF7 activo |
|
||||
| `elementskit-countdown-timer` | Countdown Timer | marketing |
|
||||
| `elementskit-drop-caps` | Drop Caps | geral |
|
||||
| `elementskit-dual-button` | Dual Button | geral |
|
||||
| `elementskit-faq` | FAQ | geral |
|
||||
| `elementskit-fluent-forms` | Fluent Forms | integração — exige Fluent Forms activo |
|
||||
| `elementskit-funfact` | Funfact | criativo |
|
||||
| `elementskit-header-info` | Header Info | geral |
|
||||
| `elementskit-header-offcanvas` | Header Offcanvas | geral |
|
||||
| `elementskit-header-search` | Header Search | geral |
|
||||
| `elementskit-heading` | Heading | geral |
|
||||
| `elementskit-icon-box` | Icon Box | geral |
|
||||
| `elementskit-icon-hover` | Icon Hover | geral |
|
||||
| `elementskit-image-accordion` | Image Accordion | geral |
|
||||
| `elementskit-image-box` | Image Box | geral |
|
||||
| `elementskit-image-comparison` | Image Comparison | geral |
|
||||
| `elementskit-lottie` | Lottie | animação |
|
||||
| `elementskit-mail-chimp` | Mail Chimp | integração — exige Mailchimp configurado |
|
||||
| **`ekit-nav-menu`** | ElementsKit Nav Menu | geral — **excepção: prefixo `ekit-`, não `elementskit-`** |
|
||||
| `elementskit-ninja-forms` | Ninja Forms | integração — exige Ninja Forms activo |
|
||||
| `elementskit-page-list` | Page List | geral |
|
||||
| `elementskit-piechart` | Pie Chart | geral |
|
||||
| `elementskit-post-grid` | Post Grid | posts |
|
||||
| `elementskit-post-list` | Post List | posts |
|
||||
| `elementskit-post-tab` | Post Tab | posts |
|
||||
| `elementskit-pricing` | Pricing Table | marketing |
|
||||
| `elementskit-progressbar` | Progress Bar | geral |
|
||||
| `elementskit-social-media` | Social | geral — nota: pasta chama-se `social`, widgetType é `elementskit-social-media` |
|
||||
| `elementskit-social-share` | Social Share | geral |
|
||||
| **`elementskit-simple-tab`** | Tab | geral — **excepção: pasta chama-se `tab`, widgetType é `elementskit-simple-tab`** |
|
||||
| `elementskit-tablepress` | TablePress | integração — exige plugin TablePress activo |
|
||||
| `elementskit-team` | Team | geral |
|
||||
| `elementskit-testimonial` | Testimonial | geral — visto ao vivo em uso real |
|
||||
| `elementskit-video` | Video | geral |
|
||||
| `elementskit-we-forms` | WeForms | integração — exige weForms activo |
|
||||
| `elementskit-wp-forms` | WP Forms | integração — exige WPForms activo, visto ao vivo em uso real |
|
||||
|
||||
## Definições transversais injectadas pelo ElementsKit em QUALQUER widget
|
||||
|
||||
Confirmado ao vivo em `get-element-settings` de um widget `heading` legacy comum (não um widget ElementsKit): a presença do ElementsKit Lite injecta a definição `ekit_cursor_text_label` ("Elementskit Cursor") em widgets genéricos via uma extensão global de cursor. Não é exclusivo dos 42 widgets acima — pode aparecer em qualquer widget legacy no site.
|
||||
|
||||
## Skills relacionadas
|
||||
- `emcp-page-building` — mecânica de coexistência atómico/legacy, sequência de construção.
|
||||
- `elementor-pro-widgets` — catálogo nativo Elementor Pro (curado, no `list-widgets`).
|
||||
- `powerpack-widgets` — catálogo do addon concorrente PowerPack Elements (também fora do catálogo curado).
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: emcp-content-ops
|
||||
description: Gestão de conteúdo WordPress (posts/pages/CPTs, taxonomias, media, menus, redirects, blocos Gutenberg, pesquisa de conteúdo) via qualquer ligação MCP EMCP Tools — distinto de construção de páginas Elementor (ver emcp-page-building) ou auditoria de segurança/performance (ver emcp-site-audit). Usar quando "gerir conteúdo wordpress via mcp", "emcp posts", "upload media mcp", "menus wordpress mcp", "redirects mcp", "blocos gutenberg mcp".
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# /emcp-content-ops — Operações de Conteúdo WordPress via EMCP Tools
|
||||
|
||||
Aplica-se a qualquer ligação MCP EMCP Tools. Confirma sempre o site alvo com `core/get-site-info` — nunca assumir pelo nome da ligação.
|
||||
|
||||
## Posts / Pages / CPTs
|
||||
|
||||
- `list-post-types` primeiro num site desconhecido — os CPTs variam muito (visto ao vivo: `e-landing-page`, `podcast`, `elementor_library`, `elementskit_content`/`elementskit_template` além dos standard `post`/`page`).
|
||||
- `create-post({ post_type, title, content, status, slug, author, date, parent, terms, meta, featured_image })` escreve `post_content` (HTML clássico ou markup de blocos Gutenberg) — **não** dados Elementor. Para uma página construída em Elementor usar `create-page` (ver `emcp-page-building`); `create-post` explicitamente não toca em dados Elementor.
|
||||
- `get-post`/`list-posts`/`update-post`/`delete-post`/`set-post-terms`. `is_elementor` em `get-post`/`list-posts` diz qual editor é dono de determinada página — nunca editar o conteúdo de uma página Elementor via `update-post`.
|
||||
- `delete-post` vai para o Lixo por omissão (reversível); `force:true` para eliminação permanente. Devolve também um `redirect_suggestion` a lembrar de chamar `create-redirect` para o URL agora morto — agir sobre isso em conteúdo publicado, ignorar em rascunhos/conteúdo de teste.
|
||||
- `set-post-terms({ mode: replace|append|remove, create_missing })` — **`create_missing:true` deixa um termo de taxonomia permanente** se não houver tool de eliminação de termos montada na ligação (comummente o caso). Confirmar nomes de termos antes de usar em conteúdo descartável.
|
||||
|
||||
## Media
|
||||
|
||||
- `list-media`/`get-media` para a biblioteca existente (pesquisa por título/alt/legenda/descrição) antes de recorrer a fotos de stock — reutilizar o que já existe.
|
||||
- `upload-media({ filename, data: base64, alt, title, caption, description })` — bytes vindos do **cliente**, não de um URL. `sideload-image(url)` — o **servidor** vai buscar um URL que consegue alcançar. Casos de uso diferentes, não confundir.
|
||||
- `search-images`/`add-stock-image` (Unsplash/Pexels/Pixabay) exigem uma chave API do provedor configurada em EMCP Tools → Connection nesse site específico — **verificar que está configurada antes de planear um workflow em torno disso**; um site sem nenhuma configurada devolve um erro simples "sem chave API", não é uma falha da tool em si.
|
||||
- `delete-media` está comummente no deny-list (destrutivo, o WordPress ignora o Lixo para media por omissão). Se não estiver montada para esta ligação, qualquer upload é efectivamente permanente via MCP — obter confirmação explícita antes de fazer upload, e verificar primeiro se está montada.
|
||||
- `update-media` para correcções de alt text/título/legenda/descrição — seguro, não-destrutivo, boa opção por omissão para passagens de limpeza de acessibilidade/SEO.
|
||||
|
||||
## Menus
|
||||
|
||||
`menu-read`/`menu-write` são **tools despachadoras** — chamar sem argumento `operation` primeiro para obter a lista de operações de leitura/escrita disponíveis e as formas exactas de argumento para a versão do plugin nessa ligação, depois chamar de novo com `{ operation, arguments }`. Não adivinhar nomes de operação.
|
||||
|
||||
## Redirects
|
||||
|
||||
`list-redirects`/`find-broken-links` são só-leitura e comummente activas por omissão. `create-redirect`/`update-redirect`/`delete-redirect` estão comummente no deny-list em sites de produção (mutação de routing com impacto directo em SEO) — verificar se estão montadas antes de assumir que se pode agir sobre um achado de link partido; se não estiverem, reportar o achado e deixar o utilizador criar o redirect via wp-admin ou um canal WP-CLI.
|
||||
|
||||
`find-broken-links` é só-leitura e seguro de correr a qualquer momento — propõe correcções, não muda nada. Bom primeiro passo antes de qualquer trabalho de redirects.
|
||||
|
||||
## Blocos Gutenberg (independente do Elementor)
|
||||
|
||||
- `list-blocks`/`get-block-schema` (batch via `names[]`) → `add-block` (markup bruto, `position.mode: append|prepend|before|after|inside`) é o padrão descobrir → schema → aplicar.
|
||||
- `get-post-blocks` devolve um **PATH em índice por bloco** (ex. `[2,1]`) — chamar sempre isto imediatamente antes de `update-block`/`remove-block`/`move-block`/`duplicate-block` para obter os paths actuais; os paths mudam após cada edição, não fazer cache entre chamadas.
|
||||
- `list-patterns`/`insert-pattern` para composições de blocos pré-construídas.
|
||||
- Estas tools operam sobre `post_content`, por isso são a camada certa para posts/CPTs clássicos que não usam Elementor — não para páginas Elementor (`is_elementor: true`), que não têm árvore de blocos Gutenberg significativa.
|
||||
|
||||
## Pesquisa/reutilização de conteúdo
|
||||
|
||||
`search-content(query)` — pesquisa tipo linguagem natural sobre páginas/templates/widgets/estilos globais, ordenada por relevância. Faz correspondência a substrings/tokens literais no conteúdo indexado, não pesquisa semântica difusa — uma query com uma palavra ausente verbatim de qualquer título/conteúdo devolve zero resultados mesmo que o conceito esteja presente. Se os resultados parecerem desactualizados (edições recentes não reflectidas), chamar `reindex-search` primeiro — o índice também actualiza incrementalmente ao gravar, por isso um reindex completo só é preciso na primeira construção ou para forçar um refresh. Usar isto antes de construir conteúdo novo, para encontrar e reutilizar/clonar uma página/template/widget existente em vez de duplicar trabalho.
|
||||
|
||||
## Plugins / Temas / Utilizadores / Definições (nível só-leitura, quase universal)
|
||||
|
||||
- `list-plugins`/`search-plugins`, `list-themes`/`search-themes`, `list-users`/`get-user` — listagem e pesquisa comummente activas; instalar/activar/desactivar/actualizar/eliminar plugins ou temas, e criar/actualizar utilizadores, estão comummente no deny-list (categorias de maior risco depois de execução de código). Verificar o que está realmente montado antes de prometer que uma mutação é possível.
|
||||
- `get-settings`/`update-settings` — um subconjunto curado e allowlisted de definições WordPress (Geral/Leitura/Escrita/Discussão/Media/Permalinks), não `wp_options` bruto. `update-settings` reporta chaves ignoradas (`skipped`) com a razão (só-leitura, não allowlisted, valor inválido) em vez de falhar todo o lote — verificar o array `skipped`, não assumir que todas as chaves passadas foram aplicadas.
|
||||
- `theme-read`/`theme-write` e leitores específicos de framework (ex. `astra-read`, quando o Astra é o tema activo — só regista se esse tema estiver activo) são **tools despachadoras** também: chamar sem `operation` primeiro para descobrir o que está disponível no tema específico desse site.
|
||||
|
||||
## Referência cruzada
|
||||
- `emcp-page-building` — construção/edição específica de Elementor (atómico + legacy).
|
||||
- `emcp-site-audit` — scan de segurança, análise de performance, acesso só-leitura a BD/filesystem, ledger de mudanças + rollback.
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
name: emcp-page-building
|
||||
description: Construção e edição de páginas Elementor via qualquer ligação MCP EMCP Tools (emcp-descomplicar, emcp-emanuelalmeida, emcp-tools/starter, ou outra). Cobre elementos atómicos Elementor 4.0+, containers/widgets legacy, templates, operações em lote, e as armadilhas reais de parâmetros/comportamento encontradas por teste ao vivo. Usar quando "construir página elementor", "emcp page building", "widget atómico", "add-flexbox", "apply-template", "criar página com mcp".
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# /emcp-page-building — Construção de Páginas Elementor via EMCP Tools
|
||||
|
||||
Aplica-se a **qualquer** ligação MCP EMCP Tools, não a um site específico. Confirma sempre o site alvo com `core/get-site-info` antes de escrever — nunca assumas pelo nome da ligação.
|
||||
|
||||
Factos abaixo verificados ao vivo contra uma instalação EMCP Tools 3.12.1 em produção (Elementor 4.2.2 + Pro), revertidos depois via ledger. Descrevem o comportamento do **plugin**, por isso generalizam a qualquer site com a mesma versão — reverifica numa página de rascunho descartável se o site tiver uma versão materialmente diferente.
|
||||
|
||||
## Ordem de descoberta (antes de construir algo desconhecido)
|
||||
|
||||
1. `detect-elementor-version` — confirma suporte atómico + `recommended_mode` (`"atomic"` em sites 4.0+, usar tools atómicas por omissão).
|
||||
2. `list-widgets` (opcional `tier: free|pro|woo`, `category`, ou pesquisa livre) — catálogo curado nativo Elementor/Pro/Woo. **Não inclui widgets de terceiros** (ElementsKit, PowerPack) — ver skills `elementskit-widgets` e `powerpack-widgets`.
|
||||
3. `get-widget-schema({ widget_type })` — **o parâmetro é `widget_type`, não `type`.** Nome errado falha com um erro genérico de "propriedade obrigatória" que não diz qual campo.
|
||||
4. `get-container-schema` — schema completo de controlos de container (flex + grid).
|
||||
5. `get-page-structure({ post_id })` antes de tocar numa página existente — conhece sempre a árvore actual antes de mutar.
|
||||
|
||||
## Atómico (Elementor 4.0+) vs legacy — coexistem na mesma página
|
||||
|
||||
Confirmado ao vivo: uma página com um `e-flexbox` atómico (com widgets `e-heading`/`e-paragraph` filhos) ao lado de um `container` legacy (com um widget `heading` legacy) gravou e renderizou a estrutura correctamente. Não é preciso escolher um modo por página.
|
||||
|
||||
- Containers atómicos: `add-flexbox`, `add-div-block`. Widgets atómicos só ligam a estes (ou a outro container atómico) como `parent_id` — `add-atomic-heading` etc. rejeitam um `container` legacy como pai.
|
||||
- Containers legacy: `add-container`. Widgets legacy (`add-free-widget`, ex. `widget_type: "heading"`) só ligam a containers legacy.
|
||||
- Usa legacy para qualquer widget sem equivalente atómico ainda — confirmado ao vivo: widgets de terceiros como `elementskit-*`/`elementskit-wp-forms` só existem como widgets legacy.
|
||||
- `update-element` funciona em elementos atómicos e legacy genericamente. `update-atomic-widget` é a variante de merge parcial específica para atómicos — preferir para atómicos, mas `update-element` é o fallback universal seguro.
|
||||
- `batch-update({ post_id, operations: [{element_id, settings}, ...] })` actualiza vários elementos (atómicos ou legacy, misturados) numa só gravação — preferir sempre isto a N chamadas sequenciais de `update-element`.
|
||||
|
||||
## 🔴 Armadilhas confirmadas ao vivo — não confiar só na descrição da tool
|
||||
|
||||
1. **`set-element-label`**: o campo real obrigatório é `title`, não `label`, apesar da descrição "Sets an element's Navigator label" sugerir `label`. Ler o schema (`read xd://mcp__<ligação>_emcp_tools_set_element_label`) antes da primeira utilização numa ligação nova.
|
||||
2. **`add-custom-js`**: exige `parent_id` (tem de ser um container **legacy** — insere um widget HTML) e o campo de código é `js`, não `code`. Não liga a um `e-flexbox`/`e-div-block` atómico.
|
||||
3. **`apply-template` pode substituir TODO o conteúdo existente da página em vez de inserir.** Testado: chamar `apply-template(post_id, template_id)` sem `position` explícito numa página com 7 elementos existentes resultou em substituição total — só ficaram os elementos do template (`elements_added` igual à contagem própria do template). A descrição sugere inserção ("at a given position, inserting its elements"); o comportamento observado foi sobrescrita. **Sequência obrigatória:** `get-page-structure` antes → `apply-template(..., position: -1)` explícito → `get-page-structure` depois, comparar. Se o conteúdo foi apagado, recuperar via `rollback-change` na entrada mais recente de `list-changes` para esse `post_id` (ver skill `emcp-site-audit`) — confirmado a funcionar.
|
||||
4. **`create-theme-template` fica publicado de imediato**, não como rascunho. Testado: `create-theme-template(type:"single", title:"...")` devolveu `status: "publish"` com `conditions.include: [{"object":"all-singular"}]` por omissão — com conteúdo vazio, aplicar-se-ia de imediato a todo o singular do site. Chamar logo `set-template-conditions` para restringir o alcance antes de construir conteúdo, ou `delete-theme-template` de imediato se criado por engano (confirmado limpo/reversível).
|
||||
5. **`get-element-settings` normaliza os wrappers `$$type` atómicos; `get-page-structure` e `export-page` não.** Para o mesmo heading atómico, `get-element-settings` devolve `{"title": "string simples"}` enquanto os outros dois mostram a estrutura crua `{"$$type":"html-v3","value":{"content":{"$$type":"string","value":"..."}}}`. Usar `get-element-settings` para "qual é o valor agora"; usar `get-page-structure`/`export-page` para entender ou reproduzir a estrutura crua de prop-types atómicos.
|
||||
6. **`set-post-terms` com `create_missing:true` deixa termos de taxonomia permanentes** — sem tool de eliminação de termos no conjunto activo em nenhum site testado até agora. Confirmar o nome do termo antes de usar em conteúdo descartável/teste.
|
||||
|
||||
## Construir uma página de raiz — sequência recomendada
|
||||
|
||||
1. `create-page({ title, status: "draft" })` — nunca construir directamente numa página publicada.
|
||||
2. `add-flexbox({ post_id, settings: { flex_direction, gap } })` (ou `add-div-block`) para o primeiro container estrutural. `add-container` só se precisares especificamente de comportamento legacy ou nesting sob uma árvore legacy existente.
|
||||
3. Aninhar widgets atómicos: `add-atomic-heading`/`add-atomic-paragraph`/`add-atomic-button`/`add-atomic-image`/`add-atomic-svg`/`add-atomic-video`/`add-atomic-youtube`/`add-atomic-divider`, ou o genérico `add-atomic-widget` para o que não tenha tool de conveniência.
|
||||
4. Para qualquer widget legacy necessário (Pro/terceiros ainda sem versão atómica, `add-pro-widget` se o deny-list do site permitir): `add-container` depois `add-free-widget`.
|
||||
5. Verificar com `get-page-structure` após cada passo relevante, não só no fim.
|
||||
6. `reorder-elements`, `move-element`, `duplicate-element`, `remove-element` operam por ID de elemento das chamadas de structure/find-element — nunca adivinhar IDs.
|
||||
7. `set-element-label({ post_id, element_id, title })` para manter o Navigator legível em páginas complexas (campo `title`, ver armadilha #1).
|
||||
8. `update-page-settings` para definições de página ao nível Elementor (background, padding, CSS custom — funcionalidades Pro degradam de forma graciosa se indisponíveis).
|
||||
9. Antes de publicar: `get-page-snapshot` para um único digest normalizado (estrutura + contagens + cores/tipografia globais em uso + resumo SEO-lite) em vez de encadear chamadas separadas de structure/global-settings/classes.
|
||||
|
||||
## Tokens de design globais
|
||||
|
||||
- `get-global-settings` — kit de todo o site (cores, tipografia, espaçamento, breakpoints).
|
||||
- `update-global-colors`/`update-global-typography` — muta o kit directamente; afecta todas as páginas que usam esses tokens, confirmar com o utilizador primeiro.
|
||||
- `list-global-classes` — resolve IDs `g-` do Class Manager do Elementor 4.0 para nomes/CSS legíveis. Normalmente só-leitura; `create-global-class`/`update-global-class`/`delete-global-class`/`reorder-global-classes` estão comummente no deny-list (mutação de CSS partilhado) — verificar se estão montadas antes de assumir que funcionam.
|
||||
|
||||
## Templates
|
||||
|
||||
- `list-templates` (templates guardados na biblioteca Elementor, qualquer tipo: page/section/container) e `save-as-template` para criar novos. **Não há tool de eliminação de template no conjunto comummente activo em nenhum site testado** — guardar um template é efectivamente permanente via MCP. Obter confirmação explícita antes de `save-as-template`.
|
||||
- `import-template`/`export-page` para estruturas JSON portáveis.
|
||||
- Theme Builder (`create-theme-template`/`list-theme-templates`/`get-theme-template`/`update-theme-template`/`set-template-conditions`/`resolve-template`/`delete-theme-template`) — ver armadilha #4 acima. `list-condition-targets` antes de `set-template-conditions` para ver selectores/post-types/taxonomias válidos naquele site.
|
||||
|
||||
## Padrão de teste seguro
|
||||
|
||||
Nunca experimentar numa página publicada real. `create-page(status:"draft")`, construir/mutar livremente, confirmar via `get-page-structure`, depois `delete-post(post_id)` (vai para o Lixo — reversível; só `force:true` se o utilizador pedir explicitamente remoção permanente). Verificar `list-changes` depois — toda a escrita aqui fica registada no ledger, por isso um teste falhado é sempre recuperável com `rollback-change` mesmo antes de chegares a apagar o rascunho.
|
||||
|
||||
## Skills relacionadas
|
||||
- `emcp-content-ops` — operações de conteúdo WordPress (posts/pages/media/menus/redirects/blocos).
|
||||
- `emcp-site-audit` — scan de segurança, análise de performance, acesso só-leitura a BD/filesystem, ledger de mudanças.
|
||||
- `elementor-pro-widgets` — catálogo completo de widgets nativos Elementor Pro.
|
||||
- `elementskit-widgets` / `powerpack-widgets` — catálogos de widgets de terceiros (não estão no catálogo curado do EMCP).
|
||||
- `emcp-tools` — arquitectura do plugin, inventário completo de ~162 abilities, mecanismo de deny-list.
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
name: emcp-site-audit
|
||||
description: Auditoria de segurança, performance, base de dados e filesystem de um site WordPress via qualquer ligação MCP EMCP Tools, e recuperação de uma edição de IA falhada via o ledger de mudanças/rollback. Usar quando "scan-security mcp", "analyze-performance mcp", "rollback-change", "ledger de mudanças elementor", "falso positivo malware uploads", "query base de dados via mcp".
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# /emcp-site-audit — Auditoria e Rede de Segurança via EMCP Tools
|
||||
|
||||
Aplica-se a qualquer ligação MCP EMCP Tools. Confirma o site alvo com `core/get-site-info`.
|
||||
|
||||
## Scan de segurança
|
||||
|
||||
`scan-security` — só-leitura, autocontido, audita apenas o site ligado. Quatro áreas: heurísticas de malware PHP (uploads + plugins/temas activos; `deep:true` para a árvore completa), integridade de ficheiros do core WordPress (vs checksums oficiais), hardening de configuração (editor de ficheiros activo, output de debug, username admin, XML-RPC, divulgação de versão, HTTPS, security headers), e software desactualizado/abandonado. Devolve `{summary: {score, grade, counts: {critical, warning, pass, info}}, sections: {...}}`.
|
||||
|
||||
**Tratar um achado `critical` como um reporte imediato e separado ao utilizador — nunca enterrado dentro de uma tarefa não relacionada.** Mas **`malware_uploads_php` (qualquer `.php` sob `wp-content/uploads/`, categoria `critical`) é uma heurística grosseira que assinala só a localização, não o conteúdo — tem um padrão confirmado e comum de falso positivo. Ler sempre o ficheiro assinalado com `read-file` e inspeccionar o conteúdo real antes de reportar como ameaça real.**
|
||||
|
||||
Confirmado benigno num scan ao vivo (dois hits `critical`, mesmo id de achado, ambos falsos positivos):
|
||||
- `wp-content/uploads/index.php` — stub próprio do **core WordPress**, incluído por omissão em toda a instalação: `header($_SERVER['SERVER_PROTOCOL'].' 403 Forbidden'); die('403 Forbidden');`. Existe só para bloquear listagem de directório. **Nunca apagar este** — removê-lo *reduz* a segurança ao remover exactamente a protecção que fornece.
|
||||
- `wp-content/uploads/<plugin>/cache/index.php` (visto: WPForms) — mesmo padrão, incluído pelo plugin, ex. `header(...' 404 Not Found');`. Qualquer plugin que faça cache em `uploads/` tipicamente inclui um destes por directoria de cache.
|
||||
|
||||
Regra de diagnóstico: um ficheiro `uploads/*.php` genuinamente malicioso contém lógica executável real (`eval`, `base64_decode`, `system`/`exec`/`shell_exec`, payloads ofuscados, marcadores de webshell) — um stub benigno tem 2-4 linhas, só `header()` + `die()`/`exit` opcional, nada mais. Se `read-file` mostrar só um stub de header/die, despromover o achado para informativo no reporte e **não** apagar o ficheiro. Se mostrar outra coisa — ameaça real, reportar de imediato e confirmar com o utilizador antes de apagar (o caminho de remoção confirmado seguro é `delete-file` se montada para a ligação, ou `wp eval`/`rm` via SSH quando não estiver — ver secção Filesystem abaixo).
|
||||
|
||||
Achados `integrity_modified` (ficheiro do core difere dos checksums oficiais) também podem ser rotina — ex. `wp-includes/version.php` difere por desenho (é o próprio ficheiro de versão instalada do WordPress, espera-se que difira de uma baseline de checksum genérica). Cruzar o que mudou (`read-file` no ficheiro assinalado) antes de tratar um achado de integridade como indicador de comprometimento.
|
||||
|
||||
## Análise de performance
|
||||
|
||||
`analyze-performance` — só-leitura. Analisa configuração do servidor, internals WordPress (tamanho da BD, opções autoloaded, backlog de cron, object cache, OPcache, contagem de plugins), e uma página alvo (por omissão a página inicial; passar `url` ou `post_id` para uma página específica). Devolve a mesma forma `{summary: {score, grade, counts}, sections}` que `scan-security`, com `status` por achado (`pass`/`warning`/`critical`), `message`, e `recommendation` — uma lista de acções priorizada já pronta, não reportar só o score.
|
||||
|
||||
## Base de dados (nível só-leitura)
|
||||
|
||||
`list-tables` (contagens de linhas + tamanhos), `describe-table({ table })` (colunas/tipos/keys), `query({ sql })` — **só SELECT/SHOW/DESCRIBE/EXPLAIN, escritas e DDL são rejeitadas no servidor.** Resultados têm limite — para conjuntos grandes, restringir a query em vez de esperar paginação. O prefixo das tabelas varia por instalação (visto ao vivo: `wpne_` num site) — sempre `list-tables` primeiro em vez de assumir `wp_`.
|
||||
|
||||
`insert-row`/`update-rows`/`delete-rows` existem no plugin mas estão comummente no deny-list em todos os sites de produção testados até agora — escritas SQL directas contornam a camada de validação do próprio WordPress. Não tentar sem confirmar primeiro que estão realmente montadas para essa ligação.
|
||||
|
||||
## Filesystem (nível só-leitura)
|
||||
|
||||
`list-directory`/`read-file`/`search-files`, confinados à raiz da instalação WordPress. `read-file` recusa ficheiros de segredos no servidor — confirmado ao vivo: pedir `wp-config.php` devolve *"This file holds site secrets ... and cannot be read"* em vez de um erro ou do conteúdo, independentemente da variante de caminho tentada. `search-files({ query, extensions, path })` faz grep file:line numa árvore de directórios, com limite — bom para confirmar versão de plugin/tema ou um padrão de código específico sem SSH.
|
||||
|
||||
`write-file`/`edit-file`/`delete-file` existem no plugin mas estão quase universalmente no deny-list (escritas directas no filesystem contornam toda a auditoria de shell/SSH) — tratar como indisponível salvo confirmação explícita de que está montada. Quando um ficheiro confirmadamente malicioso precisa de ser removido e `delete-file` não está montada, usar o canal SSH/wp-cli próprio do site em vez de forçar via MCP.
|
||||
|
||||
## Ledger de mudanças + rollback — a rede de segurança para toda escrita Elementor/conteúdo
|
||||
|
||||
Toda a chamada mutante que este plugin expõe (edições Elementor, e nalguns sites também escritas de filesystem/BD) fica registada. Testado ao vivo, ponta-a-ponta, e funciona:
|
||||
|
||||
1. `list-changes` (opcional filtrar por `domain`: elementor/filesystem/database, `rolled_back`, `reversible`) — mais recente primeiro, cada entrada tem `id`, `summary`, `reversible`, `rolled_back`.
|
||||
2. `get-change({ id })` para detalhe completo incluindo a referência de rollback (before-image / ponteiro de backup / `after_hash`).
|
||||
3. `rollback-change({ id })` — reverte essa mudança. Confirmado ao vivo: reverteu uma página exactamente para a árvore de elementos anterior, removendo precisamente o que aquela mudança tinha adicionado e nada das mudanças à volta. Recusa com erro de conflito se o alvo mudou de novo desde a mudança registada (passar `force:true` para sobrepor e aceitar perda de dados no estado mais recente). Nunca faz double-rollback da mesma entrada; regista uma entrada compensatória no ledger quando corre.
|
||||
|
||||
**Quando qualquer escrita nesta sessão correr mal ou produzir um resultado inesperado (ver a armadilha de sobrescrita do `apply-template` em `emcp-page-building`), recorrer a `list-changes` → `rollback-change` antes de tentar reconstruir manualmente o estado anterior.** É mais rápido e fiável do que reconstruir a partir do output de `get-page-structure`.
|
||||
|
||||
## Espelho de conteúdo (export/restore git-friendly — separado do ledger de mudanças)
|
||||
|
||||
`export-content`/`list-content-exports`/`restore-content` — exporta conteúdo de página/template Elementor para ficheiros JSON sob `uploads/emcp-content-mirror/` para um VCS externo poder fazer diff/versionar designs, e restaura a partir de um ficheiro de espelho (um undo baseado em ficheiro, distinto do ledger acima). `list-content-exports` mostra o que está actualmente espelhado em disco. Útil antes de um lote grande de trabalho de construção de páginas como checkpoint extra além do ledger automático.
|
||||
|
||||
## Referência cruzada
|
||||
- `emcp-page-building` — construção de páginas Elementor, incluindo as tools com maior probabilidade de precisar de rollback (`apply-template`, `create-theme-template`).
|
||||
- `emcp-content-ops` — operações de conteúdo/media/menus/redirects WordPress.
|
||||
- `emcp-tools` (skill genérica) — inventário completo de ~162 abilities e o mecanismo de deny-list que decide quais das tools referidas acima estão realmente montadas numa dada ligação.
|
||||
@@ -0,0 +1,561 @@
|
||||
---
|
||||
name: emcp-tools
|
||||
description: Auditoria e gestão de postura de segurança do EMCP Tools (extensão do WP MCP Adapter da Elementskit — expõe dados Elementor, widgets e ferramentas de operação como MCP tools para agentes de IA). Cobre inventário completo das ~162 abilities registadas por categoria (activas vs desligadas, verificado via wp_get_abilities()), os 9 módulos do plugin (prompts, brand-kits, templates, themer, redirects, agent-skills, cloud, image-optimization, svg-support) e o que cada um expõe, o mecanismo de deny-list incremental versionado (34 migrações), activação granular e segura de uma ferramenta individual (ex: só leitura Rank Math), avaliação de risco por categoria, e arquitectura de registo MCP multi-site. Usar quando "emcp tools", "emcp-tools", "mcp adapter wordpress", "ferramentas mcp elementor", "que tools o agente pode chamar", "activar tool emcp", "desligar tool mcp", "postura default-deny mcp", "agentes de ia no wordpress", "módulos emcp tools", "inventário completo mcp tools", "quantas tools estão activas".
|
||||
---
|
||||
|
||||
# /emcp-tools — Auditoria e Postura de Segurança do EMCP Tools (MCP para Elementor/WP)
|
||||
|
||||
Plugin `emcp-tools` (Mian Shahzad Raza) — extensão do WP MCP Adapter que expõe
|
||||
dados Elementor, widgets, page design tools e um conjunto amplo de
|
||||
operações WordPress como **ferramentas MCP** chamáveis por agentes de IA.
|
||||
Versão verificada `3.12.1`, instalado e activo em `emanuelalmeida.pt`,
|
||||
`descomplicar.pt` (`public_html`) e `starter.descomplicar.pt`.
|
||||
|
||||
**Fonte:** `Hub/04-Stack/02.04-Sistemas/71.Seguranca/CONFIG-Plugins-Referencia.md`
|
||||
§10 (EMCP Tools) + `BUNDLE-Excelencia-WP.md` + verificação SSH ao vivo nesta
|
||||
sessão (16-08-2026) nos três sites do ecossistema.
|
||||
|
||||
---
|
||||
|
||||
## Arquitectura — como o agente chega às tools deste plugin
|
||||
|
||||
O plugin regista um servidor MCP próprio, `emcp-tools-server` (nome visível
|
||||
"MCP Tools for Elementor Server"), lado a lado com outros servidores do
|
||||
mesmo WP MCP Adapter (`elementskit-mcp-server`, `mcp-adapter-default-server`,
|
||||
e nalguns sites `fluent-crm`). A ligação do agente ao site faz-se por SSH +
|
||||
STDIO, uma entrada por site em `~/.omp/agent/mcp.json`:
|
||||
|
||||
```json
|
||||
"emcp-emanuelalmeida": {
|
||||
"type": "stdio",
|
||||
"command": "ssh",
|
||||
"args": ["-T", "-o", "BatchMode=yes", "server",
|
||||
"sudo -u ealmeida /usr/local/bin/wp mcp-adapter serve --server=emcp-tools-server --user=ealmeida --path=/home/ealmeida/emanuelalmeida.pt"],
|
||||
"timeout": 60000,
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
**Três instâncias activas no ecossistema**, uma ligação MCP por site (cada
|
||||
uma com o seu próprio `--path` e, portanto, a sua própria config
|
||||
`emcp_tools_*` independente — **não presumir que a postura de um site se
|
||||
aplica a outro**, ver §3):
|
||||
|
||||
| Ligação em `mcp.json` | Site | `--path` |
|
||||
|---|---|---|
|
||||
| `emcp-descomplicar` | descomplicar.pt | `/home/ealmeida/public_html` |
|
||||
| `emcp-tools` | starter.descomplicar.pt | `/home/ealmeida/starter.descomplicar.pt` |
|
||||
| `emcp-emanuelalmeida` | emanuelalmeida.pt | `/home/ealmeida/emanuelalmeida.pt` |
|
||||
|
||||
Comando nativo WP-CLI para inspecção do lado do servidor (sem passar pelo
|
||||
protocolo MCP):
|
||||
|
||||
```bash
|
||||
wp mcp-adapter list --path=$PATH --allow-root
|
||||
wp mcp-adapter list --format=json --path=$PATH --allow-root
|
||||
```
|
||||
|
||||
⚠️ **Achado desta sessão — a coluna `Tools` de `wp mcp-adapter list` NÃO é
|
||||
um proxy fiável do nº de ferramentas realmente activas.** Verificado ao
|
||||
vivo nos 3 sites (16-08-2026):
|
||||
|
||||
| Site | `emcp_tools_disabled_tools` (desligadas) | `wp mcp-adapter list` → coluna `Tools` do `emcp-tools-server` | Activas REAIS (`wp_get_abilities()`, §7) |
|
||||
|---|---|---|---|
|
||||
| descomplicar.pt | 78 | `3` | **165** (achado crítico — §8.2) |
|
||||
| starter.descomplicar.pt | 131 | `3` | 114 |
|
||||
| emanuelalmeida.pt | 131 | `115` | 115 |
|
||||
|
||||
Não há correlação directa (menos desligadas em `descomplicar.pt` devia
|
||||
implicar mais activas, mas mostra o valor mais baixo). A contagem desta
|
||||
coluna parece depender de estado de registo/cache do lado do WP-CLI, não do
|
||||
filtro `emcp_tools_disabled_tools` aplicado em tempo de pedido MCP. **Não
|
||||
usar esta coluna para avaliar postura de segurança** — usar sempre o
|
||||
conteúdo real de `emcp_tools_disabled_tools` (§2) para saber o que está
|
||||
fechado, e o protocolo MCP (`tools/list` via um cliente MCP ligado, ex. a
|
||||
própria sessão do agente) para saber com exactidão o que está disponível
|
||||
para chamada num momento dado. A 4ª coluna acima é a contagem definitiva,
|
||||
obtida com o método de §7 (`wp eval` + `wp_get_abilities()` filtrado, cruzado
|
||||
slug-a-slug contra `emcp_tools_disabled_tools`) — coincide exactamente com a
|
||||
coluna `Tools` só em `emanuelalmeida.pt`; nos outros dois sites a coluna do
|
||||
WP-CLI é enganadora nos dois sentidos (mostra `3` quando o real é 114 **e**
|
||||
165).
|
||||
|
||||
---
|
||||
|
||||
## 1. Config verificada (`emanuelalmeida.pt`, `wp_options`)
|
||||
|
||||
```bash
|
||||
wp option list --search='emcp_tools*' --path=$PATH --allow-root
|
||||
```
|
||||
|
||||
| Opção | Valor real | Nota |
|
||||
|---|---|---|
|
||||
| `emcp_tools_sandbox_location` | `emcp-sandbox` | Directório isolado para operações de sandbox |
|
||||
| `emcp_tools_active_modules` | `["prompts","brand-kits","templates","themer","redirects","agent-skills","cloud"]` (7 de 9 semeados) | `image-optimization` e `svg-support` estão **semeados mas não activos** — idêntico nos 3 sites verificados |
|
||||
| `emcp_tools_disabled_tools` | array indexado com **131** ferramentas desligadas (formato `emcp-tools/<nome-tool>`) | Ver lista completa §2 |
|
||||
| `emcp_tools_defaults_applied` | `34` | Contador interno de defaults aplicados na instalação |
|
||||
| `emcp_tools_modules_seeded` / `emcp_tools_legacy_meta_migrated` / `emcp_tools_slug_namespace_migrated` | flags internas de migração | Sem acção |
|
||||
| `emcp_tools_changelog_db_version` / `emcp_tools_oauth_db_version` / `emcp_tools_redirects_db_version` / `emcp_tools_search_index_db_version` | versões de schema interno | Sem acção |
|
||||
| `emcp_tools_themer_index` / `emcp_tools_themer_index_healed` | índice interno do módulo Themer | Sem acção |
|
||||
|
||||
Outros dois sites (`descomplicar.pt`, `starter.descomplicar.pt`) partilham
|
||||
o mesmo `emcp_tools_active_modules`; `starter.descomplicar.pt` partilha
|
||||
exactamente os mesmos 131 nomes desligados que `emanuelalmeida.pt`;
|
||||
`descomplicar.pt` tem apenas 78 desligados (config mais permissiva —
|
||||
**verificar antes de assumir postura igual entre sites**). Note-se também
|
||||
que `templates` e `agent-skills` são módulos **Pro** (`tier() === 'pro'`)
|
||||
semeados como "activos" em todos os 3 sites por omissão do próprio plugin,
|
||||
mas nenhum destes sites tem licença Pro (`emcp_tools_fs()->can_use_premium_code()
|
||||
=== false`), logo `is_available()` devolve `false` e **nenhum dos dois
|
||||
módulos corre de facto** — ver tabela completa dos 9 módulos em §6, e o
|
||||
achado crítico específico de `descomplicar.pt` em §8.2 (78 desligados não
|
||||
significa "mais permissivo apenas um pouco" — significa **zero** tools
|
||||
nativas fechadas).
|
||||
|
||||
---
|
||||
|
||||
## 2. Lista completa das 131 ferramentas desligadas por omissão
|
||||
|
||||
Confirmada ao vivo (`emanuelalmeida.pt` e `starter.descomplicar.pt`,
|
||||
formato idêntico): array indexado (não associativo) em
|
||||
`emcp_tools_disabled_tools`, cada entrada `emcp-tools/<slug-da-tool>`.
|
||||
|
||||
```bash
|
||||
wp option get emcp_tools_disabled_tools --format=json --path=$PATH --allow-root
|
||||
```
|
||||
|
||||
### 2.1 Ficheiros, sistema e execução remota — risco máximo, nunca activar sem supervisão directa
|
||||
```
|
||||
write-file, edit-file, delete-file, run-wp-cli, dispatch-wp-cli,
|
||||
get-wp-cli-job, list-wp-cli-jobs
|
||||
```
|
||||
|
||||
### 2.2 Base de dados directa
|
||||
```
|
||||
insert-row, update-rows, delete-rows
|
||||
```
|
||||
|
||||
### 2.3 Gestão de plugins e temas
|
||||
```
|
||||
install-plugin, activate-plugin, deactivate-plugin, update-plugin, delete-plugin,
|
||||
install-theme, switch-theme, update-theme, delete-theme
|
||||
```
|
||||
|
||||
### 2.4 Utilizadores
|
||||
```
|
||||
create-user, update-user
|
||||
```
|
||||
|
||||
### 2.5 Redirecções e migração de site
|
||||
```
|
||||
create-redirect, update-redirect, delete-redirect,
|
||||
migrate-site, sync-to-live, sync-content-item
|
||||
```
|
||||
|
||||
### 2.6 Integrações de terceiros — leitura e escrita (granularidade por par read/write)
|
||||
```
|
||||
acf-write
|
||||
woo-read, woo-write
|
||||
metabox-write
|
||||
essential-addons-read, premium-addons-read, uae-read, uae-write
|
||||
cf7-write
|
||||
wpforms-read, wpforms-write
|
||||
gravityforms-read, gravityforms-write
|
||||
fluentforms-read, fluentforms-write
|
||||
ninjaforms-read, ninjaforms-write
|
||||
formidable-read, formidable-write
|
||||
metform-read, metform-write
|
||||
sureforms-read, sureforms-write
|
||||
forminator-read, forminator-write
|
||||
```
|
||||
|
||||
### 2.7 SEO — TODOS os plugins, leitura E escrita fechadas (Rank Math dono único da superfície SEO neste bundle)
|
||||
```
|
||||
slimseo-write
|
||||
yoast-read, yoast-write
|
||||
rankmath-read, rankmath-write
|
||||
aioseo-read, aioseo-write
|
||||
seopress-read, seopress-write
|
||||
seoframework-read, seoframework-write
|
||||
surerank-read, surerank-write
|
||||
```
|
||||
|
||||
### 2.8 Temas/frameworks de blocos
|
||||
```
|
||||
theme-write
|
||||
astra-write
|
||||
spectra-write
|
||||
kadence-write, kadence-blocks-write
|
||||
generatepress-read, generatepress-write
|
||||
generateblocks-read, generateblocks-write
|
||||
blocksy-blocks-read, blocksy-blocks-write, blocksy-extensions-read, blocksy-extensions-write
|
||||
```
|
||||
|
||||
### 2.9 Elementor avançado (widgets Pro, templates de tema, popups, dynamic tags, CSS/classes globais)
|
||||
```
|
||||
add-pro-widget, create-elementor-theme-template, set-elementor-template-conditions,
|
||||
list-dynamic-tags, set-dynamic-tag, create-popup, set-popup-settings,
|
||||
delete-media, add-custom-css,
|
||||
create-global-class, update-global-class, delete-global-class, reorder-global-classes
|
||||
```
|
||||
|
||||
### 2.10 Snippets PHP — execução de código arbitrário, risco máximo absoluto
|
||||
```
|
||||
add-code-snippet, list-code-snippets,
|
||||
validate-php-snippet, create-php-snippet, update-php-snippet, get-php-snippet,
|
||||
list-php-snippets, delete-php-snippet
|
||||
```
|
||||
|
||||
### 2.11 Memória do agente
|
||||
```
|
||||
recall, remember, save-session-summary
|
||||
```
|
||||
|
||||
### 2.12 Templates PHP de tema
|
||||
```
|
||||
create-theme-php-template, list-theme-php-templates, get-theme-php-template,
|
||||
update-theme-php-template, delete-theme-php-template
|
||||
```
|
||||
|
||||
### 2.13 SEO/A11y automatizados (geração de conteúdo/schema/contraste)
|
||||
```
|
||||
audit-page-seo, extract-keywords-from-content, generate-meta-tags,
|
||||
generate-schema-markup, set-social-image,
|
||||
audit-page-a11y, fix-color-contrast, add-alt-text-from-context
|
||||
```
|
||||
|
||||
### 2.14 Widgets e blocos custom (criação/edição/eliminação)
|
||||
```
|
||||
list-control-types, validate-widget-spec,
|
||||
create-custom-widget, update-custom-widget, get-custom-widget, list-custom-widgets,
|
||||
set-widget-status, delete-custom-widget,
|
||||
list-block-control-types, validate-block-spec,
|
||||
create-custom-block, update-custom-block, get-custom-block, list-custom-blocks,
|
||||
set-block-status, delete-custom-block
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Como listar ferramentas activas vs desligadas num site
|
||||
|
||||
```bash
|
||||
PATH=/home/USER/SITE
|
||||
|
||||
# Quantas e quais estão desligadas
|
||||
wp option get emcp_tools_disabled_tools --format=json --path=$PATH --allow-root
|
||||
|
||||
# Módulos activos (nível mais alto — prompts/brand-kits/templates/themer/redirects/agent-skills/cloud/image-optimization/svg-support)
|
||||
wp option get emcp_tools_active_modules --format=json --path=$PATH --allow-root
|
||||
|
||||
# Servidores MCP registados neste site (não usar a coluna Tools como medida de activo — ver aviso acima)
|
||||
wp mcp-adapter list --path=$PATH --allow-root
|
||||
```
|
||||
|
||||
**Para saber com exactidão quais tools estão disponíveis para chamada num
|
||||
dado momento** (a lista real, não a config): ligar via o protocolo MCP
|
||||
(a própria ligação `emcp-*` em `mcp.json`) e pedir `tools/list` — a config
|
||||
`emcp_tools_disabled_tools` é aplicada como filtro em tempo de pedido pelo
|
||||
plugin, não é reflectida de forma fiável pelo WP-CLI.
|
||||
|
||||
---
|
||||
|
||||
## 4. Activar uma ferramenta específica com segurança (granularidade individual)
|
||||
|
||||
O array é **indexado** (não associativo), por isso `wp option patch` não
|
||||
serve para remover/adicionar uma entrada isolada — usar `wp eval` com
|
||||
`array_diff`/`array_values` para manter o array limpo e sem duplicados.
|
||||
|
||||
### Activar (remover do deny-list)
|
||||
|
||||
|
||||
```bash
|
||||
wp eval '
|
||||
$tool = "emcp-tools/rankmath-read";
|
||||
$disabled = get_option("emcp_tools_disabled_tools", []);
|
||||
$before = count($disabled);
|
||||
$disabled = array_values(array_diff($disabled, [$tool]));
|
||||
update_option("emcp_tools_disabled_tools", $disabled);
|
||||
printf("antes=%d depois=%d removida=%s\n", $before, count($disabled), $before !== count($disabled) ? "sim" : "nao (ja estava activa ou nome errado)");
|
||||
' --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
**Exemplo do pedido típico — activar só leitura Rank Math sem abrir
|
||||
escrita:** activar `emcp-tools/rankmath-read` e deixar
|
||||
`emcp-tools/rankmath-write` no array (continua desligada). A granularidade
|
||||
é sempre ao nível do slug individual — nunca existe um toggle "Rank Math
|
||||
on/off" only por read/write, exactamente como aparece na lista §2.7.
|
||||
|
||||
### Reverter (voltar a fechar)
|
||||
|
||||
```bash
|
||||
wp eval '
|
||||
$tool = "emcp-tools/rankmath-read";
|
||||
$disabled = get_option("emcp_tools_disabled_tools", []);
|
||||
if (!in_array($tool, $disabled, true)) { $disabled[] = $tool; }
|
||||
update_option("emcp_tools_disabled_tools", $disabled);
|
||||
echo count($disabled) . " tools desligadas\n";
|
||||
' --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
### Verificar sempre depois, de forma independente
|
||||
|
||||
```bash
|
||||
wp option get emcp_tools_disabled_tools --format=json --path=$PATH --allow-root | grep -o 'rankmath-read' || echo "confirmado: activa (nao esta no deny-list)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Avaliação de risco por categoria — o que activar e o que nunca activar sem supervisão
|
||||
|
||||
| Categoria | Postura recomendada | Justificação |
|
||||
|---|---|---|
|
||||
| Leitura de design Elementor (o que fica activo por omissão — não está no deny-list) | ✅ Seguro por omissão | Propósito central do plugin; só leitura/inspecção, sem mutação |
|
||||
| SEO leitura isolada (ex.: só `rankmath-read`) | ✅ Seguro activar caso a caso | Não muta nada; útil para um agente auditar sem escrever — mas Rank Math continua a ser gerido preferencialmente via `/rank-math` (WP-CLI directo), não via MCP |
|
||||
| SEO escrita (qualquer `*-write` de SEO) | 🔴 Nunca activar sem supervisão | Contorna o fluxo de auditoria/rollback do `/rank-math`; risco de meta/schema incoerente sem revisão humana |
|
||||
| Redirecções/migração (`create-redirect`, `migrate-site`, `sync-to-live`) | 🔴 Nunca activar sem supervisão | Mutação estrutural com impacto em produção e SEO (redirects mal configurados = perda de ranking) |
|
||||
| Gestão de plugins/temas (`install-plugin`, `activate-plugin`, …) | 🔴 Nunca activar sem supervisão | Um agente autónomo instalar/remover plugins é a superfície mais perigosa depois de execução de código |
|
||||
| Snippets PHP (`create-php-snippet`, `validate-php-snippet`, `update-php-snippet`) | 🔴🔴 Nunca activar — risco máximo absoluto | **Execução de PHP arbitrário** persistido no site; equivalente a dar shell ao agente. Único candidato a "nunca, em circunstância nenhuma, sem revisão humana linha a linha antes de guardar" |
|
||||
| Ficheiros/sistema (`write-file`, `edit-file`, `delete-file`, `run-wp-cli`, `dispatch-wp-cli`) | 🔴🔴 Nunca activar — risco máximo | Escrita directa no filesystem e execução WP-CLI arbitrária via MCP; contorna toda a auditoria de shell/SSH existente |
|
||||
| Base de dados directa (`insert-row`, `update-rows`, `delete-rows`) | 🔴🔴 Nunca activar — risco máximo | SQL de escrita sem passar por validação da camada WP; risco de corrupção silenciosa |
|
||||
| Widgets/blocos custom (`create-custom-widget`, `create-custom-block`, …) | 🟡 Só com supervisão activa | Cria código PHP/JS executado no frontend; menos grave que snippets PHP mas ainda superfície de execução |
|
||||
| Utilizadores (`create-user`, `update-user`) | 🔴 Nunca activar sem supervisão | Escalada de privilégios / criação de contas fora do fluxo humano |
|
||||
| Memória do agente (`recall`, `remember`, `save-session-summary`) | 🟡 Avaliar por site | Sem risco de segurança directo, mas cria estado persistente fora do controlo humano — activar só se o workflow do site precisar de continuidade entre sessões MCP |
|
||||
| Integrações de terceiros — leitura (`woo-read`, `wpforms-read`, …) | 🟡 Seguro activar caso a caso, um a um | Só expõe dados existentes; activar apenas as integrações realmente instaladas no site, nunca em bloco |
|
||||
| Integrações de terceiros — escrita (`woo-write`, `cf7-write`, …) | 🔴 Nunca activar sem supervisão | Mutação em dados de negócio (encomendas, submissões de formulário) sem revisão humana |
|
||||
|
||||
**Regra geral (revista após leitura completa do código-fonte, §6-§8):** a
|
||||
**concepção** do plugin é default-deny bem desenhada — o deny-list incremental
|
||||
descrito em §8.1 fecha metodicamente cada nova categoria de risco assim que é
|
||||
lançada. Mas a **postura real, verificada ao vivo, NÃO é uniforme entre os 3
|
||||
sites**: `emanuelalmeida.pt` e `starter.descomplicar.pt` reflectem essa
|
||||
concepção (115/162 e 114/160 tools activas, respectivamente, com todas as
|
||||
categorias 🔴/🔴🔴 de facto fechadas); `descomplicar.pt` diverge de forma
|
||||
crítica — **165/165 tools registadas estão activas**, incluindo filesystem,
|
||||
base de dados directa, WP-CLI, PHP snippets e gestão de plugins/utilizadores
|
||||
(ver achado detalhado em §8.2). Qualquer activação deve ser: (1) ao nível de
|
||||
uma única tool, nunca em bloco; (2) reversível e verificada de imediato (§4,
|
||||
com o método correcto de §7/§8.3 — nunca por contagem de arrays); (3)
|
||||
documentada aqui ou em nota do site, para não perder rasto de porque é que
|
||||
uma excepção existe.
|
||||
|
||||
---
|
||||
|
||||
## 6. Módulos — os 9 blocos que a página *Modules* liga/desliga
|
||||
|
||||
Módulo ≠ ferramenta individual: é um interruptor de alto nível (`emcp_tools_active_modules`)
|
||||
que liga/desliga uma funcionalidade inteira (CPT, hooks de front-end, tab de admin e, nalguns
|
||||
casos, o próprio grupo de MCP tools). Cada módulo estende `EMCP_Tools_Module`
|
||||
(`includes/modules/class-module.php`) e expõe `tier()` (`free`/`pro`), `default_active()`
|
||||
(semeado uma única vez, via `EMCP_Tools_Modules_Registry::apply_defaults()`, marcador
|
||||
`emcp_tools_modules_seeded`) e `is_available()` (gate adicional, ex. licença Pro).
|
||||
**Um módulo `pro` pode estar "activo" no option e mesmo assim não fazer nada** — `is_available()`
|
||||
exige `emcp_tools_fs()->can_use_premium_code()`; nos 3 sites verificados (build Free, sem licença),
|
||||
`templates` e `agent-skills` estão semeados activos mas `is_available()` devolve `false`, logo não
|
||||
correm.
|
||||
|
||||
| Módulo (`id`) | Tier | Activo por omissão | Disponível nesta sessão (build Free, sem licença) | O que liga quando activo+disponível |
|
||||
|---|---|---|---|---|
|
||||
| `prompts` | free | sim | sim | Mostra a tab de admin **Prompts** (blueprints de prompts prontos a usar para construir páginas; amostras grátis + biblioteca Pro). Não regista MCP tools — é só UI de admin (`register()` vazio). |
|
||||
| `brand-kits` | free | sim | sim | Mostra a tab **Brand Kits** (kits de cor+tipografia de um clique; kits grátis + biblioteca Pro). Também só UI de admin, sem MCP tools próprias. |
|
||||
| `cloud` | free | sim | sim | Arranca `EMCP_Tools_Cloud_Connect::init()` (fluxo OAuth de ligação à conta EMCP Cloud) e — só quando `EMCP_Tools_Cloud::is_connected()` for verdadeiro — regista as 7 ferramentas `cloud-*` (§5 tabela de categorias). Nos 3 sites: módulo activo mas nenhum ligado a uma conta Cloud, logo 0 tools `cloud-*` registadas. |
|
||||
| `templates` | **pro** | sim (seeded) | **não** (sem licença) | Quando disponível: mostra a tab **Templates** (templates de página Elementor prontos a aplicar). Metadata-only (`register()` vazio) — vive na árvore free só como descrição, a lógica Pro real está fora deste build. |
|
||||
| `themer` | free | sim | sim | O módulo mais substancial do bundle free: regista o CPT `EMCP_Tools_Themer_CPT`, o índice de condições, o controlador de render no front-end, a metabox de admin, blocos Gutenberg dinâmicos, widgets Elementor dinâmicos e templates PHP (Themer PHP, sub-toggle próprio). Desligar este módulo é kill-switch total — pára o CPT, o front-end takeover, a tab, **e** o registrador de abilities omite as 8 tools `*-theme-template*`/`*-template*` (§5). |
|
||||
| `redirects` | free | sim | sim | Instala a tabela do Redirect Manager, liga o handler de 301/302 no front-end, o scan de links partidos e as sugestões de redirect ao apagar/renomear uma página. Desligar pára tudo isto **e** remove as 5 tools `*-redirect*`/`find-broken-links` do registo. |
|
||||
| `agent-skills` | **pro** | sim (seeded) | **não** (sem licença) | Quando disponível: expõe `list-skills`/`get-skill` aos agentes ligados + injecta um catálogo `## Skills` (~900 tokens) no contexto de discovery. Metadata-only na árvore free. |
|
||||
| `image-optimization` | free | **não** (opt-in) | depende (precisa de editor de imagem com suporte WebP) | Comprime uploads (`wp_generate_attachment_metadata`) e gera/serve WebP (rewriter de URL); regista `resize-media`. 5 opções próprias: `compress`, `webp`, `webp_serve`, `quality` (0-100, default 60), `max_dimension`, `keep_originals`. Um optimizador retomável trata a biblioteca já existente a partir do card do módulo. |
|
||||
| `svg-support` | free | **não** (opt-in — superfície de segurança) | depende (precisa da lib `enshrined/svg-sanitize` bundled) | Permite upload de SVG (mime `svg`) para quem tiver a capability necessária, corrige `wp_check_filetype_and_ext()` para REST/sideload, e sanitiza cada SVG (fail-closed: um SVG que não possa ser limpo é rejeitado). Uma opção: `admin_only` (restringe upload a administradores). Nota: se o Elementor já permitir SVG (como normalmente acontece), este módulo é redundante excepto pela sanitização extra. |
|
||||
|
||||
---
|
||||
|
||||
## 7. Inventário verificado das ~162 abilities registadas (build Free, Elementor activo) — por categoria
|
||||
|
||||
**Correcção a uma hipótese de partida:** subtrair ingenuamente 162 − 131 = "~31 activas" está
|
||||
**errado** — 84 dos 131 slugs em `emcp_tools_disabled_tools` são nomes de ferramentas **Pro**
|
||||
(WooCommerce, 6 SEO plugins além do Slim SEO, 5 dos 6 plugins de formulários, frameworks de
|
||||
tema além do Astra, memória do agente, Themer PHP, SEO/A11y automático, Widget/Block Builder —
|
||||
ver lista completa em §2) que **nunca chegam a registar-se** neste build Free — estão pré-semeados
|
||||
no option para o dia em que o site tiver licença Pro, mas `wp_get_abilities()` não os devolve porque
|
||||
as classes Pro não existem na árvore free. Contá-los como "desligados" infla artificialmente a
|
||||
contagem de fechadas e desinfla a de activas.
|
||||
|
||||
**Método de verificação usada** (a única fonte fiável — ver aviso sobre `wp mcp-adapter list` no
|
||||
topo deste documento):
|
||||
|
||||
```bash
|
||||
wp eval '
|
||||
$abilities = wp_get_abilities();
|
||||
$emcp = array_filter(array_keys($abilities), function($k){ return strpos($k, "emcp-tools/") === 0; });
|
||||
$disabled = get_option("emcp_tools_disabled_tools", []);
|
||||
$active = array_diff($emcp, $disabled);
|
||||
echo "registadas=" . count($emcp) . " desligadas(option)=" . count($disabled) . " activas=" . count($active) . "\n";
|
||||
' --path=$PATH --allow-root
|
||||
```
|
||||
|
||||
**Resultado real, verificado ao vivo (16-08-2026):**
|
||||
|
||||
| Site | Abilities `emcp-tools/*` registadas | Entradas em `emcp_tools_disabled_tools` | … das quais correspondem a uma ability REALMENTE registada | Activas (registada E não desligada) |
|
||||
|---|---|---|---|---|
|
||||
| `emanuelalmeida.pt` | 162 | 131 | 47 | **115** |
|
||||
| `starter.descomplicar.pt` | 160 | 131 | ~46 | **114** |
|
||||
| `descomplicar.pt` | 165 | 78 | **0** | **165** (ver achado crítico, §8) |
|
||||
|
||||
A tabela abaixo usa `emanuelalmeida.pt` (162 registadas) como referência — é o site com a
|
||||
config mais representativa da postura default-deny pretendida pelo plugin (`starter` é quase
|
||||
idêntico; `descomplicar.pt` diverge de forma crítica, ver §8). Por categoria: ferramentas
|
||||
**ACTIVAS** (chamáveis agora), **DESLIGADAS** (bloqueadas pelo deny-list, mas registadas — activáveis
|
||||
via §4), e, quando aplicável, ferramentas do grupo que **nem chegam a registar-se** neste site
|
||||
(dependem de um plugin/tema de terceiros ausente).
|
||||
|
||||
| Categoria | O que faz | Activas | Desligadas |
|
||||
|---|---|---|---|
|
||||
| **Compact tool mode (dispatcher)** | `list-tools`/`get-tool-schema`/`call-tool` — o modo de despacho compacto (3 ferramentas que expõem indirectamente todas as outras); descrito na arquitectura do servidor MCP no início deste documento. | `call-tool`, `get-tool-schema`, `list-tools` | — |
|
||||
| **Elementor — descoberta/query (P0)** | Fundação de leitura: percorre containers/elementos, resolve schemas de widget/container, lista páginas Elementor e templates disponíveis. | `find-element`, `get-container-schema`, `get-element-settings`, `get-page-structure`, `get-widget-schema`, `list-pages`, `list-templates`, `list-widgets` | — |
|
||||
| **Elementor — páginas (P1 CRUD)** | Cria/edita páginas Elementor, exporta o conteúdo de uma página, importa um template para uma página, e ajusta page settings (SEO básico, layout). | `create-page`, `delete-page-content`, `export-page`, `import-template`, `update-page-settings` | — |
|
||||
| **Elementor — layout/container** | Manipula a árvore de containers/flexbox/elementos: adicionar, mover, duplicar, remover, reordenar, actualizar propriedades, edição em lote (`batch-update`). | `add-container`, `batch-update`, `duplicate-element`, `move-element`, `remove-element`, `reorder-elements`, `set-element-label`, `update-container`, `update-element` | — |
|
||||
| **Elementor — widgets clássicos (catálogo)** | Coloca widgets Elementor gratuitos no layout e actualiza as suas definições; `add-pro-widget` (Elementor Pro) fica desligado por omissão. | `add-free-widget`, `update-widget` | `add-pro-widget` |
|
||||
| **Elementor — templates/popups/dynamic tags** | `apply-template`/`save-as-template` activos (aplicar/gravar templates de página); criação de theme templates, popups, dynamic tags e condições de exibição ficam desligados (mutação estrutural). | `apply-template`, `save-as-template` | `create-elementor-theme-template`, `create-popup`, `list-dynamic-tags`, `set-dynamic-tag`, `set-elementor-template-conditions`, `set-popup-settings` |
|
||||
| **Elementor — configurações globais (cores/tipografia)** | Lê e actualiza o kit global (cores e tipografia do site) — `get-global-settings` está agrupado na categoria Query (P0) mas afecta as mesmas definições. | `get-global-settings`, `update-global-colors`, `update-global-typography` | — |
|
||||
| **Elementor — build-page composto** | `build-page` — ferramenta de alto nível que constrói uma página inteira a partir de uma especificação estruturada (composição de containers+widgets num único pedido). | `build-page` | — |
|
||||
| **Elementor — SVG icons** | `upload-svg-icon` — envia um SVG para a biblioteca de ícones Elementor (sanitizado). | `upload-svg-icon` | — |
|
||||
| **Elementor — custom code (CSS/JS/snippets)** | `add-custom-js` activo (injecta JS Elementor); `add-custom-css`, `add-code-snippet` e `list-code-snippets` ficam desligados (execução/injecção persistente). | `add-custom-js` | `add-code-snippet`, `add-custom-css`, `list-code-snippets` |
|
||||
| **Elementor 4.0+ — atomic widgets** | Widgets atómicos do Elementor 4.0+ (heading, paragraph, button, image, svg, youtube, video, divider) e o genérico `add-atomic-widget`/`update-atomic-widget` — todos activos. | `add-atomic-button`, `add-atomic-divider`, `add-atomic-heading`, `add-atomic-image`, `add-atomic-paragraph`, `add-atomic-svg`, `add-atomic-video`, `add-atomic-widget`, `add-atomic-youtube`, `update-atomic-widget` | — |
|
||||
| **Elementor 4.0+ — atomic layout (flexbox/div-block)** | `add-div-block`, `add-flexbox` (containers atómicos) e `detect-elementor-version` (detecta se o site suporta Elementor 4.0+ atomic). | `add-div-block`, `add-flexbox`, `detect-elementor-version` | — |
|
||||
| **Elementor 4.0+ — global classes (leitura)** | `list-global-classes` — lista as classes CSS globais do Elementor 4.0+. | `list-global-classes` | — |
|
||||
| **Elementor 4.0+ — global classes (escrita)** | Criar/actualizar/eliminar/reordenar classes globais — todas desligadas por omissão (mutação de CSS partilhado entre todas as páginas). | — | `create-global-class`, `delete-global-class`, `reorder-global-classes`, `update-global-class` |
|
||||
| **Gutenberg (blocos nativos)** | Conjunto completo de leitura+escrita para blocos Gutenberg nativos (descoberta de blocos/patterns, inserir pattern, CRUD de blocos numa página) — todo activo por omissão (Gutenberg é considerado superfície de baixo risco face ao Elementor neste bundle). | `add-block`, `duplicate-block`, `get-block-schema`, `get-post-blocks`, `insert-pattern`, `list-blocks`, `list-patterns`, `move-block`, `remove-block`, `update-block` | — |
|
||||
| **Page Snapshot** | `get-page-snapshot` — digest normalizado de uma página (base para outras ferramentas de leitura); sempre activo. | `get-page-snapshot` | — |
|
||||
| **Transações/rollback (change ledger)** | `get-change`/`list-changes`/`rollback-change` — ledger de alterações feitas via MCP com possibilidade de reverter; sempre activo (é a rede de segurança das escritas). | `get-change`, `list-changes`, `rollback-change` | — |
|
||||
| **Pesquisa de conteúdo (índice léxico)** | `search-content`/`reindex-search` — índice léxico sobre páginas/templates/widgets/globals. | `reindex-search`, `search-content` | — |
|
||||
| **Content mirror (export/restore git-friendly)** | `export-content`/`list-content-exports`/`restore-content` — exporta conteúdo de página como ficheiros rastreáveis em git e permite restaurar. | `export-content`, `list-content-exports`, `restore-content` | — |
|
||||
| **WordPress — conteúdo (posts/CPT/taxonomias)** | CRUD completo de posts/CPT (criar, ler, listar, actualizar, eliminar), listar post types/taxonomias, definir termos — activo por omissão. | `create-post`, `delete-post`, `get-post`, `list-post-types`, `list-posts`, `list-taxonomies`, `set-post-terms`, `update-post` | — |
|
||||
| **WordPress — media library** | Ler/listar/actualizar/carregar media activos; `delete-media` desligado (eliminação permanente). | `get-media`, `list-media`, `update-media`, `upload-media` | `delete-media` |
|
||||
| **WordPress — resize de imagem** | `resize-media` só regista quando o módulo Image Optimization está activo (reutiliza o motor de compressão/WebP) — não registado nesta sessão porque o módulo está desligado por omissão. | *(nenhuma — grupo não registado: `resize-media`)* | *(n/a — ver nota)* |
|
||||
| **WordPress — settings** | `get-settings`/`update-settings` — leitura e escrita de um conjunto curado de definições do site (não é `wp_options` livre). | `get-settings`, `update-settings` | — |
|
||||
| **WordPress — plugins** | Listar/pesquisar plugins fica activo; instalar/activar/desactivar/actualizar/eliminar plugin ficam desligados (superfície de maior risco depois de execução de código). | `list-plugins`, `search-plugins` | `activate-plugin`, `deactivate-plugin`, `delete-plugin`, `install-plugin`, `update-plugin` |
|
||||
| **WordPress — temas (gestão)** | Listar/pesquisar temas activo; instalar/mudar/actualizar/eliminar tema desligados. | `list-themes`, `search-themes` | `delete-theme`, `install-theme`, `switch-theme`, `update-theme` |
|
||||
| **WordPress — utilizadores** | Ler/listar utilizadores activo; criar/actualizar utilizador desligados (escalada de privilégios). | `get-user`, `list-users` | `create-user`, `update-user` |
|
||||
| **WordPress — menus de navegação** | `menu-read`/`menu-write` — ambos activos por omissão (menus, itens, theme locations, render). | `menu-read`, `menu-write` | — |
|
||||
| **Tema activo (framework-agnostic)** | `theme-read` activo (`get-theme-context`, `get-mods` — identidade do tema, theme_mods); `theme-write` desligado (`set-mods`, `create-child-theme`). | `theme-read` | `theme-write` |
|
||||
| **Astra (tema)** | Só regista quando o Astra é o tema activo. `astra-read` activo (definições Astra Customizer); `astra-write` desligado. | `astra-read` | `astra-write` |
|
||||
| **ACF (Advanced Custom Fields)** | Dispatcher `acf-read`/`acf-write` + 15 operações (field groups, post types, taxonomias, options pages) — só regista se ACF (free ou Pro) estiver activo no site; não registado nesta sessão (ACF ausente). | *(nenhuma — grupo não registado: `acf-read`, `acf-write`, `create-acf-field-group`, `create-acf-post-type`, `create-acf-taxonomy`, `get-acf-field-group`, `get-acf-fields`, `get-acf-post-type`, `get-acf-taxonomy`, `list-acf-field-groups`, `list-acf-options-pages`, `list-acf-post-types`, `list-acf-taxonomies`, `update-acf-field-group`, `update-acf-fields`, `update-acf-post-type`, `update-acf-taxonomy`)* | *(n/a — ver nota)* |
|
||||
| **Meta Box** | Dispatcher `metabox-read`/`metabox-write` — só regista se o Meta Box estiver activo; não registado nesta sessão. | *(nenhuma — grupo não registado: `metabox-read`, `metabox-write`)* | *(n/a — ver nota)* |
|
||||
| **Themer (free) — templates de header/footer/single/archive** | CPT + condições de exibição para header/footer/single/archive/search/404 com qualquer page builder. Todo o grupo activo por omissão: listar/obter/criar/actualizar/eliminar template, listar alvos de condição, definir condições, resolver qual template se aplica a um contexto. | `create-theme-template`, `delete-theme-template`, `get-theme-template`, `list-condition-targets`, `list-theme-templates`, `resolve-template`, `set-template-conditions`, `update-theme-template` | — |
|
||||
| **Themer PHP templates (toggle próprio)** | Sub-funcionalidade do Themer para templates PHP brutos, atrás de um toggle independente (`EMCP_Tools_Themer_PHP::enabled()`) — não activo nesta sessão, por isso as 5 tools não estão sequer registadas. | *(nenhuma — grupo não registado: `create-theme-php-template`, `delete-theme-php-template`, `get-theme-php-template`, `list-theme-php-templates`, `update-theme-php-template`)* | *(n/a — ver nota)* |
|
||||
| **Redirect Manager** | `list-redirects`/`find-broken-links` activos (leitura + scan de links partidos); `create/update/delete-redirect` desligados (mutação de routing com impacto directo em SEO). | `find-broken-links`, `list-redirects` | `create-redirect`, `delete-redirect`, `update-redirect` |
|
||||
| **Stock images (busca + sideload + widget)** | `search-images`/`sideload-image`/`add-stock-image` — pesquisa num provider de stock, descarrega para a Media Library, e coloca como widget de imagem; todo activo (não muta nada fora da Media Library). | `add-stock-image`, `search-images`, `sideload-image` | — |
|
||||
| **Performance Analyzer** | `analyze-performance` — auditoria de performance só de leitura. | `analyze-performance` | — |
|
||||
| **Security & Malware Scanner** | `scan-security` — scanner de malware/postura de segurança, só leitura, sempre activo. | `scan-security` | — |
|
||||
| **Filesystem** | `list-directory`/`read-file`/`search-files` activos; `write-file`/`edit-file`/`delete-file` desligados (escrita directa no filesystem). | `list-directory`, `read-file`, `search-files` | `delete-file`, `edit-file`, `write-file` |
|
||||
| **Base de dados directa** | `describe-table`/`list-tables`/`query` (SELECT) activos; `insert-row`/`update-rows`/`delete-rows` desligados (escrita SQL directa). | `describe-table`, `list-tables`, `query` | `delete-rows`, `insert-row`, `update-rows` |
|
||||
| **WP-CLI (run + jobs)** | `run-wp-cli`/`dispatch-wp-cli`/`get-wp-cli-job`/`list-wp-cli-jobs` — todo o grupo desligado por omissão (execução arbitrária de comandos WP-CLI). | — | `dispatch-wp-cli`, `get-wp-cli-job`, `list-wp-cli-jobs`, `run-wp-cli` |
|
||||
| **PHP Snippets (Sandbox)** | `validate/create/update/get/list/delete-php-snippet` — todo o grupo desligado por omissão (execução de PHP arbitrário persistido). | — | `create-php-snippet`, `delete-php-snippet`, `get-php-snippet`, `list-php-snippets`, `update-php-snippet`, `validate-php-snippet` |
|
||||
| **Sandbox — export/import cloud (bundle)** | `export-sandbox-artifact`/`import-sandbox-artifact` — exporta/importa um artefacto de sandbox (bloco/widget/snippet) como bundle; ambos activos (o bundle em si não executa nada, é só serialização). | `export-sandbox-artifact`, `import-sandbox-artifact` | — |
|
||||
| **EMCP Cloud (sync remoto)** | `cloud-status`/`cloud-backup`/`cloud-list`/`cloud-pull`/`cloud-config-sync`/`cloud-marketplace-list`/`cloud-marketplace-install` — só registam quando o módulo Cloud está activo E o site está ligado a uma conta EMCP Cloud; não registadas nesta sessão porque nenhum dos 3 sites está ligado a uma conta Cloud (ver módulo `cloud`, §6). | *(nenhuma — grupo não registado: `cloud-backup`, `cloud-config-sync`, `cloud-list`, `cloud-marketplace-install`, `cloud-marketplace-list`, `cloud-pull`, `cloud-status`)* | *(n/a — ver nota)* |
|
||||
|
||||
---
|
||||
|
||||
## 8. Mecanismo do deny-list incremental — e um achado crítico ao vivo em `descomplicar.pt`
|
||||
|
||||
### 8.1 Como o plugin decide o que fecha por omissão
|
||||
|
||||
O deny-list não é estático: `includes/admin/class-admin.php`, método
|
||||
`maybe_apply_default_disabled_tools()` (chamado no boot do admin), aplica **34 blocos de migração
|
||||
incremental** (`DEFAULTS_VERSION = 34`, contador `emcp_tools_defaults_applied`), cada um
|
||||
introduzido numa versão do plugin para fechar uma nova categoria de tool assim que ela é lançada
|
||||
— ex.: v6 fecha escrita de plugins/temas, v9 fecha filesystem, v10 fecha base de dados, v18 fecha
|
||||
WP-CLI, v28 fecha escrita de global classes, v33-34 fecham as tools de migração/sync. A função só
|
||||
adiciona slugs (nunca remove uma escolha do utilizador) e só corre os blocos cujo número é maior
|
||||
que o `$applied` já gravado:
|
||||
|
||||
```php
|
||||
if ( $applied < N ) { $add = array_merge( $add, /* slugs da versão N */ ); }
|
||||
// ...
|
||||
update_option( self::OPTION_DISABLED_TOOLS, array_values( array_unique( array_merge( $existing, $add ) ) ) );
|
||||
update_option( self::OPTION_DEFAULTS_APPLIED, (string) self::DEFAULTS_VERSION );
|
||||
```
|
||||
|
||||
Consequência arquitectural importante: **um site cujo `emcp_tools_defaults_applied` já esteja em
|
||||
34 nunca mais recebe fecho automático de tools novas**, mesmo que o plugin lance uma v35 no
|
||||
futuro — nesse cenário a nova categoria nasceria **activa** nesse site até alguém a fechar à mão. E
|
||||
mais relevante ainda para o presente: se o valor de `emcp_tools_disabled_tools` for alterado
|
||||
manualmente (via `wp eval`/`array_diff`, como o método §4 deste documento ensina, ou por qualquer
|
||||
outro caminho) **removendo** entradas em massa, o contador de versão não volta atrás — o site fica
|
||||
com um deny-list mais pequeno do que o "de fábrica" para essa versão, sem qualquer aviso.
|
||||
|
||||
### 8.2 🔴 Achado crítico verificado ao vivo (16-08-2026) — `descomplicar.pt`
|
||||
|
||||
Ao aplicar o método de verificação do §7 aos 3 sites, `descomplicar.pt` destacou-se: `active=165`
|
||||
= `registered=165` — **zero ferramentas efectivamente fechadas**, apesar de
|
||||
`emcp_tools_disabled_tools` ter 78 entradas. Inspeccionando essas 78 entradas
|
||||
(`wp option get emcp_tools_disabled_tools --format=json --path=/home/ealmeida/public_html`):
|
||||
são **exclusivamente** slugs de integrações de terceiros que não estão instaladas neste site
|
||||
(WooCommerce, Essential/Premium Addons, UAE, os 6 plugins de formulários, os 7 plugins de SEO,
|
||||
Astra/Spectra/Kadence/GeneratePress/Blocksy, `recall`/`remember`/`save-session-summary`, os 4
|
||||
achados SEO/A11y automáticos, e os 16 slugs do Widget/Block Builder Pro) — **nenhuma** das
|
||||
categorias nativas mais perigosas (filesystem, base de dados, WP-CLI, PHP snippets, gestão de
|
||||
plugins/temas, gestão de utilizadores) aparece nessa lista. Confirmado directamente, ferramenta a
|
||||
ferramenta:
|
||||
|
||||
| Tool | Registada em `descomplicar.pt`? | Está no deny-list? | **Chamável agora via MCP?** |
|
||||
|---|---|---|---|
|
||||
| `emcp-tools/write-file` | sim | não | **🔴 SIM** |
|
||||
| `emcp-tools/edit-file` | sim | não | **🔴 SIM** |
|
||||
| `emcp-tools/delete-file` | sim | não | **🔴 SIM** |
|
||||
| `emcp-tools/run-wp-cli` | sim | não | **🔴 SIM** |
|
||||
| `emcp-tools/dispatch-wp-cli` | sim | não | **🔴 SIM** |
|
||||
| `emcp-tools/insert-row` | sim | não | **🔴 SIM** |
|
||||
| `emcp-tools/update-rows` | sim | não | **🔴 SIM** |
|
||||
| `emcp-tools/delete-rows` | sim | não | **🔴 SIM** |
|
||||
| `emcp-tools/create-php-snippet` | sim | não | **🔴 SIM** |
|
||||
| `emcp-tools/update-php-snippet` | sim | não | **🔴 SIM** |
|
||||
| `emcp-tools/install-plugin` | sim | não | **🔴 SIM** |
|
||||
| `emcp-tools/activate-plugin` | sim | não | **🔴 SIM** |
|
||||
| `emcp-tools/create-user` | sim | não | **🔴 SIM** |
|
||||
| `emcp-tools/update-user` | sim | não | **🔴 SIM** |
|
||||
|
||||
Todas as 34 versões de migração já correram (`emcp_tools_defaults_applied = 34`, igual aos outros
|
||||
2 sites), o que exclui "instalação nunca migrada" como explicação — a hipótese mais provável, dado
|
||||
o padrão exacto de remoção (sobrevivem só integrações de terceiros; desaparecem só as categorias
|
||||
nativas de risco máximo/alto de §5), é que o array foi reescrito manualmente nalgum momento — por
|
||||
exemplo com uma variante do próprio comando de §4 aplicada de forma demasiado ampla (ex.:
|
||||
`array_diff` contra uma lista de slugs "de terceiros" em vez de um único slug) — sem que a
|
||||
subtracção tenha sido revertida depois.
|
||||
|
||||
**Isto não foi corrigido nesta tarefa** (o âmbito desta expansão de skill é só leitura — ver
|
||||
constraints). **Requer decisão humana urgente**: ou (a) confirmar que a abertura destas 14+ tools
|
||||
nativas em `descomplicar.pt` foi intencional e está devidamente supervisionada, ou (b) alinhar
|
||||
`descomplicar.pt` com o deny-list dos outros 2 sites, repondo pelo menos as categorias 🔴🔴 de §5
|
||||
(filesystem, base de dados, WP-CLI, snippets PHP) com o padrão do método §4, aplicado entrada a
|
||||
entrada.
|
||||
|
||||
### 8.3 Regra de verificação a aplicar sempre, daqui em diante
|
||||
|
||||
**Nunca confiar na contagem de entradas em `emcp_tools_disabled_tools` isoladamente** — nem para
|
||||
avaliar "quão fechado" está um site (v. `descomplicar.pt`, 78 entradas e 0 tools realmente
|
||||
fechadas), nem para o inverso (a lista de 131 em `emanuelalmeida.pt`/`starter` também tem 84
|
||||
entradas "mortas" que nunca vão fechar nada neste build). O único método correcto é o `wp eval` +
|
||||
`wp_get_abilities()` do §7, comparado slug a slug contra `emcp_tools_disabled_tools` — nunca o
|
||||
tamanho dos arrays, nunca a coluna `Tools` de `wp mcp-adapter list` (ver aviso na arquitectura, que
|
||||
mostra `3` para `descomplicar.pt` quando o valor real é 165).
|
||||
|
||||
---
|
||||
|
||||
## Fonte
|
||||
|
||||
`Hub/04-Stack/02.04-Sistemas/71.Seguranca/CONFIG-Plugins-Referencia.md` §10
|
||||
(EMCP Tools, mapeado 16-08-2026) + `BUNDLE-Excelencia-WP.md` (contexto do
|
||||
bundle e registo dos 3 sites) + verificação SSH ao vivo nesta tarefa
|
||||
(`wp option list/get`, `wp plugin get`, `wp mcp-adapter list`,
|
||||
`~/.omp/agent/mcp.json`) em `descomplicar.pt`, `starter.descomplicar.pt` e
|
||||
`emanuelalmeida.pt` **+ leitura completa do código-fonte do plugin
|
||||
(build Free `emcp-tools` 3.12.1) em `emanuelalmeida.pt`**: todos os ficheiros
|
||||
em `includes/abilities/` (46 classes de abilities + integrações
|
||||
forms/seo), `includes/modules/` (9 módulos + sub-módulos Image Optimization
|
||||
e SVG Support), `includes/admin/class-admin.php` (catálogo de tools,
|
||||
`maybe_apply_default_disabled_tools()`, as 34 versões do deny-list
|
||||
incremental), `includes/modules/class-modules-registry.php` +
|
||||
`class-module.php` (ciclo de vida dos módulos), `includes/class-migration.php`
|
||||
(migração `elementor-mcp` → `emcp-tools`), `emcp-tools.php` (bootstrap,
|
||||
guarda Free⇄Pro) — e verificação ao vivo via `wp eval` + `wp_get_abilities()`
|
||||
filtrado a `emcp-tools/*` cruzado slug-a-slug contra
|
||||
`emcp_tools_disabled_tools`, nos 3 sites (método completo em §7).
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
name: powerpack-widgets
|
||||
description: Catálogo completo e verificado dos 97 widgets PowerPack Elements Pro para Elementor, com o widgetType real de cada um extraído do código-fonte (classes/class-pp-config.php) — não estão no catálogo curado do EMCP Tools (list-widgets), por isso precisam de get-widget-schema com full:true. Usar quando "powerpack", "pp-widget", "advanced menu elementor", "hotspots elementor", "flip box powerpack", "woo product elementor", "info box powerpack".
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# /powerpack-widgets — Catálogo de Widgets PowerPack Elements Pro
|
||||
|
||||
PowerPack Elements (Team IdeaBox, plugin `powerpack-elements`) regista os próprios widgets Elementor **fora** do catálogo curado do EMCP Tools — `list-widgets` não os lista. Este catálogo foi extraído directamente do array de configuração fonte (`wp-content/plugins/powerpack-elements/classes/class-pp-config.php`, método `get_widget_info()`) num site em produção com PowerPack Elements Pro 2.11.7 — **não adivinhado por convenção de nomes**, o que importa porque a convenção `pp-<nome-módulo>` tem excepções reais confirmadas (ver notas abaixo da tabela).
|
||||
|
||||
Catálogo completo (97 widgets) em `references/catalogo.md` — esta página tem o workflow e os widgets mais úteis para arranque rápido.
|
||||
|
||||
## Como usar (workflow)
|
||||
|
||||
1. Confirmar que `powerpack-elements` está activo: `list-plugins`, procurar o slug.
|
||||
2. `get-widget-schema({ widget_type: "pp-<slug>", full: true })` — **não estão no catálogo curado**, a chamada sem `full:true` devolve erro "Not in the curated catalog". `full:true` devolve o schema de controlos bruto.
|
||||
3. Adicionar com `add-free-widget({ post_id, parent_id, widget_type, settings })` num container **legacy** (`add-container`) — mesma mecânica de `elementskit-widgets`, sem equivalente atómico.
|
||||
4. **Nunca assumir o `widgetType` pelo nome da pasta do módulo** — verificado no código-fonte: `Hotspots` → `pp-image-hotspots` (não `pp-hotspots`), `Onepage_Nav` → `pp-one-page-nav` (não `pp-onepage-nav`), `Popup_Box` (pasta `modal-popup`) → `pp-modal-popup`, `Link_Effects` → **`pa-link-effects`** (prefixo `pa-`, não `pp-`!). Confirmar sempre com `get-widget-schema(full:true)` antes de construir em produção — ver tabela completa para todas as excepções.
|
||||
|
||||
## Widgets mais usados (ver `references/catalogo.md` para os 97 completos)
|
||||
|
||||
| `widgetType` | Título | Uso |
|
||||
|---|---|---|
|
||||
| `pp-info-box` | Info Box | ícone/imagem + título + descrição, muito usado em secções de features |
|
||||
| `pp-flipbox` | Flip Box | cartão de dois lados com flip ao hover |
|
||||
| `pp-advanced-menu` | Advanced Menu | menu de navegação avançado com mega-menu |
|
||||
| `pp-image-hotspots` | Image Hotspots | pontos interactivos sobre imagem (excepção de nome — pasta `hotspots`) |
|
||||
| `pp-pricing-table` | Pricing Table | tabela de preços |
|
||||
| `pp-team-member` | Team Member | cartão de membro de equipa |
|
||||
| `pp-testimonials` | Testimonials | testemunhos com carrossel |
|
||||
| `pp-posts` | Advanced Posts | grelha/lista de posts avançada com query control |
|
||||
| `pp-login-form` | Login Form | formulário de login frontend |
|
||||
| `pp-business-hours` | Business Hours | horário de funcionamento |
|
||||
| `pp-countdown` | Countdown Timer | temporizador |
|
||||
| `pp-table-of-contents` | Table of Contents | índice automático |
|
||||
| `pp-instafeed` | Instagram Feed | feed do Instagram |
|
||||
| `pp-modal-popup` | Popup Box | popup modal (excepção de nome — pasta `modal-popup`) |
|
||||
| `pp-woo-product-price` | Woo — Product Price | preço de produto WooCommerce, um de ~15 widgets `pp-woo-*` |
|
||||
|
||||
## Notas
|
||||
|
||||
- 15 dos 97 widgets são específicos WooCommerce (`pp-woo-*`) e só têm efeito útil com WooCommerce activo e no contexto de um produto/loja.
|
||||
- Alguns módulos listados no directório `modules/` (`display-conditions`, `dynamic-tags`, `presets-style`, `query-control`, `devices`) são **extensões transversais**, não widgets autónomos — não aparecem no catálogo porque não têm `widgetType` próprio; afectam definições de outros widgets PowerPack (o mesmo padrão visto no `elementskit-widgets` com `ekit_cursor_text_label`).
|
||||
|
||||
## Skills relacionadas
|
||||
- `emcp-page-building` — mecânica de coexistência atómico/legacy, sequência de construção.
|
||||
- `elementor-pro-widgets` — catálogo nativo Elementor Pro (curado, no `list-widgets`).
|
||||
- `elementskit-widgets` — catálogo do addon concorrente ElementsKit Lite (também fora do catálogo curado).
|
||||
@@ -0,0 +1,113 @@
|
||||
# Catálogo completo — 97 widgets PowerPack Elements Pro
|
||||
|
||||
Extraído ao vivo de `wp-content/plugins/powerpack-elements/classes/class-pp-config.php`, método `get_widget_info()`, num site em produção com PowerPack Elements Pro 2.11.7. Coluna `Classe PHP` é o identificador interno do módulo (útil para localizar o ficheiro fonte em `modules/<pasta>/widgets/`); coluna `widgetType` é o valor real gravado em `_elementor_data` e usado em `get-widget-schema`/`add-free-widget`.
|
||||
|
||||
| widgetType | Título | Classe PHP |
|
||||
|---|---|---|
|
||||
| `pp-advanced-accordion` | Advanced Accordion | Advanced_Accordion |
|
||||
| `pp-advanced-menu` | Advanced Menu | Advanced_Menu |
|
||||
| `pp-advanced-tabs` | Advanced Tabs | Advanced_Tabs |
|
||||
| `pp-album` | Album | Album |
|
||||
| `pp-author-list` | Author List | Author_List |
|
||||
| `pp-breadcrumbs` | Breadcrumbs | Breadcrumbs |
|
||||
| `pp-business-hours` | Business Hours | Business_Hours |
|
||||
| `pp-business-reviews` | Business Reviews | Business_Reviews |
|
||||
| `pp-buttons` | Buttons | Buttons |
|
||||
| `pp-card-slider` | Card Slider | Card_Slider |
|
||||
| `pp-categories` | Categories | Categories |
|
||||
| `pp-contact-form-7` | Contact Form 7 | Contact_Form_7 |
|
||||
| `pp-content-reveal` | Content Reveal | Content_Reveal |
|
||||
| `pp-content-ticker` | Content Ticker | Content_Ticker |
|
||||
| `pp-countdown` | Countdown Timer | Countdown |
|
||||
| `pp-counter` | Counter | Counter |
|
||||
| `pp-coupons` | Coupons | Coupons |
|
||||
| `pp-devices` | Devices | Devices |
|
||||
| `pp-divider` | Divider | Divider |
|
||||
| `pp-faq` | FAQ | Faq |
|
||||
| `pp-flipbox` | Flip Box | Flipbox |
|
||||
| `pp-fluent-forms` | Fluent Forms | Fluent_Forms |
|
||||
| `pp-formidable-forms` | Formidable Forms | Formidable_Forms |
|
||||
| `pp-image-gallery` | Image Gallery | Image_Gallery |
|
||||
| `pp-image-slider` | Image Slider | Image_Slider |
|
||||
| `pp-google-maps` | Google Maps | Google_Maps |
|
||||
| `pp-gravity-forms` | Gravity Forms | Gravity_Forms |
|
||||
| `pp-dual-heading` | Dual Heading | Dual_Heading |
|
||||
| `pp-fancy-heading` | Fancy Heading | Fancy_Heading |
|
||||
| `pp-image-hotspots` | Image Hotspots | Hotspots |
|
||||
| `pp-how-to` | How To | How_To |
|
||||
| `pp-icon-list` | Icon List | Icon_List |
|
||||
| `pp-image-accordion` | Image Accordion | Image_Accordion |
|
||||
| `pp-image-comparison` | Image Comparison | Image_Comparison |
|
||||
| `pp-info-box` | Info Box | Info_Box |
|
||||
| `pp-info-box-carousel` | Info Grid & Carousel | Info_Box_Carousel |
|
||||
| `pp-info-list` | Info List | Info_List |
|
||||
| `pp-info-table` | Info Table | Info_Table |
|
||||
| `pp-instafeed` | Instagram Feed | Instafeed |
|
||||
| `pa-link-effects` | Link Effects | Link_Effects |
|
||||
| `pp-login-form` | Login Form | Login_Form |
|
||||
| `pp-logo-carousel` | Logo Carousel | Logo_Carousel |
|
||||
| `pp-logo-grid` | Logo Grid | Logo_Grid |
|
||||
| `pp-magazine-slider` | Magazine Slider | Magazine_Slider |
|
||||
| `pp-ninja-forms` | Ninja Forms | Ninja_Forms |
|
||||
| `pp-offcanvas-content` | Offcanvas Content | Offcanvas_Content |
|
||||
| `pp-one-page-nav` | One Page Navigation | Onepage_Nav |
|
||||
| `pp-modal-popup` | Popup Box | Popup_Box |
|
||||
| `pp-posts` | Advanced Posts | Posts |
|
||||
| `pp-price-menu` | Price Menu | Price_Menu |
|
||||
| `pp-pricing-table` | Pricing Table | Pricing_Table |
|
||||
| `pp-promo-box` | Promo Box | Promo_Box |
|
||||
| `pp-random-image` | Random Image | Random_Image |
|
||||
| `pp-recipe` | Recipe | Recipe |
|
||||
| `pp-registration-form` | Registration Form | Registration_Form |
|
||||
| `pp-review-box` | Review Box | Review_Box |
|
||||
| `pp-scroll-image` | Scroll Image | Scroll_Image |
|
||||
| `pp-showcase` | Showcase | Showcase |
|
||||
| `pp-sitemap` | Sitemap | Sitemap |
|
||||
| `pp-table` | Table | Table |
|
||||
| `pp-tabbed-gallery` | Tabbed Gallery | Tabbed_Gallery |
|
||||
| `pp-table-of-contents` | Table of Contents | Table_Of_Contents |
|
||||
| `pp-team-member` | Team Member | Team_Member |
|
||||
| `pp-team-member-carousel` | Team Member Carousel | Team_Member_Carousel |
|
||||
| `pp-testimonials` | Testimonials | Testimonials |
|
||||
| `pp-tiled-posts` | Tiled Posts | Tiled_Posts |
|
||||
| `pp-timeline` | Timeline | Timeline |
|
||||
| `pp-toggle` | Toggle | Toggle |
|
||||
| `pp-twitter-buttons` | Twitter Buttons | Twitter_Buttons |
|
||||
| `pp-twitter-grid` | Twitter Grid | Twitter_Grid |
|
||||
| `pp-twitter-timeline` | Twitter Timeline | Twitter_Timeline |
|
||||
| `pp-twitter-tweet` | Twitter Tweet | Twitter_Tweet |
|
||||
| `pp-video` | Video | Video |
|
||||
| `pp-video-gallery` | Video Gallery | Video_Gallery |
|
||||
| `pp-wpforms` | WP Forms | WP_Forms |
|
||||
| `pp-woo-add-to-cart` | Woo — Add To Cart | Woo_Add_To_Cart |
|
||||
| `pp-woo-cart` | Woo — Cart | Woo_Cart |
|
||||
| `pp-woo-categories` | Woo — Categories | Woo_Categories |
|
||||
| `pp-woo-checkout` | Woo — Checkout | Woo_Checkout |
|
||||
| `pp-woo-mini-cart` | Woo — Mini Cart | Woo_Mini_Cart |
|
||||
| `pp-woo-offcanvas-cart` | Woo — Off Canvas Cart | Woo_Offcanvas_Cart |
|
||||
| `pp-woo-products` | Woo — Products | Woo_Products |
|
||||
| `pp-woo-my-account` | Woo — My Account | Woo_My_Account |
|
||||
| `pp-woo-product-tabs` | Woo — Product Tabs | Woo_Product_Tabs |
|
||||
| `pp-woo-product-title` | Woo — Product Title | Woo_Product_Title |
|
||||
| `pp-woo-product-meta` | Woo — Product Meta | Woo_Product_Meta |
|
||||
| `pp-woo-product-price` | Woo — Product Price | Woo_Product_Price |
|
||||
| `pp-woo-product-rating` | Woo — Product Rating | Woo_Product_Rating |
|
||||
| `pp-woo-product-stock` | Woo — Product Stock | Woo_Product_Stock |
|
||||
| `pp-woo-product-short-description` | Woo — Product Short Description | Woo_Product_Short_Description |
|
||||
| `pp-woo-product-content` | Woo — Product Content | Woo_Product_Content |
|
||||
| `pp-woo-product-images` | Woo — Product Images | Woo_Product_Images |
|
||||
| `pp-woo-product-reviews` | Woo — Product Reviews | Woo_Product_Reviews |
|
||||
| `pp-woo-product-upsell` | Woo — Product Upsell | Woo_Product_Upsell |
|
||||
| `pp-woo-add-to-cart-notification` | Woo — Add to Cart Notification | Woo_Add_To_Cart_Notification |
|
||||
| `pp-woo-archive-description` | Woo — Archive Description | Woo_Archive_Description |
|
||||
| `pp-woo-single-product` | Woo — Single Product | Woo_Single_Product |
|
||||
|
||||
## Excepções confirmadas ao nome-de-pasta óbvio
|
||||
|
||||
- `Hotspots` (pasta `modules/hotspots`) → `pp-image-hotspots`, não `pp-hotspots`.
|
||||
- `Onepage_Nav` (pasta `modules/onepage-nav`) → `pp-one-page-nav`, não `pp-onepage-nav`.
|
||||
- `Popup_Box` (pasta `modules/modal-popup`) → `pp-modal-popup`.
|
||||
- `Link_Effects` (pasta `modules/link-effects`) → **`pa-link-effects`** — único widget com prefixo `pa-` em vez de `pp-` em todo o catálogo.
|
||||
- `WP_Forms` → `pp-wpforms` (sem hífen entre "wp" e "forms").
|
||||
|
||||
Regra geral: confirmar sempre `widgetType` com `get-widget-schema({ widget_type, full: true })` antes de o usar em `add-free-widget` — este ficheiro é a fonte mais fiável disponível, mas widgets podem ser adicionados/renomeados em versões futuras do plugin.
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: rank-math
|
||||
description: Gestão programática do Rank Math SEO (Free e PRO) via WP-CLI em servidores CWP. Cobre auditoria SEO, meta em massa, schema markup, redirects, sitemaps, Instant Indexing, Analytics PRO, hooks/filtros, taxonomias WooCommerce, News/Video Sitemap, validação e rollback. Usar quando "rank math", "seo cli", "schema markup", "redirects seo", "instant indexing", "indexnow", "seo bulk", "rankmath pro".
|
||||
description: Gestão programática do Rank Math SEO (Free e PRO) via WP-CLI em servidores CWP. Cobre auditoria SEO, meta em massa, schema markup, redirects, sitemaps, Instant Indexing, Analytics PRO, hooks/filtros, taxonomias WooCommerce, News/Video Sitemap, módulos Free vs PRO completos (image-seo, local-seo, 404-monitor, llms-txt, news-sitemap, marketplace, ai-visibility), validação e rollback. Licenciamento/ligação de conta PRO → ver `/full-cliente`. Usar quando "rank math", "seo cli", "schema markup", "redirects seo", "instant indexing", "indexnow", "seo bulk", "rankmath pro", "llms.txt", "módulos rank math".
|
||||
---
|
||||
|
||||
# /rank-math — Gestão Programática Rank Math SEO via WP-CLI
|
||||
@@ -1016,6 +1016,59 @@ wp post meta get ID rank_math_robots --format=json --allow-root --path=$PATH
|
||||
|
||||
---
|
||||
|
||||
## 15. Módulos — referência completa (Free vs PRO)
|
||||
|
||||
Lista verificada ao vivo em `descomplicar.pt` (Rank Math Pro activo, licença "full services") via `wp option get rank_math_modules --format=json` e confirmada contra o filesystem (`includes/modules/` de `seo-by-rank-math` e `seo-by-rank-math-pro`), 16-08-2026.
|
||||
|
||||
```bash
|
||||
# Ver modulos activos (array INDEXADO de slugs — NAO um map slug=>bool)
|
||||
wp option get rank_math_modules --format=json --allow-root --path=$PATH
|
||||
|
||||
# Activar um modulo (wp eval — NUNCA wp option patch update aqui, a option e um array sequencial)
|
||||
wp eval '
|
||||
$modules = get_option("rank_math_modules", []);
|
||||
if (!in_array("SLUG", $modules)) { $modules[] = "SLUG"; update_option("rank_math_modules", $modules); }
|
||||
' --allow-root --path=$PATH
|
||||
|
||||
# Desactivar um modulo
|
||||
wp eval '
|
||||
$modules = get_option("rank_math_modules", []);
|
||||
$modules = array_values(array_diff($modules, ["SLUG"]));
|
||||
update_option("rank_math_modules", $modules);
|
||||
' --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
| Slug | Nome | Disponibilidade | Nota |
|
||||
|------|------|------------------|------|
|
||||
| `seo-analysis` | SEO Analysis | Free | Score SEO no editor |
|
||||
| `link-counter` (dir `links`) | Link Counter | Free | Contagem links internos/externos |
|
||||
| `sitemap` | XML Sitemap | Free | — |
|
||||
| `rich-snippet` (dir `schema`) | Schema/Rich Snippets | Free | 1 schema/pagina; PRO liberta multiplos + Schema Builder custom |
|
||||
| `redirections` | Redirections | Free (Advanced Mode) | — |
|
||||
| `404-monitor` | 404 Monitor | Free (opcao basica) / **PRO (modulo dedicado)** | Free: so `404_monitor_mode` em General, sem tabela propria. PRO: modulo com tabela `wp_rank_math_404_logs` |
|
||||
| `instant-indexing` | Instant Indexing (IndexNow) | Free | Google Indexing API adicional (via classes RM) e PRO |
|
||||
| `woocommerce` | WooCommerce SEO | Free | Requer plugin WooCommerce activo |
|
||||
| `acf` | ACF Integration | Free | Requer plugin ACF activo |
|
||||
| `analytics` | Analytics | Free (basico) / PRO (avancado) | GSC/GA; historico alargado e PRO |
|
||||
| `role-manager` | Role Manager | Free | — |
|
||||
| `buddypress` | BuddyPress Integration | Free | Requer plugin BuddyPress |
|
||||
| `bbpress` (dir `bbPress`) | bbPress Integration | Free | Requer plugin bbPress |
|
||||
| `web-stories` | Web Stories SEO | Free | Requer plugin Web Stories |
|
||||
| `ai-visibility` | AI Visibility | Free | Achado 16-08-2026 — modulo novo, monitoriza citacoes em AI Overviews/LLMs |
|
||||
| `content-ai` | Content AI | Free (limitado, requer conta ligada) / PRO (ilimitado) | Confirmado activo em `emanuelalmeida.pt` mesmo antes do Pro — depende da conta ligada, nao do plugin Pro |
|
||||
| `image-seo` | Image SEO | **PRO exclusivo** | Alt/title automatico em imagens |
|
||||
| `local-seo` | Local SEO | **PRO exclusivo** | Schema LocalBusiness multi-localizacao |
|
||||
| `llms-txt` (dir `llms`) | LLMs.txt | **PRO exclusivo** | Gera `/llms.txt` automaticamente — ver achado de sessao em §16.2 |
|
||||
| `news-sitemap` | News Sitemap | **PRO exclusivo** | — |
|
||||
| `video-sitemap` | Video Sitemap | **PRO exclusivo** | Confirmado no filesystem (`includes/modules/video-sitemap`), nao estava activo no site verificado |
|
||||
| `marketplace` | Marketplace (addons) | **PRO exclusivo** | — |
|
||||
| `link-genius` | Link Genius | **PRO exclusivo** | So existe no filesystem Pro; sem equivalente Free |
|
||||
| `podcast` | Podcast SEO | **PRO exclusivo** | So existe no filesystem Pro |
|
||||
|
||||
**Nota sobre `image-seo` e `local-seo`:** existe a pasta do modulo em AMBOS os plugins (`seo-by-rank-math/includes/modules/image-seo` e `local-seo`), mas o registo efectivo do modulo como disponivel para activacao depende da licenca PRO ligada — confirmado ao vivo: so aparecem em `rank_math_modules` em sites com Pro activo e licenciado.
|
||||
|
||||
---
|
||||
|
||||
## Sequencia de cache (sempre apos alteracoes)
|
||||
|
||||
```bash
|
||||
@@ -1081,7 +1134,8 @@ wp rankmath sitemap generate --allow-root --path=$PATH
|
||||
| Schemas multiplos/post | nao | sim |
|
||||
| Custom Schema Builder (840+ tipos) | nao | sim |
|
||||
| Redirections | sim | sim |
|
||||
| 404 Monitor | sim | sim |
|
||||
| 404 Monitor (opção básica) | sim | sim |
|
||||
| 404 Monitor (módulo dedicado, tabela própria — ver §15) | nao | sim |
|
||||
| Instant Indexing (IndexNow) | sim | sim |
|
||||
| Google Indexing API | nao | sim |
|
||||
| Analytics GSC/GA | basico | avancado |
|
||||
@@ -1126,6 +1180,53 @@ wp cache flush --allow-root --path=$PATH
|
||||
|
||||
---
|
||||
|
||||
## 16. Achados de sessão — bundle Descomplicar (16-08-2026)
|
||||
|
||||
Achados da auditoria de seguranca/infra ao bundle de 7 sites Descomplicar (`CONFIG-Plugins-Referencia.md` §7, `BUNDLE-Excelencia-WP.md`). Licenca Rank Math confirmada pelo utilizador como **"full services"** — cobre os 7 sites, nao e por assento individual.
|
||||
|
||||
### 16.1 Distribuicao real do Pro nos 7 sites
|
||||
|
||||
| Site | `seo-by-rank-math-pro` instalado | Licenca ligada (`rank_math_connect_data.connected`) | Estado |
|
||||
|------|-----------------------------------|-------------------------------------------------------|--------|
|
||||
| `descomplicar.pt` | sim | sim | Pro operacional |
|
||||
| `carstuff.pt` | sim | sim | Pro operacional |
|
||||
| `emanuelalmeida.pt` | sim | sim | Pro operacional |
|
||||
| `familyclinic.pt` | sim | sim | Pro operacional |
|
||||
| `ignitionvortex.pt` | sim | nao | Plugin instalado, **licenca por ligar** |
|
||||
| `solarfvengenharia.com` | sim | nao | Plugin instalado, **licenca por ligar** |
|
||||
| `watercontrol.pt` | sim | nao | Plugin instalado, **licenca por ligar** |
|
||||
|
||||
A ligacao de conta faz-se por OAuth no wp-admin (Rank Math → Ligar a sua conta). **Nao simular via wp-cli** copiando `rank_math_connect_data` de outro dominio — a API do Rank Math valida `site_url` no lado do servidor; copiar o valor arrisca invalidar ou confundir a licenca de origem.
|
||||
|
||||
```bash
|
||||
# Verificar ligacao de conta num site
|
||||
wp option get rank_math_connect_data --format=json --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
### 16.2 `llms-txt` como causa raiz de `/llms.txt` em falta
|
||||
|
||||
`/llms.txt` esteve em falta em `emanuelalmeida.pt` (desde 12-08-2026 pelo menos) apesar da conta Rank Math ja estar ligada. Causa raiz: o modulo `llms-txt` (gera `/llms.txt` automaticamente) e **exclusivo Pro** — o site so tinha `seo-by-rank-math` (free) instalado, sem `seo-by-rank-math-pro`. Corrigido 16-08-2026: instalado o plugin Pro + activado o modulo `llms-txt` (nao vem activo por omissao mesmo com Pro) + verificado `/llms.txt` → HTTP 200 ao vivo, em `emanuelalmeida.pt` e `familyclinic.pt`.
|
||||
|
||||
```bash
|
||||
# Diagnosticar /llms.txt em falta
|
||||
wp option get rank_math_modules --format=json --allow-root --path=$PATH | grep -q llms-txt && echo "modulo activo" || echo "modulo AUSENTE — instalar Pro + activar"
|
||||
|
||||
# Activar o modulo depois do Pro estar instalado e licenciado
|
||||
wp eval '
|
||||
$modules = get_option("rank_math_modules", []);
|
||||
if (!in_array("llms-txt", $modules)) { $modules[] = "llms-txt"; update_option("rank_math_modules", $modules); }
|
||||
' --allow-root --path=$PATH
|
||||
|
||||
# Verificar ao vivo
|
||||
curl -sI "https://SITE.pt/llms.txt" | head -1
|
||||
```
|
||||
|
||||
### 16.3 Licencas — usar `/full-cliente`, nao duplicar aqui
|
||||
|
||||
A gestao de licenca/ligacao de conta Rank Math Pro faz parte do broker de licencas **FULL.Cliente** (`api.full.services`), que suporta `rankMath` como product key numa chamada unica (sem steps de OTP, ao contrario de `essentialAddons`). Para ligar/reactivar a licenca Rank Math Pro em qualquer site do bundle, usar a skill `/full-cliente` em vez de replicar aqui os comandos do broker — esta skill (`/rank-math`) fica focada em WP-CLI/dados do plugin ja licenciado.
|
||||
|
||||
---
|
||||
|
||||
## Recursos
|
||||
|
||||
### Referencias
|
||||
@@ -1140,9 +1241,9 @@ wp cache flush --allow-root --path=$PATH
|
||||
- **Pesquisa Gemini:** `Hub/06-Operacoes/Documentacao/Manuais/WP-CLI/Rank-Math-SEO-WP-CLI-Skills-Pesquisa-Gemini.md`
|
||||
- **NotebookLM:** [WordPress Config CLI](https://notebooklm.google.com/notebook/fb2f26bd-8cb0-4d4c-bafc-4f1ebb51c51d) (4 fontes)
|
||||
|
||||
---
|
||||
**Fonte:** manual completo `Rank-Math-WP-CLI-Manual-Definitivo.md` (17 seccoes, lido na integra), codigo-fonte `includes/modules/` de `seo-by-rank-math` e `seo-by-rank-math-pro` lido ao vivo via SSH em `descomplicar.pt`, `wp option get rank_math_modules` verificado em produção, achados da auditoria de seguranca/infra 16-08-2026 (`CONFIG-Plugins-Referencia.md` §7, `BUNDLE-Excelencia-WP.md`).
|
||||
|
||||
*Rank Math SEO via WP-CLI | Descomplicar | v2.0.0 | 29-03-2026*
|
||||
*Rank Math SEO via WP-CLI | Descomplicar | v2.1.0 | 16-08-2026*
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -137,28 +137,52 @@ wp option pluck rank-math-options-sitemap pt_attachment_sitemap # on/off (defau
|
||||
|
||||
## Módulos Rank Math
|
||||
|
||||
`rank_math_modules` e um **array indexado de slugs activos** (nao um map `slug=>bool`). Lista completa verificada ao vivo em `descomplicar.pt` (Pro) + filesystem — ver `SKILL.md` §15 para a tabela completa Free vs PRO.
|
||||
|
||||
```bash
|
||||
# Ver todos os módulos
|
||||
# Ver todos os módulos activos
|
||||
wp option get rank_math_modules --format=json --allow-root
|
||||
|
||||
# Activar módulo
|
||||
wp option patch update rank_math_modules MODULE_NAME "1" --allow-root
|
||||
# Activar módulo (wp eval — wp option patch NAO funciona aqui, nao ha chave por slug)
|
||||
wp eval '
|
||||
$modules = get_option("rank_math_modules", []);
|
||||
if (!in_array("MODULE_SLUG", $modules)) { $modules[] = "MODULE_SLUG"; update_option("rank_math_modules", $modules); }
|
||||
' --allow-root
|
||||
|
||||
# Desactivar módulo
|
||||
wp option patch update rank_math_modules MODULE_NAME "0" --allow-root
|
||||
wp eval '
|
||||
$modules = get_option("rank_math_modules", []);
|
||||
$modules = array_values(array_diff($modules, ["MODULE_SLUG"]));
|
||||
update_option("rank_math_modules", $modules);
|
||||
' --allow-root
|
||||
```
|
||||
|
||||
| Módulo | Slug | Função |
|
||||
|--------|------|--------|
|
||||
| SEO Analysis | `seo-analysis` | Score SEO no editor |
|
||||
| Link Counter | `link-counter` | Contagem links internos/externos |
|
||||
| Redirections | `redirections` | Sistema de redirects |
|
||||
| 404 Monitor | `404-monitor` | Log de 404s |
|
||||
| Schema | `rich-snippet` | Schema markup |
|
||||
| Sitemap | `sitemap` | XML Sitemap |
|
||||
| Instant Indexing | `instant-indexing` | Google Indexing API (PRO) |
|
||||
| Local SEO | `local-seo` | Schema LocalBusiness |
|
||||
| WooCommerce | `woocommerce` | SEO WooCommerce |
|
||||
| Módulo | Slug | Função | Tier |
|
||||
|--------|------|--------|------|
|
||||
| SEO Analysis | `seo-analysis` | Score SEO no editor | Free |
|
||||
| Link Counter | `link-counter` | Contagem links internos/externos | Free |
|
||||
| Redirections | `redirections` | Sistema de redirects | Free |
|
||||
| 404 Monitor (dedicado, tabela própria) | `404-monitor` | Log de 404s | Free (opção básica) / PRO (módulo completo) |
|
||||
| Schema | `rich-snippet` | Schema markup | Free (1/página) / PRO (ilimitado + Builder) |
|
||||
| Sitemap | `sitemap` | XML Sitemap | Free |
|
||||
| Instant Indexing | `instant-indexing` | IndexNow; Google Indexing API é PRO | Free |
|
||||
| WooCommerce | `woocommerce` | SEO WooCommerce | Free |
|
||||
| ACF | `acf` | Integração Advanced Custom Fields | Free |
|
||||
| Analytics | `analytics` | GSC/GA no wp-admin | Free (básico) / PRO (avançado) |
|
||||
| Role Manager | `role-manager` | Capabilities por role | Free |
|
||||
| BuddyPress | `buddypress` | Integração BuddyPress | Free |
|
||||
| bbPress | `bbpress` | Integração bbPress | Free |
|
||||
| Web Stories | `web-stories` | SEO para Web Stories | Free |
|
||||
| AI Visibility | `ai-visibility` | Monitoriza citações em AI Overviews/LLMs (achado 16-08-2026) | Free |
|
||||
| Content AI | `content-ai` | Assistente de conteúdo (requer conta ligada) | Free (limitado) / PRO (ilimitado) |
|
||||
| Image SEO | `image-seo` | Alt/title automático em imagens | **PRO exclusivo** |
|
||||
| Local SEO | `local-seo` | Schema LocalBusiness multi-localização | **PRO exclusivo** |
|
||||
| LLMs.txt | `llms-txt` | Gera `/llms.txt` automaticamente | **PRO exclusivo** |
|
||||
| News Sitemap | `news-sitemap` | Sitemap Google News | **PRO exclusivo** |
|
||||
| Video Sitemap | `video-sitemap` | Sitemap de vídeos | **PRO exclusivo** |
|
||||
| Marketplace | `marketplace` | Addons Rank Math | **PRO exclusivo** |
|
||||
| Link Genius | `link-genius` | Sugestões de link interno automáticas | **PRO exclusivo** |
|
||||
| Podcast | `podcast` | SEO para podcasts | **PRO exclusivo** |
|
||||
|
||||
---
|
||||
|
||||
@@ -367,13 +391,20 @@ wp db query "SELECT id, sources, url_to, header_code FROM wp_rank_math_redirecti
|
||||
| `wp rankmath sitemap generate` | ✅ | ✅ | Único comando nativo |
|
||||
| Meta por post | ✅ | ✅ | `wp post meta` |
|
||||
| Options globais | ✅ | ✅ | `wp option patch` |
|
||||
| Schema markup | ✅ | ✅ | `wp eval` |
|
||||
| Schema markup | ✅ (1/página) | ✅ (ilimitado + Schema Builder) | `wp eval` |
|
||||
| Redirections | ✅ | ✅ | `\RankMath\Redirections\DB` |
|
||||
| 404 Monitor | ✅ | ✅ | `wp_rank_math_404_logs` |
|
||||
| Instant Indexing | ❌ | ✅ | `\RankMath\Instant_Indexing\Api` |
|
||||
| Analytics GSC | ❌ | ✅ | Tabelas analytics_gsc |
|
||||
| Analytics GA | ❌ | ✅ | Tabelas analytics_ga |
|
||||
| 404 Monitor (opção básica, `404_monitor_mode`) | ✅ | ✅ | Sem tabela própria em Free |
|
||||
| 404 Monitor (módulo dedicado, `wp_rank_math_404_logs`) | ❌ | ✅ | Verificado ao vivo 16-08-2026 — só existe com Pro licenciado |
|
||||
| Instant Indexing — IndexNow | ✅ | ✅ | Módulo `instant-indexing`, ambos free e PRO |
|
||||
| Instant Indexing — Google Indexing API | ❌ | ✅ | `\RankMath\Instant_Indexing\Api` |
|
||||
| Analytics (básico, wp-admin) | ✅ | ✅ | Módulo `analytics` presente em ambos |
|
||||
| Analytics GSC/GA (histórico alargado) | ❌ | ✅ | Tabelas `analytics_gsc`/`analytics_ga` |
|
||||
| Image SEO | ❌ | ✅ | Módulo `image-seo` — confirmado PRO exclusivo |
|
||||
| Local SEO | ❌ | ✅ | Módulo `local-seo` — confirmado PRO exclusivo |
|
||||
| LLMs.txt (`/llms.txt` automático) | ❌ | ✅ | Módulo `llms-txt` — confirmado PRO exclusivo (achado 16-08-2026) |
|
||||
| News/Video Sitemap | ❌ | ✅ | Módulos `news-sitemap`/`video-sitemap` |
|
||||
| Marketplace / Link Genius / Podcast | ❌ | ✅ | Só existem no filesystem `seo-by-rank-math-pro` |
|
||||
|
||||
---
|
||||
|
||||
*Referência Rank Math WP-CLI | Descomplicar® | v1.0.0 | 18-02-2026*
|
||||
*Referência Rank Math WP-CLI | Descomplicar® | v1.1.0 | 16-08-2026*
|
||||
|
||||
@@ -0,0 +1,460 @@
|
||||
---
|
||||
name: redis-object-cache
|
||||
description: Gestão e diagnóstico do plugin Redis Object Cache (redis-cache, Till Krüss) via WP-CLI em servidores CWP. Cobre estado da ligação (wp redis status), drop-in object-cache.php, isolamento por site via WP_REDIS_DATABASE/WP_REDIS_PREFIX no bundle partilhado, PING/PONG, flush pós-SQL directo, e diferença entre object cache e page cache (WP Fastest Cache/WP Meteor). Usar quando "redis object cache", "redis-cache", "wp redis status", "object cache", "isolamento redis", "colisão de base redis", "WP_REDIS_DATABASE", "cache não invalida", "predis vs phpredis".
|
||||
---
|
||||
|
||||
# /redis-object-cache — Gestão e Diagnóstico Redis Object Cache
|
||||
|
||||
Plugin `redis-cache` (Till Krüss), versão `2.8.0` confirmada em produção.
|
||||
Object cache persistente — cache de objectos/queries WordPress, **não** é
|
||||
page cache (ver secção "Object cache vs page cache" abaixo).
|
||||
|
||||
**Fonte:** `CONFIG-Plugins-Referencia.md` secção 6 (Redis Object Cache,
|
||||
mapeado 16-08-2026) + verificação SSH ao vivo desta sessão (16-08-2026) em
|
||||
`emanuelalmeida.pt` e nos 7 sites do bundle + expansão de cobertura
|
||||
(16-08-2026) por leitura integral do código-fonte do plugin
|
||||
(`includes/object-cache.php`, `includes/class-plugin.php`,
|
||||
`includes/class-predis.php`, `includes/class-metrics.php`,
|
||||
`includes/diagnostics.php`, `includes/cli/class-commands.php`,
|
||||
`wp-includes/load.php` do core) — mapeamento exaustivo de todas as
|
||||
constantes `WP_REDIS_*`, subcomandos WP-CLI, hooks e semântica de grupos,
|
||||
não apenas o subconjunto tocado na auditoria pontual original.
|
||||
|
||||
---
|
||||
|
||||
## Contexto CWP — sempre obrigatório
|
||||
|
||||
```bash
|
||||
# Via SSH directo (mais rápido para wp redis, comando nativo)
|
||||
ssh server "sudo -u USER /usr/local/bin/wp redis status --path=/home/USER/SITE_PATH"
|
||||
|
||||
# Formato CWP completo (PHP versionado)
|
||||
sudo -u USER /opt/alt/php-fpm82/usr/bin/php /usr/local/bin/wp redis status \
|
||||
--allow-root --path=/home/USER/public_html
|
||||
```
|
||||
|
||||
```
|
||||
servidor: server.descomplicar.pt | porta: 9443 | user: root
|
||||
```
|
||||
|
||||
**Único comando nativo do plugin:** `wp redis <subcomando>`. Confirmado ao
|
||||
vivo (`wp redis --help --path=$PATH`):
|
||||
|
||||
| Subcomando | Faz |
|
||||
|---|---|
|
||||
| `wp redis status` | Mostra ligação, client, host/porta/DB/prefixo, grupos, drop-in |
|
||||
| `wp redis enable` | Activa a cache (escreve o drop-in `object-cache.php`) |
|
||||
| `wp redis disable` | Desactiva a cache (remove o drop-in) |
|
||||
| `wp redis update-dropin` | Actualiza o drop-in para a versão do plugin instalado |
|
||||
|
||||
**Gotcha real confirmado nesta sessão:** `wp redis flush` **não existe**.
|
||||
A própria ajuda do comando diz: *"To flush call `wp cache flush`"*. Usar
|
||||
sempre o comando genérico do WP-CLI (`wp cache flush`), que funciona porque
|
||||
o drop-in `object-cache.php` está activo e intercepta o wrapper nativo.
|
||||
|
||||
**Reconfirmado nesta expansão (16-08-2026):** `wp help redis --path=$PATH`
|
||||
ao vivo devolve exactamente os mesmos 4 subcomandos. O código-fonte
|
||||
(`includes/cli/class-commands.php`, classe `Commands extends WP_CLI_Command`)
|
||||
só define 4 métodos públicos — `status()`, `enable()`, `disable()`,
|
||||
`update_dropin()` (mapeado para `update-dropin` via `@subcommand`) — pelo que
|
||||
esta lista é exaustiva, não apenas a amostra testada. Não existe `wp redis
|
||||
flush` nem `wp redis info` nesta versão (2.8.0).
|
||||
|
||||
---
|
||||
|
||||
## 1. Diagnóstico rápido — `wp redis status`
|
||||
|
||||
```bash
|
||||
PATH=/home/USER/SITE_PATH
|
||||
wp redis status --path=$PATH
|
||||
```
|
||||
|
||||
Output real (`emanuelalmeida.pt`, DB 12):
|
||||
|
||||
```
|
||||
Status: Ligado
|
||||
Client: Predis (v2.4.0)
|
||||
Drop-in: Valid
|
||||
Disabled: No
|
||||
Ping: PONG
|
||||
Errors: []
|
||||
PhpRedis: Not loaded
|
||||
Relay: Not loaded
|
||||
Predis: 2.4.0
|
||||
PHP Version: 8.2.31
|
||||
Plugin Version: 2.8.0
|
||||
Redis Version: 5.0.3
|
||||
WP_REDIS_HOST: "127.0.0.1"
|
||||
WP_REDIS_PORT: 6379
|
||||
WP_REDIS_DATABASE: 12
|
||||
WP_REDIS_PREFIX: "emanuelalmeida_pt_"
|
||||
WP_CACHE_KEY_SALT: "..."
|
||||
Timeout: 1
|
||||
Read Timeout: 1
|
||||
Global Groups: [...24 grupos: blog-details, users, site-transient, ...]
|
||||
Ignored Groups: ["counts", "plugins", "theme_json", "WPForms_Entry_Handler", "themes"]
|
||||
Drop-ins: ["Redis Object Cache Drop-In v2.8.0 by Till Krüss"]
|
||||
```
|
||||
|
||||
| Campo a verificar | Valor esperado | Se falhar |
|
||||
|---|---|---|
|
||||
| `Status` | `Ligado` | `Não ligado` → drop-in ausente ou desactivado, correr `wp redis enable` |
|
||||
| `Ping` | `PONG` | Qualquer outra coisa → Redis não responde na porta 6379, verificar serviço `redis-server` no host |
|
||||
| `Drop-in` | `Valid` | `Invalid`/`Outdated` → correr `wp redis update-dropin` |
|
||||
| `Client` | `Predis 2.4.0` | Confirmado — `PhpRedis`/`Relay` **não instalados** no servidor (extensão PHP nativa ausente); Predis é fallback 100% funcional em PHP puro, apenas mais lento. Não é erro, é a configuração real e estável do servidor |
|
||||
| `WP_REDIS_DATABASE` | número único por site | Ver secção "Isolamento entre sites" |
|
||||
|
||||
Ler `object-cache.php` como drop-in activo (não apenas plugin) é o
|
||||
diferencial: `wp plugin is-active redis-cache` só confirma que o plugin
|
||||
está ligado, **não** confirma que o drop-in está a interceptar as chamadas
|
||||
de cache. `wp redis status` é a única fonte fiável de estado real.
|
||||
|
||||
---
|
||||
|
||||
## 2. Isolamento entre sites do bundle — verificação de integridade
|
||||
|
||||
Todos os sites do bundle Descomplicar® partilham a **mesma instância Redis**
|
||||
(`127.0.0.1:6379`, um único servidor Redis no host). O isolamento é feito por
|
||||
duas camadas independentes — `WP_REDIS_DATABASE` (índice de base lógica
|
||||
Redis, 0-15 por omissão) **e** `WP_REDIS_PREFIX` (prefixo de chave) — para
|
||||
que uma colisão numa camada não cause colisão real de dados.
|
||||
|
||||
### Comando repetível — listar DB de todos os sites e confirmar zero colisão
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Corre no servidor (via ssh server "...") ou local com ssh -p 9443 root@server.descomplicar.pt
|
||||
declare -A SITES=(
|
||||
[descomplicar.pt]="ealmeida:/home/ealmeida/public_html"
|
||||
[emanuelalmeida.pt]="ealmeida:/home/ealmeida/emanuelalmeida.pt"
|
||||
[carstuff.pt]="carstuff:/home/carstuff/public_html"
|
||||
[familyclinic.pt]="familycl:/home/familycl/public_html"
|
||||
[ignitionvortex.pt]="ignition:/home/ignition/public_html"
|
||||
[solarfvengenharia.com]="solarfv:/home/solarfv/public_html"
|
||||
[watercontrol.pt]="wtc:/home/wtc/public_html"
|
||||
)
|
||||
|
||||
DBS=""
|
||||
for site in "${!SITES[@]}"; do
|
||||
user="${SITES[$site]%%:*}"; path="${SITES[$site]#*:}"
|
||||
active=$(sudo -u "$user" /usr/local/bin/wp plugin is-active redis-cache --path="$path" 2>/dev/null && echo ACTIVE || echo INACTIVE)
|
||||
db=$(sudo -u "$user" /usr/local/bin/wp config get WP_REDIS_DATABASE --path="$path" 2>/dev/null)
|
||||
prefix=$(sudo -u "$user" /usr/local/bin/wp config get WP_REDIS_PREFIX --path="$path" 2>/dev/null)
|
||||
printf "%-24s %-9s DB=%-3s prefix=%s\n" "$site" "$active" "$db" "$prefix"
|
||||
[ "$active" = "ACTIVE" ] && DBS="$DBS $db"
|
||||
done
|
||||
echo "--- DBs activas: $DBS"
|
||||
echo "--- duplicados:"; echo $DBS | tr ' ' '\n' | sort | uniq -d
|
||||
```
|
||||
|
||||
**Resultado real desta sessão (16-08-2026):**
|
||||
|
||||
| Site | Plugin | `WP_REDIS_DATABASE` | `WP_REDIS_PREFIX` |
|
||||
|---|---|---|---|
|
||||
| descomplicar.pt | **inactive** | `0` (default, não usado) | — |
|
||||
| emanuelalmeida.pt | active | `12` | `emanuelalmeida_pt_` |
|
||||
| carstuff.pt | active | `1` | `carstuff_` |
|
||||
| familyclinic.pt | active | `3` | `familycl_` |
|
||||
| ignitionvortex.pt | active | `4` | `ignition_` |
|
||||
| solarfvengenharia.com | active | `6` | `solarfv_` |
|
||||
| watercontrol.pt | active | `7` | `wtc_` |
|
||||
|
||||
**Zero colisões** — DBs activas `{1, 3, 4, 6, 7, 12}` são todas distintas, e
|
||||
mesmo que duas colidissem, o `WP_REDIS_PREFIX` distinto por site seria a
|
||||
segunda barreira. `descomplicar.pt` (site principal Descomplicar®) tem o
|
||||
plugin **instalado mas inactivo** — não usa object cache Redis; confirmar
|
||||
antes de assumir que está coberto pelo bundle.
|
||||
|
||||
**Gotcha:** a linha `echo $DBS | tr ' ' '\n' | sort | uniq -d` fica vazia
|
||||
quando não há duplicados — silêncio = sucesso. Um output não-vazio ali é
|
||||
alarme real de colisão de DB entre dois sites do bundle.
|
||||
|
||||
---
|
||||
|
||||
## 3. Object cache vs page cache — não conflitam, são camadas diferentes
|
||||
|
||||
| Camada | Plugin | O que guarda | Onde vive |
|
||||
|---|---|---|---|
|
||||
| **Object cache** | Redis Object Cache (este) | Resultados de queries SQL, `wp_options` autoload, transients, meta — substitui o cache-in-memory por pedido do WordPress (`WP_Object_Cache`) por um persistente entre pedidos | Redis (`127.0.0.1:6379`) |
|
||||
| **Page cache** | WP Fastest Cache / WP Meteor | HTML final já renderizado de uma página, servido antes do WordPress arrancar | Ficheiros estáticos em disco (`wp-content/cache/`) |
|
||||
|
||||
São independentes e **complementares**: o page cache evita mesmo carregar o
|
||||
WordPress; quando falha um cache de página (visitante logado, POST,
|
||||
página não cacheável) é o object cache Redis que absorve o custo das
|
||||
queries repetidas. Não há necessidade de coordenar TTLs ou invalidação
|
||||
entre os dois — cada um limpa-se pelo seu próprio mecanismo (`wp cache
|
||||
flush` para Redis; purga própria do WP Fastest Cache/WP Meteor para HTML).
|
||||
|
||||
---
|
||||
|
||||
## 4. Gotcha crítico — SQL directo não invalida o Redis
|
||||
|
||||
**Mesma nota da skill `/rank-math`:** qualquer alteração feita via `wp db
|
||||
query` (UPDATE/DELETE directo em `wp_options`, `wp_postmeta`, etc.) **não
|
||||
passa pelas funções WordPress** (`update_option()`, `update_post_meta()`)
|
||||
que disparam a invalidação de cache. Com o object cache Redis activo, os
|
||||
dados antigos continuam servidos da cache até expirarem ou até um flush
|
||||
explícito — o que pode demorar minutos a horas dependendo do grupo.
|
||||
|
||||
**Regra:** SEMPRE `wp cache flush --path=$PATH` imediatamente a seguir a
|
||||
qualquer `wp db query` de escrita, antes de validar o resultado no site.
|
||||
|
||||
```bash
|
||||
wp db query "UPDATE ${PREFIX}options SET option_value='...' WHERE option_name='...';" --path=$PATH
|
||||
wp cache flush --path=$PATH # OBRIGATÓRIO — sem isto o Redis serve dados stale
|
||||
```
|
||||
|
||||
Sem este passo, uma auditoria/correcção pode parecer ter falhado (o browser
|
||||
mostra o valor antigo) quando na verdade a escrita na BD foi bem-sucedida —
|
||||
é só a camada de cache que ainda não sabe.
|
||||
|
||||
---
|
||||
|
||||
## 5. Grupos ignorados por omissão
|
||||
|
||||
Confirmado via `wp redis status`:
|
||||
|
||||
```
|
||||
Ignored Groups: ["counts", "plugins", "theme_json", "WPForms_Entry_Handler", "themes"]
|
||||
```
|
||||
|
||||
Estes grupos ficam **fora** do Redis mesmo com o object cache activo —
|
||||
mudam com frequência ou têm de reflectir estado imediato (contagem de
|
||||
comentários, lista de plugins/temas). É a configuração por omissão do
|
||||
plugin, correcta para não introduzir dados desactualizados nestes pontos.
|
||||
Os restantes 24 grupos (`users`, `site-transient`, `usermeta`,
|
||||
`redis-cache`, etc.) são cacheados normalmente — ver output completo de
|
||||
`wp redis status` para a lista exaustiva por site.
|
||||
|
||||
---
|
||||
|
||||
## 6. Constantes completas suportadas (`WP_REDIS_*`)
|
||||
|
||||
Levantamento exaustivo por leitura integral de
|
||||
`includes/object-cache.php` (drop-in, 3066 linhas), `includes/class-plugin.php`
|
||||
(1685 linhas), `includes/class-predis.php`, `includes/class-metrics.php` e
|
||||
`includes/diagnostics.php` — não apenas as 5 constantes usadas no bundle
|
||||
Descomplicar®. Todas por definir em `wp-config.php` **antes** do WordPress
|
||||
arrancar (mesmo princípio do `WP_REDIS_DATABASE`/`WP_REDIS_PREFIX` já usado).
|
||||
|
||||
### Ligação básica
|
||||
|
||||
| Constante | Default | Descrição |
|
||||
|---|---|---|
|
||||
| `WP_REDIS_HOST` | `127.0.0.1` | Host do servidor Redis |
|
||||
| `WP_REDIS_PORT` | `6379` | Porta TCP |
|
||||
| `WP_REDIS_PATH` | — | Caminho do socket Unix; só usado quando `WP_REDIS_SCHEME=unix` (nesse caso `host`/`port` são descartados) |
|
||||
| `WP_REDIS_SCHEME` | `tcp` | `tcp` / `unix` / `tls` (`rediss`) |
|
||||
| `WP_REDIS_DATABASE` | `0` | Índice da base lógica Redis (0-15 por omissão) — usado no isolamento entre sites (secção 2) |
|
||||
| `WP_REDIS_PASSWORD` | — | String (só password) ou array `[username, password]` para ACL Redis 6+. Mascarado como `••••••••` em `wp redis status`/diagnostics |
|
||||
| `WP_REDIS_USERNAME` | — | Username ACL explícito; sobrepõe-se ao `[0]` de `WP_REDIS_PASSWORD` quando ambos definidos (só cliente Predis) |
|
||||
| `WP_REDIS_TIMEOUT` | `1` | Timeout de ligação, em segundos |
|
||||
| `WP_REDIS_READ_TIMEOUT` | `1` | Timeout de leitura, em segundos |
|
||||
| `WP_REDIS_RETRY_INTERVAL` | `null` | Intervalo entre tentativas de reconexão, em ms |
|
||||
| `WP_REDIS_SSL_CONTEXT` | — | Array de opções de stream context PHP para TLS, ex. `['verify_peer' => false]` |
|
||||
| `WP_REDIS_CLIENT` | auto (`phpredis` se a extensão existir, senão `predis`) | `phpredis` / `pecl` (alias de `phpredis`) / `relay` / `credis` / `predis` — força o cliente |
|
||||
| `WP_REDIS_IGBINARY` | `false` | bool — usa serialização `igbinary` se a extensão `igbinary` estiver carregada |
|
||||
|
||||
**Mecanismo:** `build_parameters()` em `object-cache.php` itera um array fixo
|
||||
de settings (`scheme, host, port, path, password, database, timeout,
|
||||
read_timeout, retry_interval`) e resolve cada um via
|
||||
`sprintf('WP_REDIS_%s', strtoupper($setting))` — é assim, literalmente, que
|
||||
o nome de cada constante é gerado a partir do parâmetro Redis correspondente.
|
||||
|
||||
### Alta disponibilidade / escala
|
||||
|
||||
| Constante | Descrição |
|
||||
|---|---|
|
||||
| `WP_REDIS_CLUSTER` | Array de DSNs (ou string = id de ligação nomeada) — activa modo Redis Cluster |
|
||||
| `WP_REDIS_SHARDS` | Array de servidores — sharding client-side via `RedisArray` (só cliente `phpredis`) |
|
||||
| `WP_REDIS_SENTINEL` | Nome do serviço Sentinel — requer `WP_REDIS_SERVERS` com os hosts dos sentinels |
|
||||
| `WP_REDIS_SERVERS` | Array de servidores — replicação Predis (`options['replication']='predis'`) ou lista de sentinels quando `WP_REDIS_SENTINEL` também está definida |
|
||||
|
||||
Nenhuma destas está em uso no bundle Descomplicar® (todos os sites usam uma
|
||||
única instância Redis local, sem cluster/replicação) — documentado aqui por
|
||||
cobertura completa do plugin, não por uso confirmado em produção.
|
||||
|
||||
### Comportamento da cache
|
||||
|
||||
| Constante | Default | Descrição |
|
||||
|---|---|---|
|
||||
| `WP_REDIS_PREFIX` | — | Prefixo de chave (isolamento, ver secção 2); herda de `WP_CACHE_KEY_SALT` se esta estiver definida e `WP_REDIS_PREFIX` não estiver; em Cloudways é preenchido automaticamente a partir de `HTTP_X_APP_USER` |
|
||||
| `WP_REDIS_SELECTIVE_FLUSH` | `false` | bool — `wp cache flush`/`flush()` só apaga chaves com o prefixo (script Lua via `SCAN`+`DEL`) em vez de `FLUSHDB` total à base lógica inteira |
|
||||
| `WP_REDIS_GLOBAL_GROUPS` | 17 grupos por omissão (ver secção 9) | array — **substitui** (não soma) a lista de grupos partilhados entre sites de uma rede multisite |
|
||||
| `WP_REDIS_IGNORED_GROUPS` | `[]` (vazio no plugin) | array — **substitui** a lista de grupos que nunca são persistidos no Redis |
|
||||
| `WP_REDIS_UNFLUSHABLE_GROUPS` | `[]` (vazio) | array — **substitui** a lista de grupos que continuam em cache mas sobrevivem a um `flush()` |
|
||||
| `WP_REDIS_MAXTTL` | — | int (segundos) — tecto aplicado a QUALQUER TTL, incluindo entradas "para sempre" (`expire=0`); `validate_expiration()` força o valor para o máximo sempre que `expiration === 0 \|\| expiration > max` |
|
||||
| `WP_REDIS_FLUSH_TIMEOUT` | `5` | int (segundos) — timeout de socket aplicado só durante o flush selectivo/scripts Lua (`execute_lua_script()`) |
|
||||
| `WP_REDIS_DISABLE_GROUP_FLUSH` | `false` | bool — `flush_group()` deixa de ser selectivo e cai num `flush()` total à base |
|
||||
| `WP_REDIS_GRACEFUL` | `false` | bool — falha silenciosamente (sem excepção fatal) se o Redis estiver inacessível na ligação inicial |
|
||||
| `WP_REDIS_DISABLED` | `false` | bool — desliga TODO o drop-in (nenhuma função `wp_cache_*` chega a ser definida, pois envolve o ficheiro inteiro num `if`); ver nuance de segurança na secção "Erros comuns" |
|
||||
|
||||
### Admin / UI / segurança
|
||||
|
||||
| Constante | Default | Descrição |
|
||||
|---|---|---|
|
||||
| `WP_REDIS_DISABLE_BANNERS` | `false` | bool — esconde todos os banners de upsell "Object Cache Pro" (dashboard, JS admin `disable_pro`, aviso WooCommerce) |
|
||||
| `WP_REDIS_DISABLE_DROPIN_BANNERS` | `false` | bool — esconde só os avisos "drop-in em falta/desactualizado" no admin |
|
||||
| `WP_REDIS_DISABLE_ADMINBAR` | `false` | bool — remove o nó "Object Cache" da barra de admin |
|
||||
| `WP_REDIS_DISABLE_COMMENT` | `false` | bool — suprime o comentário HTML de rodapé "Performance optimized by Redis Object Cache" (hook `shutdown`) |
|
||||
| `WP_REDIS_MANAGER_CAPABILITY` | `manage_options` (`manage_network_options` em multisite) | string — sobrepõe-se à capability necessária para gerir o plugin (menu, acções, admin bar); passa também pelo filtro `redis_cache_manager_capability` |
|
||||
| `WP_REDIS_DISABLE_DROPIN_CHECK` | `false` | bool — salta o teste completo de escrita (copiar/verificar versão/apagar ficheiro `object-cache.tmp`), só confirma existência+permissão de escrita do drop-in já instalado |
|
||||
| `WP_REDIS_DISABLE_DROPIN_AUTOUPDATE` | `false` | bool — desliga a auto-actualização do drop-in em `admin_init` quando a versão instalada do plugin muda |
|
||||
|
||||
### Métricas
|
||||
|
||||
| Constante | Default | Descrição |
|
||||
|---|---|---|
|
||||
| `WP_REDIS_DISABLE_METRICS` | `false` | bool — desliga completamente a recolha de métricas (esconde tab "Metrics", widget de dashboard, secção da admin bar) |
|
||||
| `WP_REDIS_METRICS_MAX_TIME` | `3600` (`HOUR_IN_SECONDS`) | int (segundos) — janela de retenção/visualização das métricas; usado tanto para o gráfico como para a purga via cron `rediscache_discard_metrics` |
|
||||
|
||||
### Caminho do plugin
|
||||
|
||||
| Constante | Descrição |
|
||||
|---|---|
|
||||
| `WP_REDIS_PLUGIN_PATH` | Só tem efeito se definida **antes** do ficheiro principal do plugin carregar (`if (!defined('WP_REDIS_PLUGIN_PATH')) define(...)`) — é o mecanismo que o bundle partilhado Descomplicar® usa para apontar o drop-in de cada site para a cópia partilhada do plugin em vez de `wp-content/plugins/redis-cache` local |
|
||||
|
||||
---
|
||||
|
||||
## 7. Grupos de cache — semântica exacta dos 3 tipos
|
||||
|
||||
O construtor de `WP_Object_Cache` (`object-cache.php` linhas ~508-529) usa
|
||||
três arrays distintos, cada um com comportamento próprio:
|
||||
|
||||
| Tipo | Efeito | Constante de override | Lista por omissão do plugin |
|
||||
|---|---|---|---|
|
||||
| `global_groups` | Partilhado entre todos os sites de uma rede multisite (não leva `blog_prefix`) | `WP_REDIS_GLOBAL_GROUPS` (substitui) | 17 grupos: `blog-details, blog-id-cache, blog-lookup, global-posts, networks, rss, sites, site-details, site-lookup, site-options, site-transient, users, useremail, userlogins, usermeta, user_meta, userslugs` (+ `redis-cache` sempre adicionado) |
|
||||
| `ignored_groups` | Nunca chega a ir para o Redis — fica só em memória do pedido actual | `WP_REDIS_IGNORED_GROUPS` (substitui) | **`[]` vazio no próprio plugin** |
|
||||
| `unflushable_groups` | Fica em cache normalmente, mas sobrevive a um `flush()`/`wp cache flush` | `WP_REDIS_UNFLUSHABLE_GROUPS` (substitui) | `[]` vazio |
|
||||
|
||||
**Correcção/precisão sobre a secção 5 acima:** os 5 "grupos ignorados por
|
||||
omissão" vistos em `wp redis status`
|
||||
(`counts, plugins, theme_json, WPForms_Entry_Handler, themes`) **não são
|
||||
configuração do plugin `redis-cache`** — o array `$ignored_groups` do
|
||||
próprio plugin nasce vazio. São chamadas em runtime à função wrapper
|
||||
`wp_cache_add_non_persistent_groups()` (que faz `array_merge`, não
|
||||
substitui) feitas por:
|
||||
- **WordPress core**, em `wp-includes/load.php::wp_start_object_cache()`
|
||||
(confirmado ao vivo nesta expansão): `wp_cache_add_non_persistent_groups(
|
||||
['counts', 'plugins', 'theme_json'] )`, logo a seguir a carregar o drop-in;
|
||||
- **WordPress core**, em `wp-includes/class-wp-theme.php:264`:
|
||||
`wp_cache_add_non_persistent_groups( 'themes' )`;
|
||||
- **Plugin WPForms** (`WPForms_Entry_Handler`), específico deste site — noutro
|
||||
site sem WPForms este grupo não aparece.
|
||||
|
||||
Ou seja: a lista de grupos ignorados varia por site consoante os plugins
|
||||
activos, não é fixa do `redis-cache`. Da mesma forma, o WordPress core
|
||||
regista o seu próprio conjunto (mais amplo, 22 grupos incluindo
|
||||
`blog_meta`, `image_editor`, `network-queries`, `site-queries`,
|
||||
`theme_files`, `translation_files`, `user-queries`) via
|
||||
`wp_cache_add_global_groups()` no mesmo `wp_start_object_cache()`, que se
|
||||
soma (`array_unique(array_merge(...))`) aos 17 do plugin.
|
||||
|
||||
---
|
||||
|
||||
## 8. Arquitectura — zero `wp_options`, tudo por constante
|
||||
|
||||
Confirmado ao vivo nesta expansão:
|
||||
|
||||
```bash
|
||||
wp option list --search='*redis*' --path=$PATH --format=json # []
|
||||
wp option list --search='*rediscache*' --path=$PATH --format=json # []
|
||||
```
|
||||
|
||||
O `redis-cache` **não grava nenhuma opção na base de dados**. Não há página
|
||||
de definições com formulário — `includes/ui/settings.php` é só um wrapper
|
||||
de tabs (Overview/Metrics/Diagnostics) que lê constantes e o estado ao vivo
|
||||
do Redis. Toda a configuração vive em `wp-config.php` (constantes) e o único
|
||||
estado persistente do plugin é:
|
||||
- o próprio ficheiro drop-in `wp-content/object-cache.php` (presença =
|
||||
cache activa);
|
||||
- as métricas, gravadas **dentro do próprio Redis** como sorted set na chave
|
||||
`<prefix>metrics:redis-cache` (via `ZADD`/`ZRANGEBYSCORE`), purgadas por
|
||||
hora via cron `rediscache_discard_metrics` — não em `wp_options` nem em
|
||||
ficheiro.
|
||||
|
||||
Isto tem implicação directa para migração/clonagem de sites: copiar
|
||||
`wp_options` entre sites nunca traz nem perde configuração deste plugin —
|
||||
só o `wp-config.php` (constantes) e o `wp-content/object-cache.php`
|
||||
(presença do drop-in) importam.
|
||||
|
||||
---
|
||||
|
||||
## 9. Interface admin — o que existe na prática
|
||||
|
||||
- **3 tabs** na página `Definições → Redis` (`options-general.php?page=redis-cache`,
|
||||
ou `settings.php?page=redis-cache` em multisite): **Overview**, **Metrics**
|
||||
(desactivado se `Metrics::is_enabled()` for falso, i.e.
|
||||
`WP_REDIS_DISABLE_METRICS`), **Diagnostics** (o mesmo output de
|
||||
`wp redis status`, renderizado em HTML).
|
||||
- **Admin bar**: nó "Object Cache" (removível com `WP_REDIS_DISABLE_ADMINBAR`)
|
||||
com submenu "Flush Cache" (AJAX, acção `roc_flush_cache`) e "Settings";
|
||||
mostra hit-ratio/hits/misses/tamanho da página actual em hover.
|
||||
- **Widget de dashboard** ("Redis Object Cache"), só visível a quem tem a
|
||||
capability de gestão e só se `Metrics::is_enabled()`.
|
||||
- **Integração Query Monitor**: regista um collector/output próprio
|
||||
(`class-qm-collector.php`, `class-qm-output.php`) que acrescenta um painel
|
||||
"Cache" ao Query Monitor quando este plugin está activo — automático, sem
|
||||
configuração.
|
||||
- **Aviso específico WooCommerce**: notice de upsell Pro nas páginas de
|
||||
encomendas/produtos/analytics do WooCommerce (silenciável com
|
||||
`WP_REDIS_DISABLE_BANNERS`).
|
||||
|
||||
### Acções da página de definições vs comandos WP-CLI
|
||||
|
||||
A página admin usa links com nonce (`?action=<x>&_wpnonce=...`) que chamam
|
||||
exactamente a mesma lógica dos comandos WP-CLI:
|
||||
|
||||
| Acção admin (`action=`) | Equivalente WP-CLI | Efeito |
|
||||
|---|---|---|
|
||||
| `enable-cache` | `wp redis enable` | Copia `includes/object-cache.php` para `wp-content/object-cache.php` |
|
||||
| `disable-cache` | `wp redis disable` | Apaga `wp-content/object-cache.php` |
|
||||
| `update-dropin` | `wp redis update-dropin` | Reescreve o drop-in com a versão actual do plugin |
|
||||
| `flush-cache` | `wp cache flush` | Chama `wp_cache_flush()` directamente (sem passar pelo WP-CLI genérico) |
|
||||
|
||||
---
|
||||
|
||||
## 10. Hooks disponíveis para integração
|
||||
|
||||
| Hook | Tipo | Quando dispara |
|
||||
|---|---|---|
|
||||
| `redis_object_cache_enable` | action | Depois de copiar o drop-in ao activar (via admin ou `wp redis enable`) — argumento: `bool $result` |
|
||||
| `redis_object_cache_disable` | action | Depois de apagar o drop-in ao desactivar |
|
||||
| `redis_object_cache_update_dropin` | action | Depois de `wp redis update-dropin` / auto-update |
|
||||
| `redis_object_cache_flush` | action | Em cada `flush()` — argumentos: `$results, $deprecated, $selective, $salt, $execute_time` |
|
||||
| `redis_cache_manager_capability` | filter | Sobrepõe a capability de gestão (default `manage_options`/`manage_network_options`), além/em vez de `WP_REDIS_MANAGER_CAPABILITY` |
|
||||
| `redis_cache_validate_dropin` | filter | Sobrepõe a validação de "o drop-in instalado é o deste plugin" (compara `PluginURI`) |
|
||||
| `redis_cache_add_non_persistent_groups` | filter | Filtra a lista de grupos antes de `add_non_persistent_groups()` os fundir em `ignored_groups` |
|
||||
|
||||
---
|
||||
|
||||
## 11. Auto-resolução de conflitos com outros plugins de cache
|
||||
|
||||
O plugin desactiva proactivamente os object caches nativos de outros
|
||||
plugins de cache/performance para evitar dois drop-ins a lutar pelo mesmo
|
||||
ficheiro:
|
||||
|
||||
```php
|
||||
add_filter( 'perflab_disable_object_cache_dropin', '__return_true' ); // WordPress Performance Lab
|
||||
add_filter( 'w3tc_config_item_objectcache.enabled', '__return_false' ); // W3 Total Cache
|
||||
add_action( 'litespeed_init', [ $this, 'litespeed_disable_objectcache' ] ); // LiteSpeed Cache
|
||||
```
|
||||
|
||||
Relevante para o bundle Descomplicar®: confirma que activar `redis-cache`
|
||||
num site que também tenha W3TC ou LiteSpeed Cache instalado (mesmo que
|
||||
inactivo o respectivo módulo de object cache) não gera conflito — o
|
||||
`redis-cache` desliga automaticamente a componente de object cache desses
|
||||
plugins via filtro, sem intervenção manual.
|
||||
|
||||
## Erros comuns
|
||||
|
||||
| Sintoma | Causa | Solução |
|
||||
|---|---|---|
|
||||
| `wp redis flush` → "not a registered command" | Subcomando não existe no plugin | Usar `wp cache flush` (genérico WP-CLI, funciona via drop-in activo) |
|
||||
| Dados alterados por `wp db query` não aparecem no site | Redis serve versão em cache, SQL directo não invalida | `wp cache flush --path=$PATH` logo a seguir a qualquer escrita SQL |
|
||||
| `wp redis status` mostra `Client: Predis`, não `PhpRedis` | Extensão PHP nativa `redis` não instalada no servidor | Não é erro — Predis é fallback 100% funcional, apenas mais lento; upgrade futuro se a extensão for instalada |
|
||||
| Dois sites com o mesmo `WP_REDIS_DATABASE` (colisão) | `wp-config.php` copiado entre sites sem ajustar `WP_REDIS_DATABASE`/`WP_REDIS_PREFIX` | Correr a verificação da secção 2 após qualquer clone/migração de site no mesmo servidor; atribuir DB livre (0-15) e prefixo único |
|
||||
| `wp redis status` → `Status: Não ligado` mas plugin activo | Drop-in `object-cache.php` ausente/removido de `wp-content/` (ex.: apagado por engano numa migração) | `wp redis enable` reescreve o drop-in |
|
||||
| Confundir "plugin activo" com "cache activa" | `wp plugin is-active redis-cache` só confirma o plugin, não o drop-in | Confirmar sempre com `wp redis status` → `Ping: PONG` |
|
||||
| Definir `WP_REDIS_DISABLED=true` sem remover o drop-in | Comportamento intencional, não um bug | Não é preciso apagar `object-cache.php`; a constante sozinha faz com que nenhuma função `wp_cache_*` seja definida pelo drop-in, e o WordPress core (`wp-includes/load.php::wp_start_object_cache()`) deteta isso e carrega automaticamente o fallback nativo `wp-includes/cache.php` — confirmado por leitura do core nesta expansão |
|
||||
| `wp redis status` → grupos ignorados diferentes de site para site | Não é config do plugin — WordPress core adiciona `counts/plugins/theme_json/themes` e plugins activos (ex. WPForms → `WPForms_Entry_Handler`) via `wp_cache_add_non_persistent_groups()` em runtime | Normal; comparar só via `WP_REDIS_IGNORED_GROUPS` se quiseres saber o que o `redis-cache` em si define (por omissão, nenhum) |
|
||||
@@ -0,0 +1,526 @@
|
||||
---
|
||||
name: seguranca-descomplicar
|
||||
description: Gestão do plugin próprio "Segurança Descomplicar" (seguranca-descomplicar, v1.4.2) via WP-CLI e REST API nos 7 sites do bundle CWP. Cobre os 5 módulos — Security Headers (CSP/XFO/security.txt), Wordfence Agent (endpoint REST autenticado para sites sem SSH), Login/dash (URL de login customizada), Descomplicar Monitor (telemetria para dash.descomplicar.pt), Admin Hardening (Classic Editor, emails de update, nags) — com comandos `wp seguranca-descomplicar`, options `segdesc_*`, e gotchas reais de produção. Usar quando "seguranca-descomplicar", "plugin de segurança Descomplicar", "CSP", "X-Frame-Options", "security.txt", "wordfence agent", "login dash", "/dash", "descomplicar monitor", "admin hardening", "classic editor forçado", "esconder avisos de update", "token do agente", "allowlist IP wordfence agent".
|
||||
---
|
||||
|
||||
# /seguranca-descomplicar — Plugin próprio de segurança WordPress (5 módulos)
|
||||
|
||||
Plugin normal (não mu-plugin, decisão explícita), instalado em
|
||||
`wp-content/plugins/seguranca-descomplicar/`, **gerido inteiramente pela
|
||||
Descomplicar®** — código-fonte único, versionado em
|
||||
`71.Seguranca/plugin/seguranca-descomplicar/seguranca-descomplicar.php`,
|
||||
distribuído por SCP/cp aos 7 sites do bundle. Substitui: `wordsense-agent.php`
|
||||
(plugin antigo), mu-plugin `descomplicar-security-headers.php`, plugin
|
||||
autónomo `descomplicar-monitor`, e todos os snippets WPCode/Code Snippets
|
||||
de login `/dash` e admin hardening que estavam clonados byte-a-byte em 6 dos
|
||||
7 sites.
|
||||
|
||||
**Fonte:** código-fonte completo lido nesta sessão (1494 linhas) +
|
||||
`CONFIG-Plugins-Referencia.md` §2 (config ao vivo verificada nos 7 sites) +
|
||||
`index.md` (changelog de 8 sessões de produção, bugs reais e correcções).
|
||||
|
||||
**Gerido/consumido por (ferramentas externas, fora desta skill):**
|
||||
`71.03-SecHeaders/tools/secheaders.py` (módulo 1) e
|
||||
`71.01-Wordsense/tools/wordsense.py`, transporte `http` (módulo 2).
|
||||
|
||||
---
|
||||
|
||||
## Contexto CWP — sempre obrigatório
|
||||
|
||||
```bash
|
||||
# Local (quando o path existe no filesystem do agente)
|
||||
wp seguranca-descomplicar <comando> --path=$PATH
|
||||
|
||||
# Via SSH (servidor real)
|
||||
ssh -p 9443 root@server.descomplicar.pt \
|
||||
"wp seguranca-descomplicar <comando> --path=$PATH --allow-root"
|
||||
```
|
||||
|
||||
Namespace REST do plugin: `seguranca-descomplicar/v1` (todos os endpoints
|
||||
exigem `Authorization: Bearer <token>`, token de 64 chars hex em
|
||||
`segdesc_agent_token`).
|
||||
|
||||
---
|
||||
|
||||
## Decision tree — qual módulo/comando usar
|
||||
|
||||
| Preciso de | Módulo | Comando/opção |
|
||||
|---|---|---|
|
||||
| Ver/mudar CSP, XFO, security.txt | 1 | `wp seguranca-descomplicar headers status\|set` |
|
||||
| Diagnosticar/ajustar Wordfence sem SSH (via HTTP) | 2 | REST `seguranca-descomplicar/v1/wordfence/*` |
|
||||
| Ligar/mudar a URL de login custom | 3 | `wp seguranca-descomplicar login status\|enable\|disable\|slug\|block-wp-login` |
|
||||
| Ver estado da telemetria para o dashboard | 4 | `wp option get descomplicar_monitor_*` (sem comando CLI próprio) |
|
||||
| Ligar/desligar Classic Editor, emails de update, nags | 5 | `wp seguranca-descomplicar hardening status\|enable\|disable` |
|
||||
| Rodar o token do agente REST | — | `wp seguranca-descomplicar token --rotate` |
|
||||
| Restringir o REST endpoint a IPs específicos | — | `wp seguranca-descomplicar allowlist --set=IP1,IP2` |
|
||||
|
||||
---
|
||||
|
||||
## Referência de constantes (`SEGDESC_*`)
|
||||
|
||||
Todas as constantes definidas no plugin (topo do ficheiro, antes de
|
||||
qualquer hook), agrupadas por função — confirma cobertura total do
|
||||
código-fonte (26 constantes no total).
|
||||
|
||||
**Identificação**
|
||||
|
||||
| Constante | Valor | Nota |
|
||||
|---|---|---|
|
||||
| `SEGDESC_VERSION` | `'1.4.2'` | Devolvida em `wordfence/status.agent_version` |
|
||||
| `SEGDESC_NS` | `'seguranca-descomplicar/v1'` | Namespace REST |
|
||||
|
||||
**Options (`segdesc_*`, persistidas em `wp_options`)** — ver tabelas de
|
||||
cada módulo abaixo para defaults/comportamento; nomes reais:
|
||||
`segdesc_agent_token`, `segdesc_headers_enabled`, `segdesc_csp`,
|
||||
`segdesc_xfo`, `segdesc_csp_report_only`, `segdesc_security_txt`,
|
||||
`segdesc_ip_allowlist`, `segdesc_nginx_csp_covered`,
|
||||
`segdesc_login_enabled`, `segdesc_login_slug`,
|
||||
`segdesc_login_block_wplogin`, `segdesc_hardening_enabled`,
|
||||
`segdesc_hardening_classic_editor`, `segdesc_hardening_update_emails`,
|
||||
`segdesc_hardening_update_nags`.
|
||||
|
||||
**Defaults/valores hardcoded (literais PHP usados como fallback, não são options)**
|
||||
|
||||
| Constante | Valor |
|
||||
|---|---|
|
||||
| `SEGDESC_DEFAULT_LOGIN_SLUG` | `'dash'` |
|
||||
| `SEGDESC_DEFAULT_CSP` | CSP de enforcement (ver secção 1) |
|
||||
| `SEGDESC_DEFAULT_XFO` | `'SAMEORIGIN'` |
|
||||
| `SEGDESC_DEFAULT_CSP_REPORT_ONLY` | CSP Report-Only (ver secção 1) |
|
||||
| `SEGDESC_DANGEROUS_KEYS` | `serialize(['waf_status', 'isPaid', 'apiKey'])` — chaves `wfconfig` que exigem `force_dangerous=true` em `/wordfence/config` |
|
||||
|
||||
**Rate-limit do endpoint REST** (só editável no código, sem option/wp-cli)
|
||||
|
||||
| Constante | Valor | Nota |
|
||||
|---|---|---|
|
||||
| `SEGDESC_RATE_LIMIT_WINDOW` | `60` (segundos) | Janela do tecto geral de pedidos |
|
||||
| `SEGDESC_RATE_LIMIT_MAX` | `60` | Pedidos nominais/IP/janela (~30 reais, ver nota da dupla invocação) |
|
||||
| `SEGDESC_RATE_LIMIT_FAIL_MAX` | `10` | Falhas nominais/IP/janela antes do lockout (~5 reais) |
|
||||
| `SEGDESC_RATE_LIMIT_FAIL_LOCKOUT` | `900` (segundos = 15 min) | Duração do lockout por IP |
|
||||
|
||||
---
|
||||
|
||||
## 1. Security Headers — CSP, X-Frame-Options, security.txt
|
||||
|
||||
Hook `send_headers` (envia CSP/XFO/CSP-Report-Only) + hook `init` (serve
|
||||
`/.well-known/security.txt`, RFC 9116).
|
||||
|
||||
### Options (`segdesc_*`)
|
||||
|
||||
| Option | Default | Nota |
|
||||
|---|---|---|
|
||||
| `segdesc_headers_enabled` | `'1'` (definida na activação) | Liga/desliga o módulo inteiro |
|
||||
| `segdesc_csp` | `SEGDESC_DEFAULT_CSP` (definida na activação) | CSP de **enforcement** — só é enviada se `nginx_csp_covered` ≠ `'1'` |
|
||||
| `segdesc_xfo` | `SAMEORIGIN` (definida na activação) | Sempre enviada, independente do nginx |
|
||||
| `segdesc_csp_report_only` | `SEGDESC_DEFAULT_CSP_REPORT_ONLY` (fallback em código, não persistida na activação) | Sempre enviada — telemetria; único mecanismo de report em sites sem template nginx |
|
||||
| `segdesc_security_txt` | `''` | Sem default — vazio = ficheiro não é servido; conteúdo bruto do `.well-known/security.txt` |
|
||||
| `segdesc_ip_allowlist` | `''` (vazio = sem restrição) | CSV de IPs — só afecta os endpoints REST do módulo 2, não o site público |
|
||||
| `segdesc_nginx_csp_covered` | `'0'` | **`'1'` em sites com o template nginx aplicado** — desliga o CSP de enforcement do plugin (evita intersecção de directivas entre 2 CSPs); XFO continua sempre activo |
|
||||
|
||||
### Comandos
|
||||
|
||||
```bash
|
||||
# Estado
|
||||
wp seguranca-descomplicar headers status --path=$PATH
|
||||
|
||||
# Actualizar CSP/XFO
|
||||
wp seguranca-descomplicar headers set --csp="default-src 'self'; script-src 'self' https:" --path=$PATH
|
||||
wp seguranca-descomplicar headers set --xfo=SAMEORIGIN --path=$PATH
|
||||
|
||||
# security.txt a partir de ficheiro local
|
||||
wp seguranca-descomplicar headers set --security-txt-file=/tmp/security.txt --path=$PATH
|
||||
|
||||
# Ligar/desligar o módulo inteiro
|
||||
wp seguranca-descomplicar headers set --enabled=1 --path=$PATH
|
||||
|
||||
# Opções que o wp-cli custom NÃO cobre — usar wp option directo
|
||||
wp option get segdesc_nginx_csp_covered --path=$PATH
|
||||
wp option update segdesc_nginx_csp_covered 1 --path=$PATH # sites com template nginx aplicado
|
||||
wp option get segdesc_ip_allowlist --path=$PATH
|
||||
```
|
||||
|
||||
### CSP real em produção (v1.4.2 — permissivo por directiva, sem lista branca de domínios)
|
||||
|
||||
```
|
||||
default-src 'self';
|
||||
script-src 'self' 'unsafe-inline' 'unsafe-eval' https:;
|
||||
style-src 'self' 'unsafe-inline' https:;
|
||||
img-src 'self' data: https:;
|
||||
font-src 'self' data: https:;
|
||||
frame-src https:;
|
||||
frame-ancestors 'self';
|
||||
object-src 'none'
|
||||
```
|
||||
|
||||
Decisão explícita do utilizador (10ª sessão): uma lista branca por domínio
|
||||
(`frame-src youtube.com google.com ...`) é manutenção infinita — cada embed
|
||||
novo obriga a voltar a editar. `frame-src https:` permite qualquer iframe
|
||||
servido por HTTPS; o que interessa bloquear é `http://` não encriptado e
|
||||
`data:`/`javascript:`. `object-src 'none'` e `frame-ancestors 'self'`
|
||||
mantêm-se restritos (sem caso de uso legítimo / protecção anti-clickjacking
|
||||
deste site).
|
||||
|
||||
**Nota de produção (16-08-2026):** na prática, no bundle CWP, CSP/XFO são
|
||||
geridos maioritariamente pelo **template nginx** (`71.03-SecHeaders/`,
|
||||
nível de servidor, sobrevive a cache/preload de plugin) nos sites que o
|
||||
têm aplicado — o módulo do plugin fica então limitado a `security.txt` +
|
||||
CSP Report-Only (telemetria, ver `segdesc_nginx_csp_covered`). Em
|
||||
`emanuelalmeida.pt` (piloto desde a 11ª sessão), os headers passaram a
|
||||
ser servidos por **Cloudflare Transform Rules** (token do plugin App for
|
||||
Cloudflare®) — nginx e este plugin continuam a enviar os seus próprios
|
||||
headers, mas ficam invisíveis ao tráfego real porque o `set` do
|
||||
Cloudflare se sobrepõe antes de chegar ao browser; servem só de fallback
|
||||
para acesso directo à origem (bypass do Cloudflare).
|
||||
|
||||
---
|
||||
|
||||
## 2. Wordfence Agent — endpoint REST autenticado (sites sem SSH)
|
||||
|
||||
8 rotas REST sob `seguranca-descomplicar/v1`, autenticação partilhada via
|
||||
`segdesc_check_auth()` (allowlist → lockout → rate-limit → Bearer token).
|
||||
Registadas sempre; `/wordfence/status` indica se o Wordfence está mesmo
|
||||
activo no site.
|
||||
|
||||
| Rota | Método | Payload | Função |
|
||||
|---|---|---|---|
|
||||
| `/headers/status` | GET | — | Estado do módulo 1 |
|
||||
| `/headers/set` | POST | `csp`, `xfo`, `security_txt`, `enabled` | Ajusta módulo 1 remotamente |
|
||||
| `/wordfence/status` | GET | — | `wordfence_active`, `version`, `db_prefix` |
|
||||
| `/wordfence/query` | POST | `sql` | **Só SELECT/SHOW contra exactamente 1 tabela `wf*`** — bloqueia JOIN, subquery, UNION, INSERT/UPDATE/DELETE/DROP/etc. |
|
||||
| `/wordfence/config` | POST | `key`, `value`, `force_dangerous` | UPSERT em `{prefix}wfconfig`; chaves perigosas (`waf_status`, `isPaid`, `apiKey`) exigem `force_dangerous=true` |
|
||||
| `/wordfence/unblock-ip` | POST | `ip` | `DELETE FROM {prefix}wfblockediplog WHERE IP = INET6_ATON(ip)` |
|
||||
| `/wordfence/whitelist-ip` | POST | `ip`, `reason` | Acrescenta `"{ip} #{reason}"` a `neverBlockIP` em `wfconfig` |
|
||||
| `/wordfence/scan` | POST | — | `wfScanEngine::startScan()` se a classe existir; senão `do_action('wordfence_doScan')` (fallback cron) |
|
||||
|
||||
**`/headers/*` — nota de proveniência:** os 2 endpoints REST de headers
|
||||
(`status`/`set`) foram desenhados para o transporte `http` de
|
||||
`71.03-SecHeaders/tools/secheaders.py` (comentário no código-fonte:
|
||||
"usados por secheaders.py transporte 'http' (futuro, hoje só SSH)") —
|
||||
presentes e funcionais, mas **ainda não consumidos em produção**:
|
||||
`secheaders.py` aplica correcções via SSH/wp-cli directo, não via este
|
||||
REST. Único consumidor real hoje é o próprio `wp seguranca-descomplicar
|
||||
headers`.
|
||||
|
||||
### Autenticação e rate-limit (importante para clientes REST)
|
||||
|
||||
```
|
||||
Authorization: Bearer <segdesc_agent_token>
|
||||
```
|
||||
|
||||
- **Allowlist de IP** (opcional, `segdesc_ip_allowlist`) verificada primeiro.
|
||||
- **Rate-limit** por IP: 60 pedidos/60s nominal — **mas o `WP_REST_Server`
|
||||
invoca `permission_callback` DUAS VEZES por pedido HTTP real** (confirmado
|
||||
ao vivo em `carstuff.pt`), pelo que o limite prático é ~30 pedidos reais,
|
||||
não 60.
|
||||
- **Lockout por falhas de auth:** 10 falhas nominais (~5 reais) → lockout de
|
||||
15 min (900s), chaveado por IP via transient.
|
||||
- **IP do cliente** (`segdesc_client_ip()`) só confia em `X-Forwarded-For`
|
||||
quando `REMOTE_ADDR` é um proxy local confiável (`127.0.0.1`/`::1`) — as
|
||||
portas backend do CWP (2083/2031/2095) são acessíveis directamente da
|
||||
internet, por isso um pedido directo ao backend usa sempre `REMOTE_ADDR`,
|
||||
nunca o XFF do atacante.
|
||||
|
||||
### Comandos WP-CLI relacionados
|
||||
|
||||
```bash
|
||||
# Ver/rodar o token de autenticação do agente
|
||||
wp seguranca-descomplicar token --path=$PATH
|
||||
wp seguranca-descomplicar token --rotate --path=$PATH
|
||||
|
||||
# Allowlist de IP para os endpoints REST
|
||||
wp seguranca-descomplicar allowlist --path=$PATH
|
||||
wp seguranca-descomplicar allowlist --set=203.0.113.5,203.0.113.6 --path=$PATH
|
||||
wp seguranca-descomplicar allowlist --clear --path=$PATH
|
||||
```
|
||||
|
||||
### Exemplo de pedido real (curl)
|
||||
|
||||
```bash
|
||||
TOKEN=$(wp seguranca-descomplicar token --path=$PATH)
|
||||
curl -s https://site.pt/wp-json/seguranca-descomplicar/v1/wordfence/status \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Login /dash — URL de login customizada e segura
|
||||
|
||||
Substitui os antigos snippets WPCode "Alterar /wp-admin para /dash" (que
|
||||
deixaram de executar por `E_DEPRECATED` em PHP 8.2 — ver Gotchas). Handler
|
||||
em `template_redirect` prioridade 1 (antes do `redirect_canonical`,
|
||||
prioridade 10).
|
||||
|
||||
### Comportamento quando `segdesc_login_enabled = '1'`
|
||||
|
||||
- `/<slug>` (default `dash`): mostra o form nativo de login WP se não
|
||||
autenticado; `wp_redirect(admin_url())` se autenticado.
|
||||
- `wp-login.php` directo (GET): **404** para não autenticados. O **POST**
|
||||
do form (submissão real do login) continua a funcionar — o bloqueio só
|
||||
intercepta GET.
|
||||
- `/wp-admin/` directo: **404** para não autenticados, excepto
|
||||
`admin-ajax.php` (necessário para plugins front-end).
|
||||
|
||||
### Hooks internos
|
||||
|
||||
| Hook | Prioridade | Função |
|
||||
|---|---|---|
|
||||
| `init` → `segdesc_login_rewrite_rule` | default (10) | Regista `add_rewrite_rule('^<slug>/?$', 'index.php?segdesc_login=1', 'top')` — só se o módulo estiver ligado |
|
||||
| `query_vars` → `segdesc_login_query_var` | default (10) | Regista a query var `segdesc_login` (necessária para o WP reconhecer o parâmetro da rewrite rule) |
|
||||
| `template_redirect` → `segdesc_login_handle` | **1** | Handler principal — antes do `redirect_canonical` (prioridade 10) |
|
||||
| `init` → `segdesc_login_block_wp_login` | default (10) | Bloqueio de `wp-login.php` directo (GET) |
|
||||
| `init` → `segdesc_login_block_wp_admin` | default (10) | Bloqueio de `/wp-admin/` directo (excepto `admin-ajax.php`) |
|
||||
| `update_option_segdesc_login_slug` → `segdesc_login_flush_rules_on_slug_change` | default (10) | `flush_rewrite_rules()` automático sempre que `segdesc_login_slug` muda — **mesmo por `wp option update` directo**, não só pelo subcomando `login slug` |
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Default | Nota |
|
||||
|---|---|---|
|
||||
| `segdesc_login_enabled` | `'0'` | Módulo desligado por omissão — só activo onde pedido |
|
||||
| `segdesc_login_slug` | `'dash'` (constante `SEGDESC_DEFAULT_LOGIN_SLUG`, não persistida a menos que alterada) | Sanitizado para `[a-z0-9_-]` |
|
||||
| `segdesc_login_block_wplogin` | `'1'` | Bloqueia `wp-login.php` directo (GET) |
|
||||
|
||||
### Comandos
|
||||
|
||||
```bash
|
||||
wp seguranca-descomplicar login status --path=$PATH
|
||||
wp seguranca-descomplicar login enable --path=$PATH # faz flush_rewrite_rules() automático
|
||||
wp seguranca-descomplicar login disable --path=$PATH
|
||||
wp seguranca-descomplicar login slug --set=acesso --path=$PATH
|
||||
wp seguranca-descomplicar login block-wp-login --on --path=$PATH
|
||||
wp seguranca-descomplicar login block-wp-login --off --path=$PATH
|
||||
```
|
||||
|
||||
`status` devolve `enabled`, `slug`, `block_wp_login`, `login_url` (URL
|
||||
completo já resolvido com `home_url()`).
|
||||
|
||||
**Nota carstuff.pt (achado 10ª sessão, fora do âmbito deste módulo):**
|
||||
`/dash` naquele site serve login e `wp-login.php` redirecciona para
|
||||
`/dash` por um mecanismo que **não é o Módulo 3** (nunca activado em
|
||||
carstuff.pt até à migração completa) nem o snippet WPCode legado (sempre
|
||||
em draft) — candidato mais provável é o `branda-white-labeling`
|
||||
(login-screen custom). Login do admin funciona normalmente; não confundir
|
||||
com este módulo ao diagnosticar `/dash` nesse site especificamente.
|
||||
|
||||
---
|
||||
|
||||
## 4. Descomplicar Monitor — telemetria para dash.descomplicar.pt
|
||||
|
||||
Classe `Descomplicar_Monitor` (singleton), **funde o antigo plugin autónomo
|
||||
`descomplicar-monitor`** — reutiliza as MESMAS options
|
||||
(`descomplicar_monitor_*`, prefixo diferente do resto do plugin, propositado
|
||||
para preservar dados na migração) e o MESMO cron
|
||||
(`descomplicar_monitor_cron`). Guard
|
||||
`is_plugin_active('descomplicar-monitor/descomplicar-monitor.php')`: só
|
||||
instancia se o plugin antigo não estiver activo (evita duplicar envios).
|
||||
|
||||
**Sem comando WP-CLI próprio** — este módulo não regista `WP_CLI::add_command`.
|
||||
Interage-se via `wp option`, `wp eval`, ou a página de definições em
|
||||
**Definições → Descomplicar Monitor** (`add_options_page`, capability
|
||||
`manage_options`; grupo de settings `descomplicar_monitor_settings` via
|
||||
`register_settings`, hook `admin_init`; AJAX `descomplicar_monitor_test` /
|
||||
`descomplicar_monitor_send_now`, ambos com nonce próprio via
|
||||
`check_ajax_referer`).
|
||||
|
||||
### Hooks internos
|
||||
|
||||
| Hook | Função |
|
||||
|---|---|
|
||||
| `admin_menu` → `add_admin_menu` | Regista a página **Definições → Descomplicar Monitor** |
|
||||
| `admin_init` → `register_settings` | Regista o grupo `descomplicar_monitor_settings` (campos `api_key`, `enabled`) |
|
||||
| `descomplicar_monitor_cron` → `send_monitoring_data` | Handler do cron — envia a telemetria |
|
||||
| `cron_schedules` → `add_cron_interval` | Regista um intervalo **próprio** chamado `twice_daily` (43200s = 12h) — **não é o `twicedaily` nativo do WordPress** (nomes diferentes, mesmo valor); `wp_schedule_event` usa este nome custom |
|
||||
| `wp_ajax_descomplicar_monitor_test` → `ajax_test_connection` | AJAX "Testar Conexão" |
|
||||
| `wp_ajax_descomplicar_monitor_send_now` → `ajax_send_now` | AJAX "Enviar Agora" |
|
||||
| `init` → `ensure_cron` | Reagenda `descomplicar_monitor_cron` se `wp_next_scheduled()` devolver vazio |
|
||||
|
||||
**Sem `register_deactivation_hook`** (nenhum módulo do plugin tem) — ao
|
||||
desactivar o plugin, o evento `descomplicar_monitor_cron` continua
|
||||
agendado no wp-cron, mas o código deixa de carregar, logo o disparo do
|
||||
evento não faz nada (sem handler registado) — consome um ciclo de cron
|
||||
sem efeito, sem erro visível. Reactivar retoma o envio automaticamente,
|
||||
sem reconfigurar nada (options preservadas).
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Nota |
|
||||
|---|---|
|
||||
| `descomplicar_monitor_enabled` | `'1'`/`'0'` — sem module flag `segdesc_*` (nome legado preservado) |
|
||||
| `descomplicar_monitor_api_key` | Chave enviada como header `X-API-Key` |
|
||||
| `descomplicar_monitor_last_sent` | Timestamp `Y-m-d H:i:s`, actualizado em cada tentativa (sucesso ou falha) |
|
||||
| `descomplicar_monitor_last_status` | `'success'` ou a mensagem de erro |
|
||||
|
||||
### Dados recolhidos (POST JSON para `https://dash.descomplicar.pt/api/wp-monitor`)
|
||||
|
||||
URL, nome, **email de admin**, versão WP/PHP/MySQL, **flag multisite**,
|
||||
**timestamp ISO 8601** (`current_time('c')`) e **timezone** do site, tema
|
||||
(+ parent), lista de plugins activos c/ versão, updates pendentes
|
||||
(core/plugins/themes, com bloco `counts` agregado), contagem de
|
||||
posts/páginas/utilizadores/comentários, estatísticas da BD (**nº de
|
||||
tabelas `{prefix}*`**, tamanho em MB, **prefix**, transients expirados,
|
||||
tamanho do autoload em KB), memory_limit, upload máximo, debug mode, SSL,
|
||||
cron disabled, cache habilitada, e um bloco `health` (status
|
||||
good/warning/critical com lista de issues: `WP_DEBUG` sem log, sem SSL,
|
||||
uploads sem permissão de escrita, memória PHP < 64MB).
|
||||
|
||||
**Nota:** `get_pending_updates()` chama `wp_update_plugins()` e
|
||||
`wp_update_themes()` directamente antes de ler `get_plugin_updates()`/
|
||||
`get_theme_updates()` — força uma verificação síncrona a
|
||||
`api.wordpress.org` em **cada execução do cron de 12h**, mesmo que o
|
||||
WordPress já tivesse um resultado em cache válido. Corre em contexto de
|
||||
cron (não bloqueia carregamento de página), por isso não é o mesmo
|
||||
problema de performance do Gotcha #3 (que era em `admin_init`/page load).
|
||||
|
||||
### Comandos úteis
|
||||
|
||||
```bash
|
||||
# Estado
|
||||
wp option get descomplicar_monitor_enabled --path=$PATH
|
||||
wp option get descomplicar_monitor_last_status --path=$PATH
|
||||
wp option get descomplicar_monitor_last_sent --path=$PATH
|
||||
|
||||
# Forçar envio imediato (fora do cron 12h)
|
||||
wp eval 'echo json_encode(Descomplicar_Monitor::get_instance()->send_monitoring_data());' --path=$PATH
|
||||
|
||||
# Confirmar que o cron está agendado (reagenda-se sozinho em cada 'init' se limpo)
|
||||
wp cron event list --path=$PATH --fields=hook,next_run_relative | grep descomplicar_monitor_cron
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Admin Hardening — Classic Editor, emails de update, nags
|
||||
|
||||
Substitui 3 snippets WPCode/Code Snippets clonados byte-a-byte (`md5sum`
|
||||
idêntico) em 6 dos 7 sites CWP (origem: tutorial WPBeginner). O snippet de
|
||||
emails tinha um bug real herdado: `add_filter('auto_core_update_send_email',
|
||||
'wpb_stop_auto_update_emails', ...)` referenciava uma função nunca definida
|
||||
(`wpb_stop_update_emails`, sem `_auto`), gerando `E_WARNING` silencioso em
|
||||
cada auto-update. O módulo simplifica para `__return_false` directo.
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Default (quando `hardening_enabled='1'`) | Nota |
|
||||
|---|---|---|
|
||||
| `segdesc_hardening_enabled` | `'0'` | Módulo desligado por omissão |
|
||||
| `segdesc_hardening_classic_editor` | `'1'` | `use_block_editor_for_post{,_type}` → `__return_false` |
|
||||
| `segdesc_hardening_update_emails` | `'1'` | `auto_{core,plugin,theme}_update_send_email` → `__return_false` |
|
||||
| `segdesc_hardening_update_nags` | `'1'` | Wipe de `admin_notices`/`all_admin_notices`/`network_admin_notices` (incl. avisos Wordfence) + CSS para esconder badges de contagem |
|
||||
|
||||
### Comandos
|
||||
|
||||
```bash
|
||||
wp seguranca-descomplicar hardening status --path=$PATH
|
||||
wp seguranca-descomplicar hardening enable --path=$PATH
|
||||
wp seguranca-descomplicar hardening enable --no-classic-editor --path=$PATH # liga o módulo mas deixa o bloco editor
|
||||
wp seguranca-descomplicar hardening enable --no-update-emails --path=$PATH
|
||||
wp seguranca-descomplicar hardening enable --no-update-nags --path=$PATH
|
||||
wp seguranca-descomplicar hardening disable --path=$PATH
|
||||
```
|
||||
|
||||
### Como o bloqueio de nags funciona de facto (decisão de negócio: agressivo)
|
||||
|
||||
Decisão do Emanuel: bloquear TAMBÉM avisos Wordfence e visibilidade de
|
||||
updates pendentes — clientes reencaminhavam esses avisos/emails achando que
|
||||
eram falha da Descomplicar. Dois mecanismos distintos, **nunca tocando nos
|
||||
transients de update** (ver Gotchas #3):
|
||||
|
||||
1. **`in_admin_header` prioridade 999** → `unset($wp_filter['admin_notices'])`
|
||||
(+ `all_admin_notices` + `network_admin_notices`). Tem de ser
|
||||
`in_admin_header`, não `admin_init` (ver Gotchas #2).
|
||||
2. **`admin_head`** → injecta `<style>` que esconde
|
||||
`#adminmenu .update-plugins`, `#wpadminbar .update-plugins`,
|
||||
`#adminmenu .wf-menu-badge` (o badge "Wordfence N" no menu não é um hook
|
||||
— é HTML injectado directamente no título do item de menu por
|
||||
`wordfenceClass.php`; só CSS apanha).
|
||||
|
||||
---
|
||||
|
||||
## Deploy aos 7 sites do bundle
|
||||
|
||||
Fonte do plugin canónico:
|
||||
`71.Seguranca/plugin/seguranca-descomplicar/` → copiado para
|
||||
`wp-content/plugins/seguranca-descomplicar/` em cada site
|
||||
(`tools/distribuir_e_activar_plugin.py`: `cp -r` local se o `path` existir
|
||||
no filesystem, senão `mkdir -p` + `scp -P 9443` + `ssh ... wp plugin
|
||||
activate` via `root@server.descomplicar.pt`).
|
||||
|
||||
| Domínio | Conta CWP | Path |
|
||||
|---|---|---|
|
||||
| `descomplicar.pt` | `ealmeida` | `/home/ealmeida/public_html` |
|
||||
| `emanuelalmeida.pt` | `ealmeida` | `/home/ealmeida/emanuelalmeida.pt` |
|
||||
| `carstuff.pt` | `carstuff` | `/home/carstuff/public_html` |
|
||||
| `familyclinic.pt` | `familycl` | `/home/familycl/public_html` |
|
||||
| `ignitionvortex.pt` | `ignition` | `/home/ignition/public_html` |
|
||||
| `solarfvengenharia.com` | `solarfv` | `/home/solarfv/public_html` |
|
||||
| `watercontrol.pt` | `wtc` | `/home/wtc/public_html` |
|
||||
|
||||
```bash
|
||||
python3 tools/distribuir_e_activar_plugin.py
|
||||
```
|
||||
|
||||
`tools/executar_pipeline_completa.py` orquestra o ciclo completo de
|
||||
segurança nos mesmos 7 domínios (`SITES_CONFIG`, campo `tipo:
|
||||
"nossos_sites"`): 1) diagnóstico externo (`seguranca-check.py`) → 2)
|
||||
diagnóstico de postura interno (`postura.py` → wordsense + softcheck) → 3)
|
||||
correcção automática de headers (`secheaders.py`, template nginx ou este
|
||||
plugin) → 4) re-análise de verificação → 5) relatório visual. Usa
|
||||
`--confirm-fix` para aplicar correcções (sem a flag, é dry-run/diagnóstico).
|
||||
|
||||
**Estado ao vivo confirmado (16-08-2026):** 5 módulos activos e coerentes
|
||||
nos 7 sites — `headers_enabled=1`, `login_enabled=1` (7/7, antes eram 5/7),
|
||||
`hardening_enabled=1` (7/7), `bridge`/monitor migrado 7/7. Único desvio real
|
||||
por site: `segdesc_nginx_csp_covered` só é `'1'` nos sites com o template
|
||||
nginx aplicado (todos excepto casos pontuais em rollout).
|
||||
|
||||
**Scripts sem flags de plugin:** `distribuir_e_activar_plugin.py` não
|
||||
aceita argumentos CLI — itera sempre a lista `SITES` completa hardcoded
|
||||
(`cp -r` local se o `path` existir, senão `mkdir -p` + `scp -P 9443` +
|
||||
`ssh ... wp plugin activate` via `root@server.descomplicar.pt`, porta
|
||||
9443). `executar_pipeline_completa.py` só tem uma flag, `--confirm-fix`
|
||||
(sem ela = dry-run/diagnóstico só); a lista `SITES_CONFIG` mapeia cada
|
||||
domínio para `wordsense_site`/`softcheck_account` — usados por
|
||||
`postura.py`/`wordsense.py` (fora desta skill), não por este plugin
|
||||
directamente.
|
||||
|
||||
---
|
||||
|
||||
## Gotchas / erros reais corrigidos em produção
|
||||
|
||||
| # | Sintoma | Causa raiz | Correcção |
|
||||
|---|---|---|---|
|
||||
| 1 | Actualizar `post_content` de um snippet WPCode via `$wpdb->update` directo não desliga o snippet legado | O WPCode mantém uma cache compilada em `wp_options.wpcode_snippets`, separada de `wp_posts` — não invalida por escrita SQL directa | Apagar a option `wpcode_snippets` ou chamar `wpcode()->cache->cache_all_loaded_snippets()` depois de qualquer edição directa em BD |
|
||||
| 2 | Aviso "ElementsKit Lite Premium" (ou outro plugin) sobrevive ao wipe de `admin_notices` | Alguns plugins registam o callback em `admin_notices` **de dentro** de outro callback pendurado em `admin_head` — que corre **depois** de `admin_init` na sequência de bootstrap (`admin_init → load-{page} → admin_head → in_admin_header → admin_notices`) | Wipe tem de estar em `in_admin_header` prioridade 999 (o último ponto seguro antes de `admin_notices` disparar), nunca em `admin_init` |
|
||||
| 3 | Regressão de performance real: ~1,3s extra em **todo** o carregamento do wp-admin (medido: core 0,4s + plugins 0,5s + temas 0,3s) | Bloquear `pre_site_transient_update_*` para esconder nags impede a cache nativa de 12h do WordPress de "pegar" — `_maybe_update_core/plugins/themes()` vêem sempre "nunca verificado" e disparam pedido HTTP síncrono a `api.wordpress.org` em cada page load | Nunca tocar nos transients de update; esconder badges/contadores só por CSS (`.update-plugins`) |
|
||||
| 4 | Badge "Wordfence N" no menu lateral continua visível apesar do wipe de `admin_notices` | Não vem de nenhum hook — é HTML injectado directamente no título do item de menu por `wordfenceClass.php` | Só CSS resolve: `#adminmenu .wf-menu-badge { display: none !important; }` |
|
||||
| 5 | `/dash` dá 404, `wp-login.php` também dá 404 — login completamente inacessível | Snippet WPCode legado usava `basename(parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH))` sem protecção — em PHP 8.2 `parse_url` pode devolver `null`, `basename(null)` dispara `E_DEPRECATED`; o WPCode apanha o erro e marca o snippet em `wpcode_snippets_errors`, **deixando de o executar por completo** (rewrite rule, query var e redirect todos mortos) | Migrado para código de plugin normal (Módulo 3), sem essa fragilidade; `wp rewrite flush --hard` depois de qualquer mudança de slug |
|
||||
| 6 | Regra de rewrite `/<slug>` não persistia em alguns sites recém-activados | Rewrite rules não flushed após `login enable` em certas condições de cache de permalinks | `wp rewrite flush --hard` explícito após activar o módulo 3 |
|
||||
| 7 | `security.txt` continha `mailto:seguranca@descomplicar.pt` — mailbox **inexistente** | Valor hardcoded em `tools/executar_pipeline_completa.py` (`--contact seguranca@descomplicar.pt`), replicado para os 7 sites no deploy inicial. Não foi apanhado pela auditoria automática (só validava presença/formato do ficheiro, não se o mailbox era real) | Corrigido nos 7 sites (`wp_options` ao vivo) e na origem (script) para `mailto:it@descomplicar.pt` — mesmo endereço usado em `alertEmails` do Wordfence, `rua`/`ruf` do DMARC, e utilizador `only-me` do WSAL |
|
||||
| 8 | reCAPTCHA/YouTube bloqueados por CSP mesmo com `frame-src` a permitir | CSP duplicado (nginx + plugin) — browsers aplicam a directiva mais restritiva de **cada** CSP na intersecção; o nginx não declarava `frame-src`, caindo no fallback mais restrito | `segdesc_nginx_csp_covered = '1'` nos sites com template nginx — nginx passa a ser a única autoridade de enforcement, plugin só mantém XFO + Report-Only |
|
||||
| 9 | `WP_REST_Server` conta o dobro dos pedidos reais nos limiares de rate-limit | `permission_callback` é invocado **duas vezes** por pedido HTTP real (confirmado por transient antes/depois de 1 pedido) | Limiares nominais (`FAIL_MAX=10`, `MAX=60`) valem, na prática, metade (~5 e ~30) — mantido assim de propósito, mais conservador não prejudica uso legítimo |
|
||||
| 10 | `X-Forwarded-For` falsificável permitia contornar allowlist/rate-limit/lockout do endpoint REST | Portas backend do CWP (2083/2031/2095) acessíveis directamente da internet — confiar incondicionalmente em XFF permitia a um atacante que batesse directo no backend falsificar o IP visto | `segdesc_client_ip()` só confia em XFF quando `REMOTE_ADDR` é um proxy local confiável (`127.0.0.1`/`::1`), e só no último valor da cadeia (o que o próprio nginx anexa) |
|
||||
| 11 | Desactivar o plugin não limpa cron/options/rewrite rules | Nenhum módulo regista `register_deactivation_hook` — só existe `register_activation_hook` (gera token + activa headers com CSP/XFO default) | `descomplicar_monitor_cron` fica agendado mas sem handler (evento inofensivo, sem efeito); opções `segdesc_*`/`descomplicar_monitor_*` e a rewrite rule do slug de login persistem; reactivar retoma o estado exactamente onde ficou — desejável para reinstalação, mas exige limpeza manual (`wp option delete`) numa desinstalação definitiva |
|
||||
|
||||
---
|
||||
|
||||
## Fonte
|
||||
|
||||
- `71.Seguranca/plugin/seguranca-descomplicar/seguranca-descomplicar.php`
|
||||
(v1.4.2, 1494 linhas) — código-fonte completo, relido linha a linha
|
||||
nesta expansão: todas as 26 constantes `SEGDESC_*`, os 6 hooks do
|
||||
Módulo 3, os 7 hooks do Módulo 4 (incl. `cron_schedules` custom), os
|
||||
8 endpoints REST (não 7 — corrigido nesta expansão), e os 5 subcomandos
|
||||
WP-CLI (`token`, `allowlist`, `headers`, `login`, `hardening`)
|
||||
confirmados exaustivos (sem `WP_CLI::add_command` adicional no
|
||||
ficheiro).
|
||||
- `71.Seguranca/CONFIG-Plugins-Referencia.md` §2 (`seguranca-descomplicar`)
|
||||
— config ao vivo verificada via wp-cli nos 7 sites, 16-08-2026.
|
||||
- `71.Seguranca/tools/distribuir_e_activar_plugin.py` e
|
||||
`tools/executar_pipeline_completa.py` — relidos por completo; confirmado
|
||||
que nenhum dos dois expõe flags de configuração do plugin em si (só
|
||||
`--confirm-fix` no pipeline, sem argumentos no script de distribuição).
|
||||
- `71.Seguranca/index.md` — lido na íntegra (linhas 1-627, não só
|
||||
183-636 como na versão anterior desta skill); confirmou a contagem real
|
||||
de 8 rotas REST (tabela de bundle da 12ª sessão: "8 rotas REST
|
||||
(`/wordfence/*` × 6, `/headers/*` × 2)"), a nota de que CSP/XFO ficam
|
||||
hoje maioritariamente a cargo do nginx/Cloudflare (módulo do plugin na
|
||||
prática só serve `security.txt` nos sites com essa cobertura), e o caso
|
||||
carstuff.pt (mecanismo de `/dash` alheio a este plugin).
|
||||
@@ -0,0 +1,648 @@
|
||||
---
|
||||
name: webp-express
|
||||
description: Gestão do plugin WebP Express (conversão automática de imagens para WebP) via WP-CLI e ficheiro de config em servidores CWP. Cobre localizar o ficheiro de config com hash variável, modos de operação (CDN friendly, Varied image responses, No conversion, Tweaked), reconversão em massa via `wp webp-express convert`, flush de webps, conversores disponíveis (imagemagick/imagick/gd vs cwebp/vips/ffmpeg/graphicsmagick/wpc/ewww) e as respectivas opções próprias, estrutura JSON completa do ficheiro de configuração (qualidade/encoding/near-lossless/alpha-quality por tipo de imagem, cache-control, alter HTML, redirection rules, web service), regras `.htaccess` e a fronteira com o Cloudflare. Usar quando "webp express", "converter imagens webp", "webp nao funciona", "reconverter imagens", "flush webp", "conversor imagemagick gd", "operation mode webp", "cdn friendly webp", "webp quality", "near lossless", "alter html webp", "cache control webp", "web service webp express".
|
||||
---
|
||||
|
||||
# /webp-express — Conversão de imagens para WebP via WP-CLI
|
||||
|
||||
Gestão programática do plugin WebP Express (`webp-express`) em sites WordPress
|
||||
da frota, via WP-CLI no servidor CWP (`server.descomplicar.pt`, SSH porta
|
||||
9443).
|
||||
|
||||
**Fonte:** `CONFIG-Plugins-Referencia.md` §5 (WebP Express) + verificação ao
|
||||
vivo em `emanuelalmeida.pt` (versão `0.25.15`) + leitura completa do
|
||||
código-fonte nesta sessão: `lib/classes/CLI.php`, `lib/classes/CachePurge.php`,
|
||||
`lib/classes/BulkConvert.php`, e **todos** os ficheiros `.inc`/`.php` de
|
||||
`lib/options/options/` (general, conversion-options incl.
|
||||
`converter-options/*.php` por conversor, redirection-rules, serve-options,
|
||||
alter-html, web-service-options, operation-mode.inc) — 43 ficheiros no total.
|
||||
Config JSON completo lido ao vivo do disco (não só campos vistos na UI).
|
||||
|
||||
---
|
||||
|
||||
## Contexto CWP — sempre obrigatório
|
||||
|
||||
```bash
|
||||
PATH=/home/USER/public_html
|
||||
sudo -u USER /usr/local/bin/wp <comando> --path=$PATH
|
||||
```
|
||||
|
||||
**Acesso via SSH:** `ssh -p 9443 root@server.descomplicar.pt` (alias `server`
|
||||
já configurado localmente).
|
||||
|
||||
---
|
||||
|
||||
## 1. Onde vive a configuração — NÃO é `wp_options` normal
|
||||
|
||||
A config principal do WebP Express vive num **ficheiro JSON com nome
|
||||
imprevisível** (hash no nome, muda por instalação/reinstalação):
|
||||
|
||||
```
|
||||
wp-content/webp-express/config/config.<hash>.json
|
||||
```
|
||||
|
||||
**Nunca assumir o hash.** Duas formas de o descobrir, por ordem de
|
||||
preferência:
|
||||
|
||||
```bash
|
||||
# 1. Forma rápida — o hash está guardado numa option (sem precisar de find)
|
||||
wp option get webp-express-config-hash --path=$PATH
|
||||
|
||||
# 2. Confirmar/descobrir via find quando a option não existe ou for preciso
|
||||
# validar o caminho real no disco
|
||||
find $PATH/wp-content/webp-express/config -iname 'config.*.json'
|
||||
```
|
||||
|
||||
O ficheiro em si:
|
||||
|
||||
```bash
|
||||
HASH=$(wp option get webp-express-config-hash --path=$PATH)
|
||||
cat $PATH/wp-content/webp-express/config/config.$HASH.json | python3 -m json.tool
|
||||
```
|
||||
|
||||
### Estado operacional (`wp_options`, separado da config)
|
||||
|
||||
Ao contrário da config, o **estado** vive mesmo em `wp_options` normais,
|
||||
todas com o prefixo `webp-express-`:
|
||||
|
||||
```bash
|
||||
wp option get webp-express-state --format=json --path=$PATH
|
||||
wp option get webp-express-migration-version --path=$PATH
|
||||
wp option get webp-express-config-migrated-cve-2025-11379 --path=$PATH
|
||||
wp option get webp-express-alter-html-options --format=json --path=$PATH
|
||||
```
|
||||
|
||||
`webp-express-state` traz o resumo mais útil de uma só vez:
|
||||
`workingConverterIds`, `workingAndActiveConverterIds`, `configured`,
|
||||
`htaccess-rules-saved-at-some-point`, `active-htaccess-dirs`.
|
||||
|
||||
### ⚠️ Gotcha: `convert_webp_status` e `webp_offset_*` NÃO são do WebP Express
|
||||
|
||||
Numa auditoria com `wp option list --search='*webp*'` aparecem também
|
||||
`convert_webp_status` e vários `webp_offset_*` (`webp_offset_thumbnail`,
|
||||
`webp_offset_large`, etc.). **São opções órfãs de outro plugin** (não
|
||||
presente na lista activa de plugins do site) — não pertencem ao WebP
|
||||
Express e não devem ser lidas/alteradas ao auditar este plugin. Confirmar
|
||||
sempre com `wp plugin list --format=json | grep -i webp` que só
|
||||
`webp-express` está activo antes de interpretar options com "webp" no nome.
|
||||
|
||||
---
|
||||
|
||||
## 2. Modos de operação (`operation-mode`)
|
||||
|
||||
Fonte: `lib/options/options/operation-mode.inc`. Quatro valores possíveis:
|
||||
|
||||
| Valor | Nome na UI | Comportamento |
|
||||
|---|---|---|
|
||||
| `varied-image-responses` | Varied image responses | Redirecciona jpeg/png para webp via `.htaccess`, mas só quando o browser envia `Accept: image/webp`. A mesma URL responde de forma diferente consoante o cliente — **problemático para CDNs que não fazem `Vary` no header `Accept`** |
|
||||
| `cdn-friendly` | CDN friendly | jpeg é **sempre** servido como jpeg; em vez de variar a resposta, o WebP Express reescreve o HTML (`<picture>`/`<img srcset>`) para apontar directamente ao ficheiro `.webp` estático. Melhor HIT ratio em CDN, sem exigir forward do header `Accept` |
|
||||
| `no-conversion` | No conversion | Não converte nada — usado quando outro plugin já faz a conversão e só se quer aproveitar a reescrita de HTML/redirecção do WebP Express |
|
||||
| `tweaked` | Tweaked | Sem preset — todas as opções ficam editáveis individualmente (mostra secções `redirection-rules` e `serve-options` completas, que ficam escondidas nos outros modos); ao voltar a um preset perdem-se as afinações |
|
||||
|
||||
**Verificado em `emanuelalmeida.pt`:** `operation-mode: "cdn-friendly"` —
|
||||
escolha correcta dado o site estar atrás do Cloudflare (evita depender de o
|
||||
Cloudflare fazer `Vary: Accept` correctamente, que nem sempre acontece nos
|
||||
planos gratuitos).
|
||||
|
||||
```bash
|
||||
HASH=$(wp option get webp-express-config-hash --path=$PATH)
|
||||
wp eval "echo json_decode(file_get_contents('wp-content/webp-express/config/config.$HASH.json'))->{'operation-mode'};" --path=$PATH
|
||||
```
|
||||
|
||||
Para mudar de modo é preciso editar o ficheiro JSON directamente (não há
|
||||
comando `wp option patch` — não é uma option serializada) e depois correr
|
||||
`wp webp-express convert --reconvert` para regenerar tudo com as novas
|
||||
definições. **Mutação em produção — nunca fazer sem autorização.**
|
||||
|
||||
**Nota de UI condicional por modo** (relevante ao ler o código de
|
||||
`lib/options/options/general/general.inc`): as secções `scope.inc`,
|
||||
`destination-folder.inc` e `destination-structure.inc` só aparecem quando
|
||||
`operation-mode != 'no-conversion'`; `cache-control.inc` só aparece em
|
||||
`tweaked`, `varied-image-responses` ou `cdn-friendly`. O JSON de config
|
||||
mantém sempre todos os campos gravados, independentemente do que a UI
|
||||
mostra para o modo actual.
|
||||
|
||||
---
|
||||
|
||||
## 3. Reconverter imagens em massa — comando nativo `wp webp-express`
|
||||
|
||||
O plugin regista um comando WP-CLI próprio (`lib/classes/CLI.php`), **não é
|
||||
preciso passar por `wp eval`**. Fonte lida na íntegra nesta sessão — o
|
||||
plugin só regista **dois** subcomandos, não há mais:
|
||||
|
||||
```bash
|
||||
wp help webp-express --path=$PATH
|
||||
```
|
||||
|
||||
```
|
||||
NAME
|
||||
wp webp-express
|
||||
SUBCOMMANDS
|
||||
convert Convert images to webp
|
||||
flushwebp Flush webps
|
||||
```
|
||||
|
||||
### `wp webp-express convert`
|
||||
|
||||
```bash
|
||||
# Ver o que falta converter, sem converter (dry preview por pasta)
|
||||
wp webp-express convert --path=$PATH
|
||||
|
||||
# Converter tudo o que ainda não está convertido (media library + tema)
|
||||
wp webp-express convert uploads --path=$PATH
|
||||
wp webp-express convert themes --path=$PATH
|
||||
|
||||
# Forçar RECONVERSÃO de tudo (substitui webps já existentes)
|
||||
wp webp-express convert uploads --reconvert --path=$PATH
|
||||
|
||||
# Limitar a uma subpasta
|
||||
wp webp-express convert uploads/2026 --path=$PATH
|
||||
|
||||
# Só PNG / só JPEG
|
||||
wp webp-express convert uploads --only-png --path=$PATH
|
||||
wp webp-express convert uploads --only-jpeg --path=$PATH
|
||||
|
||||
# Forçar um conversor específico (ignora o stack de fallback)
|
||||
wp webp-express convert uploads --converter=gd --path=$PATH
|
||||
|
||||
# Sobrepor qualidade/encoding só nesta corrida (não altera a config gravada)
|
||||
wp webp-express convert uploads --quality=75 --encoding=lossy --path=$PATH
|
||||
|
||||
# Sobrepor near-lossless e alpha-quality só nesta corrida
|
||||
wp webp-express convert uploads --near-lossless=60 --path=$PATH
|
||||
wp webp-express convert uploads --alpha-quality=80 --path=$PATH
|
||||
```
|
||||
|
||||
`<location>` aceita `uploads`, `themes`, `plugins`, `wp-content` ou `index`
|
||||
como "raiz de imagem", opcionalmente seguido de `/subpasta`. Sem argumento,
|
||||
lista quantos ficheiros por converter há em cada grupo, sem converter nada.
|
||||
|
||||
**Flags completas do `convert`** (confirmadas em `CLI.php`, docblock
|
||||
`## OPTIONS`):
|
||||
|
||||
| Flag | Efeito | Aplica-se a `max-quality` E `png-quality` |
|
||||
|---|---|---|
|
||||
| `[<location>]` | Restringe a uma raiz de imagem (`uploads`\|`themes`\|`plugins`\|`wp-content`\|`index`), opc. `/subpasta` | — |
|
||||
| `--reconvert` | Reconverte mesmo o que já está convertido | — |
|
||||
| `--only-png` | Só PNG (`image-types = 2`) | — |
|
||||
| `--only-jpeg` | Só JPEG (`image-types = 1`) | — |
|
||||
| `--quality=<n>` | Sobrepõe qualidade (0-100) | Sim — aplica ao mesmo valor `max-quality` e `png-quality` |
|
||||
| `--near-lossless=<n>` | Sobrepõe near-lossless (0-100) | Sim — aplica a `png-near-lossless` e `jpeg-near-lossless` |
|
||||
| `--alpha-quality=<n>` | Sobrepõe alpha-quality (0-100) | Só `alpha-quality` (PNG com transparência) |
|
||||
| `--encoding=<auto\|lossy\|lossless>` | Sobrepõe encoding | Sim — aplica a `png-encoding` e `jpeg-encoding` |
|
||||
| `--converter=<id>` | Força um conversor específico, ignora o stack. Valores válidos: `cwebp \| vips \| ewww \| imagemagick \| imagick \| gmagick \| graphicsmagick \| ffmpeg \| gd \| wpc` | — |
|
||||
|
||||
Nenhuma destas flags altera a config gravada em disco — são só para essa
|
||||
corrida.
|
||||
|
||||
### `wp webp-express flushwebp` — limpar webps gerados
|
||||
|
||||
```bash
|
||||
# Apaga TODOS os .webp gerados (força reconversão no próximo acesso/convert)
|
||||
wp webp-express flushwebp --path=$PATH
|
||||
|
||||
# Só os que vieram de PNG
|
||||
wp webp-express flushwebp --only-png --path=$PATH
|
||||
```
|
||||
|
||||
Internamente chama `CachePurge::purge()` (`lib/classes/CachePurge.php`),
|
||||
que apaga recursivamente `.webp` em três locais: o cache dir
|
||||
(`Paths::getCacheDirAbs()`), o upload dir (só se
|
||||
`destination-folder == 'mingled'`) e o dir de "bigger than source dummy
|
||||
files". Nunca apaga o original de um attachment registado na media library
|
||||
(`MediaLibraryHelper::isRegisteredAttachmentOrThumbnail`) — protecção
|
||||
interna contra apagar acidentalmente ficheiros errados quando modo
|
||||
`mingled` mistura originais e webps na mesma pasta.
|
||||
|
||||
Útil depois de mudar `quality`/`encoding`/conversor na config, antes de
|
||||
correr `convert` de novo — garante que não ficam webps antigos com as
|
||||
definições anteriores misturados com os novos.
|
||||
|
||||
**Alternativa via wp-admin (sem SSH):** Settings → WebP Express → aba
|
||||
"Bulk convert" tem os mesmos botões ("Bulk Convert" → popup de conversão em
|
||||
massa via AJAX; "Delete converted files" → popup que chama
|
||||
`processAjaxPurgeCache()`, o mesmo `CachePurge::purge()` do `flushwebp`).
|
||||
Há ainda um botão "Delete log files" na secção "Enable logging" (ver §7).
|
||||
O WP-CLI é preferível em produção por ser scriptável e não depender de
|
||||
timeout do browser em sites com muitas imagens. **Nota:** a conversão em
|
||||
massa via UI usa sempre as **últimas definições gravadas** (comentário no
|
||||
código-fonte de `bulk-convert.inc`: *"the bulk conversion is using the
|
||||
last saved settings"*) — se acabaste de mudar qualidade/encoding no forms
|
||||
mas ainda não gravaste (Save), o bulk convert usa a versão antiga.
|
||||
|
||||
---
|
||||
|
||||
## 4. Conversores — stack de fallback e opções por conversor
|
||||
|
||||
`webp-express` tenta uma lista ordenada de conversores até um funcionar; cada
|
||||
entrada tem `working: true/false` gravado em `webp-express-state` (testado
|
||||
no arranque, não em cada conversão):
|
||||
|
||||
| Conversor | Estado em `emanuelalmeida.pt` | Nota |
|
||||
|---|---|---|
|
||||
| `imagemagick` (binário CLI) | ✅ `working: true`¹ | Fallback preferido |
|
||||
| `imagick` (extensão PHP) | ✅ `working: true`¹ | |
|
||||
| `gd` (extensão PHP, sempre disponível) | ✅ `working: true` | Último recurso, sempre presente em qualquer instalação PHP |
|
||||
| `cwebp` (binário Google) | ❌ `working: false` | Não instalado no servidor CWP |
|
||||
| `vips` | ❌ `working: false` | Não instalado |
|
||||
| `graphicsmagick`/`gmagick` | ❌ `working: false` | Não instalado |
|
||||
| `ffmpeg` | ❌ `working: false` | Não instalado |
|
||||
| `wpc` (WebP Cloud / Remote WebP Express, API paga ou remota) | ❌ `working: false` | Não configurado (sem API key/URL) |
|
||||
| `ewww` (requer plugin EWWW Image Optimizer) | ❌ `working: false` | Plugin não instalado neste site |
|
||||
|
||||
¹ Nota lida directamente no JSON de config nesta sessão: no bloco
|
||||
`converters[]` do config actual, `imagemagick` e `graphicsmagick` aparecem
|
||||
com `"working": false` (o binário de sistema não responde), enquanto só
|
||||
`gd` tem `"working": true`. O `webp-express-state` (cache separada,
|
||||
recalculada a cada teste de auto-detecção) pode divergir ligeiramente do
|
||||
snapshot gravado no `converters[]` do JSON — **confirmar sempre pelo
|
||||
`webp-express-state` para saber o estado corrente**, o array `converters`
|
||||
do config json é sobretudo a lista de opções por conversor + ordem.
|
||||
|
||||
**Sem impacto operacional** — `gd` cobre 100% dos casos como último
|
||||
recurso; os conversores em falta são apenas alternativas mais
|
||||
rápidas/melhor compressão que não compensam instalar a nível de servidor
|
||||
só para este plugin. Verificar sempre `workingConverterIds` antes de forçar
|
||||
`--converter=X` num `wp webp-express convert` — se `X` não estiver na
|
||||
lista, o comando falha.
|
||||
|
||||
```bash
|
||||
wp option get webp-express-state --format=json --path=$PATH | python3 -c "import json,sys; print(json.load(sys.stdin)['workingConverterIds'])"
|
||||
```
|
||||
|
||||
### Opções específicas por conversor (bloco `converters[].options` no JSON)
|
||||
|
||||
Fonte: `lib/options/options/conversion-options/converter-options/*.php` (um
|
||||
ficheiro por conversor) + o array `converters` do config JSON ao vivo.
|
||||
|
||||
| Conversor | Opções (`options{}`) | Descrição |
|
||||
|---|---|---|
|
||||
| `cwebp` | `use-nice` (bool), `try-common-system-paths` (bool), `try-supplied-binary-for-os` (bool), `method` (0-6), `low-memory`/"set-size"+`size-in-percentage`, `command-line-options` (string livre passada ao binário) | `method`: trade-off velocidade/qualidade (0=rápido, 6=melhor). "Size" força tamanho-alvo em % do original em vez de qualidade (~2.5x mais lento). `command-line-options` aceita qualquer flag do `cwebp` real, ex. `-low_memory -af -f 50 -sharpness 0 -mt` |
|
||||
| `vips` | `smart-subsample` (bool), `preset` (`none`\|`default`\|`photo`\|`picture`\|`drawing`\|`icon`\|`text`) | Preset ajusta várias opções internas consoante o tipo de conteúdo (não sobrepõe qualidade) |
|
||||
| `imagemagick` | `use-nice` (bool) | Executa o binário `convert`; sem outras opções específicas |
|
||||
| `graphicsmagick` (`gmagick`) | `use-nice` (bool) | Executa `gm convert`; sem outras opções específicas |
|
||||
| `ffmpeg` | `use-nice` (bool), `method` (0-6) | Idêntico ao `imagemagick` mas via ffmpeg |
|
||||
| `gd` | `skip-pngs` (bool) | Se `true`, PNGs passam para o próximo conversor da stack (Gd historicamente pior a comprimir PNG e teve bugs de transparência, hoje resolvidos) |
|
||||
| `imagick` | — (sem opções próprias) | "imagick has no special options" no código |
|
||||
| `ewww` | `api-key`, `api-key-2` (fallback) | Serviço cloud pago (ewww.io); fee único, sem custo por conversão webp |
|
||||
| `wpc` (Remote WebP Express / WPC) | `api-version` (0\|1), `api-url`, `secret`/`api-key`, `crypt-api-key-in-transfer` (bool) | Delega a conversão a outra instalação WebP Express ou a um serviço `webp-convert-cloud-service`. Api 0 é legado (v0.1); usar 1 para instâncias WebP Express normais |
|
||||
|
||||
`use-nice`: presente em quase todos os conversores baseados em binário —
|
||||
executa com prioridade reduzida (`nice`) para poupar recursos à custa de
|
||||
conversão ligeiramente mais lenta.
|
||||
|
||||
`Use nice`, `try-common-system-paths`, `try-supplied-binary-for-os`: o
|
||||
plugin traz binários `cwebp` pré-compilados para várias plataformas dentro
|
||||
do próprio plugin (`try-supplied-binary-for-os`) — útil quando o binário de
|
||||
sistema não existe mas o hosting permite `exec()`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Qualidade, encoding, near-lossless e metadata (`conversion-options`)
|
||||
|
||||
Fonte: `lib/options/options/conversion-options/{quality,jpeg,png,metadata}.inc`
|
||||
+ valores ao vivo do JSON de `emanuelalmeida.pt`.
|
||||
|
||||
### 5.1. JPEG → WebP
|
||||
|
||||
| Campo JSON | Valor ao vivo | Descrição |
|
||||
|---|---|---|
|
||||
| `jpeg-encoding` | `"auto"` | `lossy` (sempre lossy) ou `auto` (o plugin experimenta lossy e lossless e fica com o mais pequeno). `Gd`/`Ewww` não suportam `auto` |
|
||||
| `quality-auto` | `true` | Se `true`, tenta detectar a qualidade original do jpeg e usar a mesma no webp (requer imagick/imagemagick/gmagick capazes de detectar qualidade); se `false`, usa `quality-specific` fixo |
|
||||
| `max-quality` | `80` | Tecto para `quality-auto`: mesmo que o jpeg original tenha qualidade mais alta, nunca ultrapassa este valor. Recomendado 50-85 |
|
||||
| `quality-specific` | `70` | Qualidade fixa usada quando `quality-auto=false` OU como fallback quando a detecção de qualidade falhar |
|
||||
| `jpeg-enable-near-lossless` | `true` | Aplica-se quando o encoding resultante é lossless: liga o pré-processamento "near-lossless" em vez de 100% lossless puro. Só suportado por `cwebp` e `vips` |
|
||||
| `jpeg-near-lossless` | `60` | Nível 0 (máximo pré-processamento) a 100 (sem pré-processamento, = lossless puro) |
|
||||
|
||||
### 5.2. PNG → WebP
|
||||
|
||||
| Campo JSON | Valor ao vivo | Descrição |
|
||||
|---|---|---|
|
||||
| `png-encoding` | `"auto"` | `lossless` (default para PNG) ou `auto` (experimenta lossy e lossless, fica com o mais pequeno — não existe opção "sempre lossy" isolada para PNG na UI) |
|
||||
| `png-quality` | `85` | Qualidade quando o resultado é lossy (via `auto`). Recomendado 60-90, tipicamente mais alto que jpeg pois PNG é usado para ícones/gráficos |
|
||||
| `alpha-quality` | `80` | Qualidade específica do canal alfa (transparência), só relevante em encoding lossy com transparência. `Gd`/`Ewww` ignoram esta opção e mantêm o canal alfa sempre lossless |
|
||||
| `png-enable-near-lossless` | `true` | Idêntico ao `jpeg-enable-near-lossless`, mas para PNG |
|
||||
| `png-near-lossless` | `60` | Idêntico ao `jpeg-near-lossless` |
|
||||
|
||||
### 5.3. Metadata
|
||||
|
||||
| Campo JSON | Valor ao vivo | Descrição |
|
||||
|---|---|---|
|
||||
| `metadata` | `"none"` | `none` (não copia EXIF/etc. para o webp — mais pequeno) ou `all` (copia toda a metadata). **`Gd` não suporta cópia de metadata** — ignora esta opção sempre que `Gd` é o conversor efectivo |
|
||||
|
||||
### 5.4. Outras opções gerais de conversão
|
||||
|
||||
| Campo JSON | Valor ao vivo | Descrição |
|
||||
|---|---|---|
|
||||
| `convert-on-upload` | `true` | Converte a imagem (incl. todos os thumbnails gerados) no momento do upload para a media library. Hooka em `handle_upload` e `image_make_intermediate_size`. Pode abrandar o upload em temas com muitos tamanhos de thumbnail |
|
||||
| `image-types` | `3` | Bitmask: `1`=jpeg, `2`=png, `3`=ambos, `0`=desactivado. Controla que tipos são convertidos/processados |
|
||||
| `prevent-using-webps-larger-than-original` | `true` | Webps maiores que o original ficam sempre em disco mas não são usados (nem em `.htaccess` nem em Alter HTML) se esta opção estiver activa. Desde 0.25.5: em Alter HTML com `picture` + `srcset`, só omite o `<source webp>` se **todos** os webps do srcset forem maiores — considerar desactivar se muitas imagens têm srcset |
|
||||
| `enable-logging` | `false` | Grava resultado de cada conversão em `wp-content/webp-express/log/conversions/`. Tem botão dedicado "Delete log files" na UI (popup `purgelogpopup`) |
|
||||
|
||||
---
|
||||
|
||||
## 6. Estrutura completa do ficheiro de configuração (JSON)
|
||||
|
||||
Volcado ao vivo de `emanuelalmeida.pt`
|
||||
(`wp-content/webp-express/config/config.<hash>.json`) — esta é a **lista
|
||||
completa de todas as chaves de topo** que o plugin grava, incluindo as que
|
||||
não aparecem directamente numa única aba da UI:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
// --- Modo e âmbito ---
|
||||
"operation-mode": "cdn-friendly", // varied-image-responses | cdn-friendly | no-conversion | tweaked
|
||||
"scope": ["uploads", "themes"], // subset de: uploads, themes, plugins, wp-content, index
|
||||
"image-types": 3, // bitmask: 1=jpeg 2=png 3=ambos 0=nenhum
|
||||
|
||||
// --- Destino dos ficheiros webp ---
|
||||
"destination-folder": "separate", // separate | mingled
|
||||
"destination-extension": "append", // append (image.jpg.webp) | set (image.webp)
|
||||
"destination-structure": "image-roots", // doc-root | image-roots
|
||||
|
||||
// --- Cache-Control header ---
|
||||
"cache-control": "no-header", // no-header | set | custom
|
||||
"cache-control-custom": "public, max-age=31536000, stale-while-revalidate=604800, stale-if-error=604800",
|
||||
"cache-control-max-age": "one-week", // one-second|one-minute|one-hour|one-day|one-week|one-month|one-year
|
||||
"cache-control-public": false, // true=public, false=private (só usado quando cache-control=set)
|
||||
|
||||
// --- Robustez ---
|
||||
"prevent-using-webps-larger-than-original": true,
|
||||
"enable-logging": false,
|
||||
|
||||
// --- Redirection rules (.htaccess) ---
|
||||
"enable-redirection-to-converter": false, // só editável em modo "tweaked"/"varied-image-responses"
|
||||
"only-redirect-to-converter-on-cache-miss": false,
|
||||
"only-redirect-to-converter-for-webp-enabled-browsers": true,
|
||||
"do-not-pass-source-in-query-string": true,
|
||||
"redirect-to-existing-in-htaccess": false,
|
||||
"forward-query-string": true,
|
||||
"enable-redirection-to-webp-realizer": true, // "criar webp sob pedido" (chave em cdn-friendly)
|
||||
|
||||
// --- Qualidade/encoding jpeg ---
|
||||
"jpeg-encoding": "auto", // lossy | auto
|
||||
"jpeg-enable-near-lossless": true,
|
||||
"jpeg-near-lossless": 60,
|
||||
"quality-auto": true,
|
||||
"max-quality": 80,
|
||||
"quality-specific": 70,
|
||||
|
||||
// --- Qualidade/encoding png ---
|
||||
"png-encoding": "auto", // lossless | auto
|
||||
"png-enable-near-lossless": true,
|
||||
"png-near-lossless": 60,
|
||||
"png-quality": 85,
|
||||
"alpha-quality": 80,
|
||||
|
||||
// --- Stack de conversores, ordem = prioridade ---
|
||||
"converters": [
|
||||
{ "converter": "cwebp", "options": { "use-nice": true, "try-common-system-paths": true, "try-supplied-binary-for-os": true, "method": 6, "low-memory": true, "command-line-options": "" }, "working": false },
|
||||
{ "converter": "vips", "options": { "smart-subsample": false, "preset": "none" }, "working": false },
|
||||
{ "converter": "imagemagick", "options": { "use-nice": true }, "working": false },
|
||||
{ "converter": "graphicsmagick", "options": { "use-nice": true }, "working": false },
|
||||
{ "converter": "ffmpeg", "options": { "use-nice": true, "method": 4 }, "working": false },
|
||||
{ "converter": "wpc", "working": false, "options": { "api-key": "" } },
|
||||
{ "converter": "ewww", "working": false },
|
||||
{ "converter": "imagick", "working": false },
|
||||
{ "converter": "gmagick", "working": false },
|
||||
{ "converter": "gd", "options": { "skip-pngs": false }, "working": true }
|
||||
],
|
||||
|
||||
// --- Metadata / upload automático ---
|
||||
"metadata": "none", // none | all
|
||||
"convert-on-upload": true,
|
||||
|
||||
// --- Serve options (resposta ao browser) ---
|
||||
"fail": "original", // original | 404 | report
|
||||
"success-response": "original", // original | converted
|
||||
|
||||
// --- Alter HTML ---
|
||||
"alter-html": {
|
||||
"enabled": true,
|
||||
"replacement": "picture", // picture | url
|
||||
"hooks": "ob", // content-hooks | ob (output buffering completo da página)
|
||||
"only-for-webp-enabled-browsers": false,
|
||||
"only-for-webps-that-exists": false,
|
||||
"alter-html-add-picturefill-js": true,
|
||||
"hostname-aliases": [] // hostnames extra (CDN) cujas URLs também devem ser reescritas
|
||||
},
|
||||
|
||||
// --- Web service (partilhar conversão com outros sites) ---
|
||||
"web-service": {
|
||||
"enabled": false,
|
||||
"whitelist": [] // [{ip, label, api-key, crypt-in-transfer}, ...]
|
||||
},
|
||||
|
||||
// --- Snapshot de ambiente à data do save (diagnóstico, não editável) ---
|
||||
"environment-when-config-was-saved": { "...": "..." },
|
||||
"base-htaccess-on-these-capability-tests": { "...": "..." },
|
||||
"document-root": "/home/USER/site",
|
||||
"paths-used-in-htaccess": { "wod-url-path": "wp-content/plugins/webp-express/wod/webp-on-demand.php" }
|
||||
}
|
||||
```
|
||||
|
||||
### 6.1. Cache-Control header — detalhe
|
||||
|
||||
Fonte: `lib/options/options/general/cache-control.inc`.
|
||||
|
||||
| `cache-control` | Comportamento |
|
||||
|---|---|
|
||||
| `no-header` | Não define header — deixa o servidor/CDN decidir |
|
||||
| `set` | Usa `cache-control-public` (public/private) + `cache-control-max-age` (preset de duração) para montar o header automaticamente |
|
||||
| `custom` | Usa literalmente a string em `cache-control-custom` — **única forma de definir `stale-while-revalidate`/`stale-if-error`**, não expostos nos presets |
|
||||
|
||||
O texto de ajuda do próprio plugin recomenda `custom` com
|
||||
`stale-while-revalidate`/`stale-if-error` para melhor resiliência em falhas
|
||||
momentâneas do servidor de origem.
|
||||
|
||||
### 6.2. Scope — mapeamento de valores
|
||||
|
||||
Fonte: `lib/options/options/general/scope.inc`. O array `scope[]` é
|
||||
qualquer subconjunto ordenado alfabeticamente de `uploads`, `themes`,
|
||||
`plugins`, `wp-content`, `index`; a UI mapeia combinações comuns para
|
||||
nomes amigáveis:
|
||||
|
||||
| `scope` (array) | Nome na UI |
|
||||
|---|---|
|
||||
| `["uploads"]` | Uploads only |
|
||||
| `["themes"]` | Themes only |
|
||||
| `["themes", "uploads"]` | Uploads and themes |
|
||||
| `["plugins", "themes", "uploads", "wp-content"]` | All content |
|
||||
| `["index", "plugins", "themes", "uploads", "wp-content"]` | Everything (including wp-admin) |
|
||||
| Qualquer outra combinação | Mostrado como "Custom: …" |
|
||||
|
||||
**Verificado em `emanuelalmeida.pt`:** `["uploads", "themes"]` → "Uploads
|
||||
and themes" (plugins/wp-content fora de âmbito).
|
||||
|
||||
### 6.3. Destination folder / extension / structure
|
||||
|
||||
| Opção | Valores | Efeito |
|
||||
|---|---|---|
|
||||
| `destination-folder` | `separate` (pasta dedicada `wp-content/webp-express/webp-images/`) \| `mingled` (webp ao lado do original, só dentro de `uploads`) | `mingled` é recomendado ao combinar com plugins de cache de página que sabem servir por extensão (ex. Cache Enabler), ou com Shortpixel |
|
||||
| `destination-extension` | `append` (`imagem.jpg.webp`) \| `set` (`imagem.webp`) | `set` conflitua se existir `logo.jpg` E `logo.png` na mesma pasta (colidem no mesmo `logo.webp`) |
|
||||
| `destination-structure` | `doc-root` (espelha caminho a partir da doc root) \| `image-roots` (espelha caminho a partir da raiz de imagem — uploads/themes/etc) | Recomendado `image-roots` em hosts com doc root mal configurada; `doc-root` reduz regras de rewrite necessárias em Nginx |
|
||||
|
||||
**Verificado em `emanuelalmeida.pt`:** `destination-folder: "separate"`,
|
||||
`destination-extension: "append"`, `destination-structure: "image-roots"`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Redirection rules (`.htaccess`) — detalhe por opção
|
||||
|
||||
Fonte: `lib/options/options/redirection-rules/*.inc`. Estas opções só são
|
||||
todas editáveis em modo `tweaked`; nos outros modos, o preset do modo
|
||||
decide-as automaticamente (mas o valor gravado no JSON reflecte sempre o
|
||||
que está realmente activo em `.htaccess`).
|
||||
|
||||
| Campo JSON | Descrição |
|
||||
|---|---|
|
||||
| `redirect-to-existing-in-htaccess` | Redirect interno directo para o `.webp` já existente, sem passar por PHP — mais rápido. Regra fica **acima** da regra de conversão |
|
||||
| `enable-redirection-to-converter` | Redirige jpeg/png (não convertidos) para `webp-on-demand.php`, que converte, grava e serve. Regra fica **abaixo** da anterior (só actua se ainda não existir webp) |
|
||||
| `enable-redirection-to-webp-realizer` | "Criar webp files upon request": redirige pedidos por um `.webp` que **ainda não existe** para `webp-realizer.php`, que procura o jpg/png correspondente, converte e serve — permite referenciar webps no HTML antes de existirem fisicamente. É a opção chave em modo `cdn-friendly` |
|
||||
| `only-redirect-to-converter-for-webp-enabled-browsers` | Só actua a regra do `enable-redirection-to-converter` quando o `Accept` header contém `image/webp` |
|
||||
| `only-redirect-to-converter-on-cache-miss` | Condição extra equivalente à funcionalidade usada por `enable-redirection-to-webp-realizer`, mas aplicada ao `enable-redirection-to-converter` — desnecessária se `redirect-to-existing-in-htaccess` já estiver activo |
|
||||
| `do-not-pass-source-in-query-string` | Se `true` (default recomendado), passa o path da imagem por env var em vez de query string, para não disparar firewalls que bloqueiam certas query strings |
|
||||
| `forward-query-string` | Encaminha a query string original do pedido para o script de conversão |
|
||||
|
||||
---
|
||||
|
||||
## 8. Serve options (resposta ao browser após conversão)
|
||||
|
||||
Fonte: `lib/options/options/serve-options/*.inc` — só visível na UI em modo
|
||||
`tweaked`.
|
||||
|
||||
| Campo JSON | Valores | Descrição |
|
||||
|---|---|---|
|
||||
| `fail` | `original` (serve o jpg/png original) \| `404` \| `report` (relatório de erro em texto simples) | Recomendado `original` em produção |
|
||||
| `success-response` | `original` \| `converted` | `converted` envia header `Vary: Accept` (indica que a resposta depende do Accept). Usar `original` se combinado com plugins de cache de página que não sabem variar por Accept (ex. Cache Enabler sem suporte dual-cache) |
|
||||
|
||||
**Verificado em `emanuelalmeida.pt`:** `fail: "original"`,
|
||||
`success-response: "original"`.
|
||||
|
||||
---
|
||||
|
||||
## 9. Alter HTML — detalhe completo
|
||||
|
||||
Fonte: `lib/options/options/alter-html/*.inc`.
|
||||
|
||||
| Campo JSON (`alter-html.*`) | Valores | Descrição |
|
||||
|---|---|---|
|
||||
| `enabled` | bool | Recomendado activar mesmo com redirecção activa: melhora cache em CDN e mantém extensão correcta ao fazer download de imagem |
|
||||
| `replacement` | `picture` \| `url` | **`picture`**: substitui `<img>` por `<picture>` com `<source type="image/webp">` — funciona bem com cache de página, mas pode quebrar CSS `div > img` (usar `div img`). **`url`**: substitui directamente os URLs de imagem (src, srcset, lazy-load attrs, inline styles) — mais abrangente mas não funciona com cache de página excepto Cache Enabler |
|
||||
| `hooks` | `content-hooks` \| `ob` | `content-hooks`: hooka em `the_content`, `the_excerpt`, `post_thumbnail_html`, `get_avatar`, `woocommerce_product_get_image`, `acf_the_content`, `dynamic_sidebar_before/after` — mais leve. `ob`: intercepta a página inteira via output buffering — necessário se o tema/plugin não usa os hooks standard. HTML > 600kb ignora a alteração por protecção de memória |
|
||||
| `only-for-webp-enabled-browsers` | bool | Só relevante com `replacement=url`: só faz a substituição quando o browser suporta webp (evita servir só-webp a browsers antigos sem JS de fallback) |
|
||||
| `only-for-webps-that-exists` | bool | Se `false` ("Reference webps that haven't been converted yet" activo), permite referenciar webps que ainda não existem — requer `enable-redirection-to-webp-realizer` activo para funcionar |
|
||||
| `alter-html-add-picturefill-js` | bool | Só relevante com `replacement=picture`: injecta polyfill `picturefill.js` para browsers sem suporte nativo a `<picture>` (~94% suporte nativo actual) |
|
||||
| `hostname-aliases` | array de strings | Hostnames adicionais (ex. CDN) cujas imagens também devem ser processadas — útil se outro plugin já reescreve URLs para um CDN antes do WebP Express actuar |
|
||||
|
||||
**Verificado em `emanuelalmeida.pt`:** `enabled: true`,
|
||||
`replacement: "picture"`, `hooks: "ob"`,
|
||||
`only-for-webp-enabled-browsers: false`,
|
||||
`only-for-webps-that-exists: false`,
|
||||
`alter-html-add-picturefill-js: true`, `hostname-aliases: []`.
|
||||
|
||||
---
|
||||
|
||||
## 10. Web service — partilhar conversão entre sites
|
||||
|
||||
Fonte: `lib/options/options/web-service-options/*.inc`. Permite que **este**
|
||||
site actue como servidor de conversão remota para outros sites que usam o
|
||||
conversor `wpc`/"Remote WebP Express" (ver §4).
|
||||
|
||||
| Campo JSON (`web-service.*`) | Descrição |
|
||||
|---|---|
|
||||
| `enabled` | Activa o endpoint (URL exposto: `Paths::getWebServiceUrl()`) |
|
||||
| `whitelist[]` | Lista de sites autorizados a usar este endpoint, cada entrada com: `label` (referência própria), `ip` (aceita wildcard `*`, ex. `212.91.*` ou `*` para qualquer IP), `api-key` (chave arbitrária escolhida pelo utilizador, não um segredo gerado), `crypt-api-key-in-transfer` (bool — cifra a api-key no transporte; alguns setups antigos não suportam) |
|
||||
|
||||
**Verificado em `emanuelalmeida.pt`:** `web-service.enabled: false`,
|
||||
`whitelist: []` — não usado como servidor remoto neste site.
|
||||
|
||||
---
|
||||
|
||||
## 11. Bulk convert e cache purge (via UI e via CLI)
|
||||
|
||||
Fonte: `lib/options/options/conversion-options/bulk-convert.inc` +
|
||||
`lib/classes/BulkConvert.php` + `lib/classes/CachePurge.php`.
|
||||
|
||||
- **UI → "Bulk Convert"** dispara AJAX que usa `BulkConvert::getList()` +
|
||||
conversão sequencial das últimas definições **gravadas**. Equivalente
|
||||
CLI: `wp webp-express convert <scope> [--reconvert]`.
|
||||
- **UI → "Delete converted files"** dispara AJAX
|
||||
`CachePurge::processAjaxPurgeCache()`. Equivalente CLI:
|
||||
`wp webp-express flushwebp [--only-png]`.
|
||||
- **UI → "Delete log files"** (dentro da secção "Enable logging") apaga
|
||||
`wp-content/webp-express/log/conversions/*`; sem equivalente CLI
|
||||
dedicado — usar `wp eval` ou apagar directamente via `find`/`rm` se
|
||||
necessário (nunca sem autorização em produção).
|
||||
- O filtro de listagem interno (`BulkConvert::defaultListOptions`) usa
|
||||
sempre `only-unconverted: true` por default (não reconverte o que já
|
||||
existe) e `max-depth: 100` — nunca varre mais de 100 níveis de
|
||||
subpastas.
|
||||
- `CachePurge::purge()` nunca apaga `.webp` que estejam registados como
|
||||
attachment/thumbnail na media library (protecção em modo `mingled`, onde
|
||||
originais e webps partilham pasta).
|
||||
|
||||
---
|
||||
|
||||
## 12. Regras `.htaccess`
|
||||
|
||||
`webp-express-state.configured: true` e
|
||||
`htaccess-rules-saved-at-some-point: true` confirmam que as regras já foram
|
||||
gravadas — normalmente na pasta de cache do próprio plugin
|
||||
(`active-htaccess-dirs: ["cache"]`), não na raiz do site. Isto é o que faz
|
||||
o browser/Cloudflare receberem directamente o ficheiro `.webp` estático em
|
||||
vez de passar por PHP a cada pedido (modo `cdn-friendly`).
|
||||
|
||||
Se `configured: false` ou o site deixar de servir webps depois de uma
|
||||
migração/restauro, o passo de correcção é voltar à página de definições do
|
||||
plugin (wp-admin) e gravar de novo (o botão "Save" regrava o `.htaccess`) —
|
||||
não há comando WP-CLI dedicado a isto; o mais próximo é
|
||||
`wp webp-express flushwebp` seguido de `convert`, que não recria as regras
|
||||
`.htaccess` por si só.
|
||||
|
||||
---
|
||||
|
||||
## 13. Interacção com Cloudflare — quem faz o quê
|
||||
|
||||
**Achado desta sessão, importante para não duplicar trabalho:** a
|
||||
conversão/optimização de imagem feita pelo **Cloudflare "Polish"** está
|
||||
`off` neste site (não editável no plano Free) — o WebP não vem do
|
||||
Cloudflare, vem inteiramente do WebP Express a correr no WordPress. O
|
||||
Cloudflare aqui é só **cache/CDN de distribuição** do ficheiro `.webp` já
|
||||
gerado, não faz qualquer transformação de imagem própria. Não há
|
||||
sobreposição de funcionalidade a resolver, mas também não há optimização
|
||||
de imagem "grátis" via Cloudflare a contar — se o WebP Express falhar a
|
||||
converter, o Cloudflare não compensa.
|
||||
|
||||
Modo `cdn-friendly` foi escolhido precisamente por causa disto: ao reescrever
|
||||
o HTML para apontar directamente ao `.webp` estático (em vez de depender do
|
||||
`Accept` header e do Cloudflare fazer `Vary` correctamente), garante HIT
|
||||
ratio alto no cache do Cloudflare independentemente do plano.
|
||||
|
||||
---
|
||||
|
||||
## Erros comuns
|
||||
|
||||
| Sintoma | Causa | Solução |
|
||||
|---|---|---|
|
||||
| `find`/`cat` no ficheiro de config falha, "No such file" | Hash do nome do ficheiro mudou (reinstalação/migração) | Nunca hardcode o hash — ler sempre `wp option get webp-express-config-hash` primeiro |
|
||||
| Confundir `convert_webp_status`/`webp_offset_*` com definições do WebP Express | Options órfãs de outro plugin já removido, mesmo prefixo textual "webp" | Confirmar `wp plugin list` antes de interpretar qualquer option com "webp" no nome |
|
||||
| `wp webp-express convert --converter=cwebp` falha | Conversor não está na lista `workingConverterIds` (binário não instalado no servidor) | Verificar `webp-express-state` antes de forçar um conversor específico |
|
||||
| Imagens não aparecem como WebP no browser depois de `convert` | `.htaccess` não gravado (`configured: false`) ou modo `varied-image-responses` com CDN sem `Vary: Accept` | Confirmar `configured: true` em `webp-express-state`; preferir `cdn-friendly` atrás de Cloudflare |
|
||||
| Webps antigos com qualidade errada persistem depois de mudar `quality`/`encoding` na config | `convert` normal só converte o que falta, não regenera o que já existe | `wp webp-express flushwebp` seguido de `wp webp-express convert` (ou `convert --reconvert` directo) |
|
||||
| Bulk convert via UI usa qualidade/encoding antigos apesar de ter mudado o form | O bulk convert usa sempre as **últimas definições gravadas** (Save), não o estado não-gravado do formulário | Gravar (Save) antes de disparar "Bulk Convert" |
|
||||
| Metadata (EXIF) desaparece do webp apesar de `metadata: "all"` | `Gd` está a ser o conversor efectivo — Gd não suporta cópia de metadata, ignora sempre a opção | Confirmar qual conversor está `working`/activo antes de assumir que `metadata: "all"` está a ser respeitado |
|
||||
| Alpha quality/near-lossless parecem não ter efeito | Conversor efectivo (`Gd`/`Ewww`) não suporta essas opções — são ignoradas silenciosamente | Confirmar o conversor: near-lossless só em `cwebp`/`vips`; alpha-quality ignorado por `Gd`/`Ewww` |
|
||||
| Selector CSS `div > img` deixa de funcionar depois de activar Alter HTML | `replacement: "picture"` insere um elemento `<picture>` extra entre o `div` e o `img` | Usar selector `div img` (descendente) em vez de `div > img` (filho directo), ou mudar para `replacement: "url"` |
|
||||
|
||||
---
|
||||
|
||||
**Fonte:** `CONFIG-Plugins-Referencia.md` §5 + auditoria ao vivo original em
|
||||
`emanuelalmeida.pt` + expansão nesta sessão com leitura completa do
|
||||
código-fonte: `lib/classes/CLI.php`, `CachePurge.php`, `BulkConvert.php`, e
|
||||
os 43 ficheiros `.inc`/`.php` de `lib/options/options/` (general,
|
||||
conversion-options + converter-options/*.php, redirection-rules,
|
||||
serve-options, alter-html, web-service-options, operation-mode.inc). Config
|
||||
JSON completo (`config.<hash>.json`) lido ao vivo do disco — todas as
|
||||
chaves de topo documentadas em §6 vêm directamente desse ficheiro, não só
|
||||
das que a UI mostra por modo.
|
||||
@@ -0,0 +1,738 @@
|
||||
---
|
||||
name: wordfence
|
||||
description: Auditoria e gestão completa do Wordfence Security via SQL directo em servidores CWP — cobre as 313 chaves de `wfconfig`, a tabela separada `wfls_settings` do módulo Login Security (2FA/passkeys/CAPTCHA/XML-RPC), armazenamento do WAF em ficheiros (`wp-content/wflogs/config*.php`), WAF (modos, categorias de regra, blacklist premium), bloqueio de IPs/países/padrões (UA/referrer/hostname), Live Traffic, os 5 limitadores de Rate Limiting, Diagnostics, Import/Export de config e Wordfence Central. Detecção de IP real atrás do Cloudflare (howGetIPs), scan settings e interacção com plugins de cache. Usar quando "wordfence", "waf wordpress", "firewall wordpress", "2fa wordpress", "passkeys wordpress", "bloqueio de login", "wfconfig", "wfls_settings", "cloudflare real ip wordfence", "howGetIPs", "scan malware wordpress", "brute force wordpress", "rate limiting wordpress", "live traffic wordfence", "wordfence central", "bloqueio de país wordpress".
|
||||
---
|
||||
|
||||
# /wordfence — Auditoria e Configuração Wordfence via SQL
|
||||
|
||||
Gestão do Wordfence Security via `wp db query` directo no servidor CWP.
|
||||
**A configuração NÃO vive toda no mesmo sítio:**
|
||||
- Grosso da config (WAF nível aplicação, scan, alertas, blocking,
|
||||
rate limiting) → tabela própria `wfconfig` (chave/valor, colunas
|
||||
`name`/`val`), **não** `wp_options` — `wp option get/patch` não
|
||||
funciona para nada disto.
|
||||
- 2FA, passkeys, CAPTCHA de login, XML-RPC, "remember device" (módulo
|
||||
Login Security) → tabela **separada** `wfls_settings` (colunas
|
||||
`name`/`value` — nomes de coluna diferentes de `wfconfig`). Ver §6.
|
||||
- Config do motor WAF usada para arrancar antes do WordPress (Extended
|
||||
Protection/auto-prepend) → **ficheiros PHP serializados** em
|
||||
`wp-content/wflogs/config*.php`, fora de qualquer tabela SQL,
|
||||
sincronizados automaticamente a partir de `wfconfig`. Ver §10.
|
||||
|
||||
**Fonte:** `CONFIG-Plugins-Referencia.md` §8 (Wordfence, mapeado
|
||||
16-08-2026, site piloto `emanuelalmeida.pt`, versão `9.0.0` gratuita) +
|
||||
leitura completa do código-fonte do plugin (466 ficheiros PHP) e
|
||||
verificação SQL/SSH ao vivo feitas nesta sessão — detalhe completo da
|
||||
cobertura no rodapé "Fonte" no final do documento.
|
||||
|
||||
---
|
||||
|
||||
## Contexto CWP — sempre obrigatório
|
||||
|
||||
```bash
|
||||
PATH=/home/USER/public_html
|
||||
PREFIX=$(wp db prefix --allow-root --path=$PATH) # ex.: wpne_, wpah_ — nunca assumir wp_
|
||||
```
|
||||
|
||||
**Acesso via SSH:** `server.descomplicar.pt`, porta `9443`, user `root`.
|
||||
Servidor executa comandos como o utilizador do site: `sudo -u USER wp ... --path=$PATH`.
|
||||
|
||||
**Tabela de config real (schema confirmado):**
|
||||
|
||||
```
|
||||
DESCRIBE ${PREFIX}wfconfig;
|
||||
name varchar(100) PRI
|
||||
val longblob -- valor (string, número ou JSON serializado)
|
||||
autoload enum('no','yes')
|
||||
```
|
||||
|
||||
Não há `wp option patch` equivalente — é sempre `SELECT`/`UPDATE` directo
|
||||
sobre `name`/`val`. **313 linhas** de config no site piloto.
|
||||
|
||||
---
|
||||
|
||||
## Decision tree — qual comando usar
|
||||
|
||||
| Operação | Comando |
|
||||
|---|---|
|
||||
| Ler 1 chave de config | `wp db query "SELECT name, val FROM ${PREFIX}wfconfig WHERE name='...';"` |
|
||||
| Ler várias chaves | `SELECT name, val FROM ${PREFIX}wfconfig WHERE name IN (...);` |
|
||||
| Alterar 1 chave (produção) | `UPDATE ${PREFIX}wfconfig SET val='...' WHERE name='...';` — **preferir sempre a UI do wp-admin** para chaves que disparam hooks (`wordfence_changed_ip_source`, `wordfence_changed_license_key`) |
|
||||
| Contar utilizadores com 2FA | `SELECT COUNT(*) FROM ${PREFIX}wfls_2fa_secrets;` (tabela moderna) — **não** `usermeta` (legado, pode ficar desactualizado) |
|
||||
| Ver todas as tabelas do plugin | `SHOW TABLES LIKE '${PREFIX}wf%';` |
|
||||
| Ver issues de scan pendentes | `SELECT COUNT(*) FROM ${PREFIX}wfpendingissues;` |
|
||||
| Ver IPs bloqueados pelo WAF | `SELECT COUNT(*) FROM ${PREFIX}wfblockediplog;` |
|
||||
| Confirmar recomendação de proxy do próprio Wordfence | `SELECT val FROM ${PREFIX}wfconfig WHERE name='detectProxyRecommendation';` |
|
||||
| Ler settings do módulo Login Security (2FA/passkeys/CAPTCHA) | `SELECT name, value FROM ${PREFIX}wfls_settings ORDER BY name;` — **tabela diferente**, colunas `name`/`value` (não `val`) — ver §6 |
|
||||
| Ver ficheiros de config do WAF (bootstrap fora do WordPress) | `cat wp-content/wflogs/config.php` / `config-synced.php` — **não é SQL**, é PHP serializado com `__halt_compiler()` — ver §10 |
|
||||
|
||||
---
|
||||
|
||||
## 1. Auditoria de estado (leitura, sem risco)
|
||||
|
||||
```bash
|
||||
PATH=/home/USER/public_html
|
||||
PREFIX=$(wp db prefix --allow-root --path=$PATH)
|
||||
|
||||
# Estado geral do WAF/firewall
|
||||
wp db query "SELECT name, val FROM ${PREFIX}wfconfig WHERE name IN
|
||||
('firewallEnabled','waf_status','disableWAFIPBlocking','isPaid');" --allow-root --path=$PATH
|
||||
|
||||
# Login security (rate-limit + 2FA)
|
||||
wp db query "SELECT name, val FROM ${PREFIX}wfconfig WHERE name IN
|
||||
('loginSec_maxFailures','loginSec_countFailMins','loginSec_lockoutMins',
|
||||
'loginSec_lockInvalidUsers','allowLegacy2FA','loginSec_requireAdminTwoFactor');" --allow-root --path=$PATH
|
||||
|
||||
# Quantos utilizadores TÊM 2FA activo de facto (tabela moderna do módulo login-security)
|
||||
wp db query "SELECT COUNT(*) AS total_2fa FROM ${PREFIX}wfls_2fa_secrets;" --allow-root --path=$PATH
|
||||
|
||||
# Detecção de IP real (crítico atrás de proxy/CDN)
|
||||
wp db query "SELECT name, val FROM ${PREFIX}wfconfig WHERE name IN
|
||||
('howGetIPs','howGetIPs_trusted_proxies','howGetIPs_trusted_proxy_preset',
|
||||
'detectProxyRecommendation');" --allow-root --path=$PATH
|
||||
|
||||
# Scans activos
|
||||
wp db query "SELECT name, val FROM ${PREFIX}wfconfig WHERE name LIKE 'scansEnabled_%';" --allow-root --path=$PATH
|
||||
|
||||
# Alertas/email
|
||||
wp db query "SELECT name, val FROM ${PREFIX}wfconfig WHERE name IN
|
||||
('alertEmails','email_summary_enabled','liveTrafficEnabled','blockFakeBots','autoUpdate','cacheType');" --allow-root --path=$PATH
|
||||
|
||||
# Volume de actividade (contexto do site)
|
||||
wp db query "SELECT COUNT(*) FROM ${PREFIX}wfblockediplog;" --allow-root --path=$PATH # IPs bloqueados pelo WAF
|
||||
wp db query "SELECT COUNT(*) FROM ${PREFIX}wfpendingissues;" --allow-root --path=$PATH # issues de scan em aberto
|
||||
wp db query "SHOW TABLES LIKE '${PREFIX}wf%';" --allow-root --path=$PATH # inventário de tabelas do plugin
|
||||
```
|
||||
|
||||
### Valores reais confirmados (`emanuelalmeida.pt`, gratuito, 16-08-2026)
|
||||
|
||||
| Chave | Valor | Avaliação |
|
||||
|---|---|---|
|
||||
| `firewallEnabled` | `1` | ✅ |
|
||||
| `waf_status` | `enabled` | ✅ WAF a funcionar |
|
||||
| `disableWAFIPBlocking` | `0` | ✅ bloqueio de IP activo (325 IPs bloqueados no log) |
|
||||
| `isPaid` | vazio | Versão **gratuita** — sem WAF em tempo real (updates de regras com atraso), sem scan de reputação de IP premium |
|
||||
| `alertEmails` | `it@descomplicar.pt` | ✅ |
|
||||
| `email_summary_enabled` | `1` | ✅ |
|
||||
| `liveTrafficEnabled` | `1` | ✅ |
|
||||
| `blockFakeBots` | `1` | ✅ bloqueia falsos Googlebot/etc. |
|
||||
| `autoUpdate` | `1` | ✅ |
|
||||
| `cacheType` | `disabled` | ✅ **deliberado** — ver §4 |
|
||||
| `scansEnabled_core/plugins/themes/malware/diskSpace/suspiciousAdminUsers/wafStatus/...` | todos `1` | ✅ cobertura de scan quase completa |
|
||||
| `scansEnabled_highSense` | `0` | Sensibilidade alta de scan desligada — reduz falsos positivos, aceitável |
|
||||
| `scansEnabled_scanImages` | `0` | Não faz scan binário a imagens — aceitável, baixo risco típico |
|
||||
| `scansEnabled_checkHowGetIPs` | `1` | O próprio Wordfence **já tem um scan check dedicado a esta má-configuração** (ver §3) |
|
||||
| `loginSec_maxFailures` / `_countFailMins` / `_lockoutMins` | `5` / `60` / `240` | Bloqueia ao fim de 5 falhas em 60 min, lockout de 4h |
|
||||
| `loginSec_lockInvalidUsers` | `0` | Não bloqueia por tentar logins com username inexistente (só falhas de password em conta real) |
|
||||
| `allowLegacy2FA` | `0` | ✅ não permite métodos 2FA fracos/antigos |
|
||||
|
||||
---
|
||||
|
||||
## 2. GAP real — 2FA não forçado, zero utilizadores protegidos
|
||||
|
||||
```bash
|
||||
wp db query "SELECT name, val FROM ${PREFIX}wfconfig WHERE name='loginSec_requireAdminTwoFactor';" --allow-root --path=$PATH
|
||||
# → 0 = 2FA NÃO é obrigatório para administradores
|
||||
|
||||
wp db query "SELECT COUNT(*) FROM ${PREFIX}wfls_2fa_secrets;" --allow-root --path=$PATH
|
||||
# → 0 = zero utilizadores com 2FA activo, incluindo o admin
|
||||
```
|
||||
|
||||
**Achado real (`emanuelalmeida.pt`):** `loginSec_requireAdminTwoFactor=0` e
|
||||
**zero** linhas em `wfls_2fa_secrets` — o login continua protegido só por
|
||||
password + rate-limit (5 tentativas/60min/lockout 4h), sem segundo factor,
|
||||
mesmo sendo o site pessoal do fundador da empresa.
|
||||
|
||||
### Forçar 2FA para administradores
|
||||
|
||||
**Auditoria/leitura sempre segura.** Escrita é mutação em produção —
|
||||
confirmar autorização antes de aplicar:
|
||||
|
||||
```bash
|
||||
# Ler estado actual antes de alterar
|
||||
wp db query "SELECT val FROM ${PREFIX}wfconfig WHERE name='loginSec_requireAdminTwoFactor';" --allow-root --path=$PATH
|
||||
|
||||
# Forçar 2FA para o role Administrator
|
||||
wp db query "UPDATE ${PREFIX}wfconfig SET val='1' WHERE name='loginSec_requireAdminTwoFactor';" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
**Cuidado operacional:** activar isto **sem** um administrador já ter um
|
||||
autenticador configurado bloqueia o próprio acesso ao wp-admin no login
|
||||
seguinte (o Wordfence força a configuração do 2FA no momento do login, não
|
||||
tranca por fora — mas confirmar sempre com o utilizador antes, e nunca
|
||||
aplicar em sessão headless sem acesso de recuperação garantido, ex. acesso
|
||||
SSH/SQL directo para reverter o valor para `0` se algo correr mal).
|
||||
|
||||
---
|
||||
|
||||
## 3. GAP real — `howGetIPs` vazio atrás do Cloudflare
|
||||
|
||||
**Este é o achado mais concreto desta auditoria.** O próprio Wordfence já
|
||||
tinha calculado a recomendação correcta e guardado numa chave separada, mas
|
||||
**nunca a aplicou** à chave activa:
|
||||
|
||||
```bash
|
||||
wp db query "SELECT name, val FROM ${PREFIX}wfconfig WHERE name IN
|
||||
('howGetIPs','detectProxyRecommendation');" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
```
|
||||
name val
|
||||
detectProxyRecommendation HTTP_CF_CONNECTING_IP
|
||||
howGetIPs (vazio)
|
||||
```
|
||||
|
||||
`detectProxyRecommendation` é preenchido automaticamente pelo Wordfence
|
||||
quando detecta que o tráfego chega via um proxy conhecido (Cloudflare, neste
|
||||
caso) — mas **fica só como sugestão**; `howGetIPs` (a chave que o WAF
|
||||
realmente usa para decidir qual IP é o "real") continua vazia. Com
|
||||
`howGetIPs` vazio, o Wordfence cai no fallback de ordem de headers
|
||||
(`lib/wfUtils.php`: `HTTP_CF_CONNECTING_IP` → `HTTP_X_REAL_IP` →
|
||||
`REMOTE_ADDR` → `HTTP_X_FORWARDED_FOR`), o que **na maioria dos casos até
|
||||
funciona**, mas não é o comportamento explícito/auditável e não activa o
|
||||
scan check dedicado (`scansEnabled_checkHowGetIPs=1` já está ligado — é
|
||||
precisamente este scan que devia estar a assinalar isto como issue, mas
|
||||
`wfpendingissues` está vazia, i.e. o scan periódico pode não ter corrido
|
||||
recentemente ou o alerta expirou).
|
||||
|
||||
### Valores válidos de `howGetIPs` (confirmado no código, `wfConfig.php`/`wfUtils.php`)
|
||||
|
||||
Cabeçalhos HTTP reconhecidos pelo Wordfence para determinar o IP real:
|
||||
|
||||
| Valor | Quando usar |
|
||||
|---|---|
|
||||
| `HTTP_CF_CONNECTING_IP` | Site atrás de **Cloudflare** — este é o caso do bundle Descomplicar® (todos os sites usam App for Cloudflare®) |
|
||||
| `HTTP_X_REAL_IP` | Proxy tipo nginx reverso simples (sem CDN) |
|
||||
| `HTTP_X_FORWARDED_FOR` | Load balancer/proxy genérico |
|
||||
| (vazio) | `REMOTE_ADDR` directo — só correcto se não houver proxy/CDN nenhum à frente |
|
||||
|
||||
Existe ainda `howGetIPs_trusted_proxy_preset`, que aponta para uma entrada
|
||||
em `ipResolutionList` (JSON de ~8KB, sincronizado da API Wordfence, contém
|
||||
blocos de IP de CDNs conhecidas — ex. `cloudflare`, `cloudfront` — usados
|
||||
para validar que o pedido realmente vem de um proxy confiável antes de
|
||||
aceitar o header). Consultar presets disponíveis:
|
||||
|
||||
```bash
|
||||
wp db query "SELECT val FROM ${PREFIX}wfconfig WHERE name='ipResolutionList';" --allow-root --path=$PATH \
|
||||
| python3 -c "import json,sys; print(list(json.load(sys.stdin).keys()))"
|
||||
```
|
||||
|
||||
### Corrigir (copiar a própria recomendação do Wordfence)
|
||||
|
||||
```bash
|
||||
# Ler antes de escrever
|
||||
wp db query "SELECT val FROM ${PREFIX}wfconfig WHERE name='detectProxyRecommendation';" --allow-root --path=$PATH
|
||||
|
||||
# Aplicar — usa o valor que o próprio Wordfence já recomendou
|
||||
wp db query "UPDATE ${PREFIX}wfconfig SET val='HTTP_CF_CONNECTING_IP' WHERE name='howGetIPs';" --allow-root --path=$PATH
|
||||
|
||||
# Confirmar
|
||||
wp db query "SELECT name, val FROM ${PREFIX}wfconfig WHERE name='howGetIPs';" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
Sem isto configurado, o rate-limiting de login, os bloqueios de IP do WAF e
|
||||
o Live Traffic podem estar a agir sobre o IP do proxy Cloudflare em vez do
|
||||
IP real do atacante — mais grave em sites com muito tráfego atrás do mesmo
|
||||
edge, onde o "IP" observado pode ser partilhado por múltiplos visitantes.
|
||||
|
||||
---
|
||||
|
||||
## 4. Interacção com cache de página — `cacheType=disabled` é deliberado
|
||||
|
||||
```bash
|
||||
wp db query "SELECT val FROM ${PREFIX}wfconfig WHERE name='cacheType';" --allow-root --path=$PATH
|
||||
# → disabled
|
||||
```
|
||||
|
||||
O Wordfence tem o seu próprio sistema de cache de página interno
|
||||
(`Enable Falcon Engine`), mas em sites do bundle Descomplicar® **a cache de
|
||||
página já é feita por outro plugin dedicado** (WP Fastest Cache ou
|
||||
equivalente). `cacheType=disabled` está **correcto** — dois sistemas de
|
||||
cache HTML activos ao mesmo tempo competem, servem versões desalinhadas e
|
||||
dificultam o purge coordenado. **Nunca activar o cache Falcon do Wordfence
|
||||
num site que já tem WP Fastest Cache/WP Meteor a fazer cache de página** —
|
||||
confirmar sempre qual plugin de cache está activo antes de alterar
|
||||
`cacheType` num site novo.
|
||||
|
||||
---
|
||||
|
||||
## 5. Scan settings — cobertura completa
|
||||
|
||||
```bash
|
||||
wp db query "SELECT name, val FROM ${PREFIX}wfconfig WHERE name LIKE 'scansEnabled_%';" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
| Categoria | Chave | Estado (piloto) |
|
||||
|---|---|---|
|
||||
| Core WordPress | `scansEnabled_core`, `_coreUnknown`, `_oldVersions` | `1` |
|
||||
| Plugins/temas | `scansEnabled_plugins`, `_themes` | `1` |
|
||||
| Malware/ficheiros suspeitos | `scansEnabled_malware`, `_fileContents`, `_fileContentsGSB`, `_suspectedFiles` | `1` |
|
||||
| Espaço em disco | `scansEnabled_diskSpace` | `1` |
|
||||
| Utilizadores admin suspeitos | `scansEnabled_suspiciousAdminUsers` | `1` |
|
||||
| Opções de BD suspeitas | `scansEnabled_options`, `_suspiciousOptions` | `1` |
|
||||
| Passwords fracas | `scansEnabled_passwds` | `1` |
|
||||
| Comentários/posts (spam/malware injectado) | `scansEnabled_comments`, `_posts` | `1` |
|
||||
| GeoIP / Google Safe Browsing | `scansEnabled_geoipSupport`, `_checkGSB` | `1` |
|
||||
| Config legível externamente | `scansEnabled_checkReadableConfig` | `1` |
|
||||
| **Detecção de IP mal configurada** | `scansEnabled_checkHowGetIPs` | `1` — ver §3 |
|
||||
| Estado do WAF | `scansEnabled_wafStatus` | `1` |
|
||||
| WPScan (directory listing, full path disclosure) | `scansEnabled_wpscan_directoryListingEnabled`, `_wpscan_fullPathDisclosure` | `1` |
|
||||
| Sensibilidade alta | `scansEnabled_highSense` | `0` (desligado, reduz falsos positivos) |
|
||||
| Scan binário de imagens | `scansEnabled_scanImages` | `0` (desligado) |
|
||||
|
||||
**Avaliação:** cobertura de scan quase total (23 de 25 checks activos),
|
||||
única omissão relevante é a sensibilidade alta — aceitável para reduzir
|
||||
ruído em sites com actividade legítima elevada.
|
||||
|
||||
---
|
||||
|
||||
## 6. Two-Factor / Passkeys / CAPTCHA — tabela SEPARADA `wfls_settings`
|
||||
|
||||
**Achado arquitectural importante desta expansão:** o módulo "Login
|
||||
Security" (2FA, passkeys, CAPTCHA de login, XML-RPC, "remember device",
|
||||
integração WooCommerce, NTP) **não guarda a sua configuração em
|
||||
`wfconfig`** — vive numa tabela própria, `wfls_settings`, gerida pela
|
||||
classe `WordfenceLS\Controller_Settings` (código em
|
||||
`modules/login-security/classes/controller/settings.php`). Schema:
|
||||
|
||||
```
|
||||
DESCRIBE ${PREFIX}wfls_settings;
|
||||
name varchar(191) PRI
|
||||
value longtext -- nota: coluna chama-se "value", não "val"
|
||||
autoload enum('no','yes')
|
||||
```
|
||||
|
||||
```bash
|
||||
wp db query "SELECT name, value FROM ${PREFIX}wfls_settings ORDER BY name;" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
As chaves `loginSec_requireAdminTwoFactor` e `loginSec_enableSeparateTwoFactor`
|
||||
em `wfconfig` (§2) são a versão **legada** — um switch global único. A
|
||||
versão actual do plugin é **baseada em papéis (roles)**:
|
||||
`migrate_admin_2fa_requirements_to_roles()` migra o switch legado para
|
||||
chaves por role (`required-2fa-role.<role>`) dentro de `wfls_settings` e
|
||||
depois apaga a chave legada do `wfconfig`. Um site "antigo" pode ainda ter
|
||||
o valor legado; um site já migrado tem-no ausente/zero e a fonte de
|
||||
verdade passa a ser `wfls_settings` + capabilities.
|
||||
|
||||
### Chaves confirmadas em `wfls_settings` (`emanuelalmeida.pt`)
|
||||
|
||||
| Chave | Valor confirmado | O que controla |
|
||||
|---|---|---|
|
||||
| `xmlrpc-enabled` | `1` | Exigir 2FA também em pedidos XML-RPC autenticados |
|
||||
| `allow-xml-rpc` | `1` | Permitir XML-RPC de todo (independente do 2FA) |
|
||||
| `ip-source` | vazio (`automatic`) | Fonte do IP real para o módulo login-security — **independente** de `howGetIPs` do `wfconfig` (§3); valores: `automatic`, `REMOTE_ADDR`, `X-Forwarded-For`, `X-Real-IP` |
|
||||
| `ip-trusted-proxies` | vazio | Lista de proxies confiáveis (newline-separated) para o cálculo de IP deste módulo |
|
||||
| `2fa-user-grace-period` | `10` | Dias de período de graça depois de 2FA se tornar obrigatório por role, antes de bloquear o login |
|
||||
| `require-2fa.administrator` | vazio | Legado (ver acima); use `required-2fa-role.administrator` |
|
||||
| `passkey-sign-count-mode` | `reject-lower` | Política anti-clonagem de passkeys: `allow` / `reject-lower` / `reject-lower-and-zero` |
|
||||
| `passkey-relying-party-override` | vazio | Override do hostname RP para passkeys (multi-domínio) |
|
||||
| `remember-device` | vazio (`false`) | "Lembrar este dispositivo" para saltar 2FA X dias |
|
||||
| `remember-device-duration` | `2592000` (30 dias) | Duração do "remember device" em segundos |
|
||||
| `always-show-login-security-menu` | `1` | Mostrar sempre o menu Login Security mesmo sem nada configurado |
|
||||
| `enable-auth-captcha` | vazio | CAPTCHA (reCAPTCHA) no formulário de login |
|
||||
| `recaptcha-site-key` / `recaptcha-secret` | vazio | Credenciais reCAPTCHA — só relevantes se `enable-auth-captcha=1` |
|
||||
| `recaptcha-threshold` | `0.5` | Limiar de pontuação do reCAPTCHA v3 (0–1) |
|
||||
| `enable-woocommerce-integration` / `-account-integration` | vazio | Aplicar 2FA/passkeys também na área de conta WooCommerce |
|
||||
| `use-ntp` | `1` | Sincronizar relógio via NTP para códigos TOTP (evita drift do relógio do servidor) |
|
||||
| `whitelisted` | vazio | IPs isentos de exigência de 2FA (não confundir com `whitelisted` do `wfconfig`, que é do WAF) |
|
||||
| `schema-version` | `3` | Versão do schema interno do módulo — não editar manualmente |
|
||||
|
||||
### Modelo de permissões por role (capabilities, não settings)
|
||||
|
||||
"2FA obrigatório" e "2FA opcional" por role **não** são uma chave de
|
||||
configuração simples — são geridos como **capabilities** do WordPress,
|
||||
sincronizadas por `WordfenceLS\Controller_Permissions`:
|
||||
|
||||
| Capability | Significado |
|
||||
|---|---|
|
||||
| `wf2fa_activate_2fa_self` | O utilizador pode activar/desactivar 2FA na própria conta |
|
||||
| `wf2fa_activate_2fa_others` | Pode activar/desactivar 2FA de outros utilizadores |
|
||||
| `wf2fa_manage_settings` | Pode editar as definições do módulo Login Security |
|
||||
| `wfls_manage_passkey_self` / `_others` | Equivalente para passkeys |
|
||||
| `wfls_show_login_security` | Capability interna que mostra/esconde o menu (sincronizada automaticamente) |
|
||||
|
||||
```bash
|
||||
wp eval 'var_export(get_role("administrator")->capabilities);' --allow-root --path=$PATH | grep -i 'wf2fa\|wfls'
|
||||
# Confirmado em emanuelalmeida.pt: administrator TEM wf2fa_activate_2fa_self (pode activar),
|
||||
# mas isso é OPCIONAL — só se torna obrigatório se required-2fa-role.administrator tiver timestamp > -1
|
||||
```
|
||||
|
||||
O estado "obrigatório desde quando" fica em `required-2fa-role.<role>`
|
||||
(timestamp Unix) ou `-1` (não obrigatório) — chave dinâmica dentro de
|
||||
`wfls_settings`, não aparece na lista de defaults porque só existe depois
|
||||
de alguém a definir pela UI.
|
||||
|
||||
### Tabelas de dados do módulo (não config, mas relevantes para auditoria)
|
||||
|
||||
| Tabela | Conteúdo |
|
||||
|---|---|
|
||||
| `wfls_2fa_secrets` | Segredos TOTP activos por utilizador (contagem = utilizadores com 2FA activo) |
|
||||
| `wfls_passkeys` | Passkeys (WebAuthn) registadas por utilizador |
|
||||
| `wfls_role_counts` | Cache de contagens de utilizadores por role, usada pela UI |
|
||||
|
||||
---
|
||||
|
||||
## 7. Live Traffic — configuração completa
|
||||
|
||||
Todas as chaves vivem em `wfconfig` (ao contrário do módulo 2FA). Tabela
|
||||
de dados: `wflivetraffichuman` (visitas humanas) + `wfhits`, `wfhoover`,
|
||||
`wfcrawlers`, `wflocs`, `wflogins` (dados de suporte ao Live Traffic e ao
|
||||
dashboard de tráfego).
|
||||
|
||||
| Chave | Valor (piloto) | O que controla |
|
||||
|---|---|---|
|
||||
| `liveTrafficEnabled` | `1` | Liga/desliga o registo de Live Traffic |
|
||||
| `liveTraf_ignorePublishers` | `1` | Não regista visitas de utilizadores autenticados com capacidade de publicar (reduz ruído do próprio staff) |
|
||||
| `liveTraf_ignoreUsers` | vazio | Lista de usernames (separados por vírgula) a ignorar |
|
||||
| `liveTraf_ignoreIPs` | vazio | Lista de IPs (separados por vírgula) a ignorar |
|
||||
| `liveTraf_ignoreUA` | vazio | User-agent a ignorar (substring) |
|
||||
| `liveTraf_maxRows` | `2000` | Quantidade máxima de registos guardados |
|
||||
| `liveTraf_maxAge` | `30` | Dias máximos de retenção dos registos |
|
||||
| `liveTraf_displayExpandedRecords` | `0` | Preferência de UI (registos expandidos por omissão) — não afecta captura |
|
||||
|
||||
**Overrides que desligam Live Traffic independentemente da config:**
|
||||
`wfConfig::liveTrafficEnabled()` força `false` se a constante
|
||||
`WORDFENCE_DISABLE_LIVE_TRAFFIC` estiver definida, ou se
|
||||
`WF_IS_WP_ENGINE` for verdadeiro (hosts WP Engine desactivam sempre este
|
||||
módulo, independentemente do valor em `wfconfig`) — útil para explicar a
|
||||
um cliente porque "liguei e não aparece nada" nesse tipo de hosting.
|
||||
|
||||
```bash
|
||||
wp db query "SELECT name, val FROM ${PREFIX}wfconfig WHERE name LIKE 'liveTraf%' OR name='liveTrafficEnabled';" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Blocking completo — País, IP manual, Padrões (UA/Referrer/Hostname)
|
||||
|
||||
Todos os bloqueios (manuais e automáticos) vivem numa única tabela,
|
||||
`wfBlocks7` (não em `wfconfig`), com um campo `type` que distingue a
|
||||
natureza do bloqueio (`models/block/wfBlock.php`):
|
||||
|
||||
| Constante | Valor | Origem |
|
||||
|---|---|---|
|
||||
| `TYPE_IP_MANUAL` | 1 | Bloqueio de IP manual pelo admin |
|
||||
| `TYPE_WFSN_TEMPORARY` | 2 | Resposta automática da Wordfence Security Network (rede partilhada entre sites) |
|
||||
| `TYPE_COUNTRY` | 3 | Bloqueio por país |
|
||||
| `TYPE_PATTERN` | 4 | Bloqueio avançado (IP range + hostname + user-agent + referrer) |
|
||||
| `TYPE_RATE_BLOCK` | 5 | Gerado pelo rate limiting (§9), acção `block` |
|
||||
| `TYPE_RATE_THROTTLE` | 6 | Gerado pelo rate limiting (§9), acção `throttle` |
|
||||
| `TYPE_LOCKOUT` | 7 | Lockout de login (falhas de password/2FA) |
|
||||
| `TYPE_IP_AUTOMATIC_TEMPORARY` / `_PERMANENT` | 8 / 9 | Bloqueios automáticos do WAF, temporário vs promovido a permanente por acção do admin |
|
||||
|
||||
```bash
|
||||
# Ver todos os bloqueios activos por tipo
|
||||
wp db query "SELECT type, COUNT(*) FROM ${PREFIX}wfblocks7 WHERE expiration=0 OR expiration>UNIX_TIMESTAMP() GROUP BY type;" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
### Bloqueio por país
|
||||
|
||||
Campos guardados em `parameters` (JSON): `blockLogin` (bloquear só a
|
||||
página de login), `blockSite` (bloquear o resto do site), `countries`
|
||||
(array de códigos ISO). Comportamento configurado globalmente em
|
||||
`wfconfig`:
|
||||
|
||||
| Chave | Valor (piloto) | O que controla |
|
||||
|---|---|---|
|
||||
| `cbl_action` | `block` | O que fazer a um país bloqueado: `block` (503) ou `redirect` (redireccionar) |
|
||||
| `cbl_redirURL` | vazio | URL de destino se `cbl_action=redirect` |
|
||||
| `cbl_loggedInBlocked` | `0` | Bloquear país mesmo que o visitante já tenha sessão iniciada |
|
||||
| `cbl_bypassRedirURL` / `cbl_bypassRedirDest` | vazio | Um visitante de país bloqueado que aceda a este URL relativo é reencaminhado e recebe um cookie de bypass permanente |
|
||||
| `cbl_bypassViewURL` | vazio | Um visitante permitido que veja este URL relativo recebe o cookie de bypass antecipadamente (para o caso de mudar de país/VPN depois) |
|
||||
| `cbl_cookieVal` | gerado automaticamente | Valor único do cookie de bypass — regenerar invalida bypasses concedidos |
|
||||
|
||||
Nenhum destes está configurado no piloto (site sem bloqueio de país
|
||||
activo) — confirmar sempre `hasCountryBlock()`/`countryBlocks()` antes de
|
||||
assumir que não há impacto em visitantes internacionais.
|
||||
|
||||
### Bloqueio manual de IP / IP range
|
||||
|
||||
```bash
|
||||
# Confirmar que um IP não está na whitelist antes de o bloquear (a UI faz isto automaticamente)
|
||||
wp db query "SELECT val FROM ${PREFIX}wfconfig WHERE name='whitelisted';" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
`wfBlock::isWhitelisted()` verifica dois níveis: a lista manual em
|
||||
`whitelisted` (`wfconfig`, uma entrada por linha, IP/CIDR) e uma lista de
|
||||
serviços conhecidos (`whitelistedServices`, JSON — vazio `{}` no piloto;
|
||||
quando preenchido guarda ranges de IP de serviços como monitorização
|
||||
externa que o Wordfence nunca bloqueia mesmo com regras activas).
|
||||
|
||||
### Bloqueio avançado (Custom Pattern) — hostname / user-agent / referrer
|
||||
|
||||
Bloqueio combinável por 4 critérios (pelo menos 1 obrigatório),
|
||||
`type=custom-pattern` na validação (`wfBlock::validate()`):
|
||||
|
||||
| Campo | Formato | Exemplo de uso |
|
||||
|---|---|---|
|
||||
| `ipRange` | IP único, CIDR, ou range `1.2.3.4-1.2.3.9` (IPv4 e IPv6 não podem misturar-se no mesmo bloqueio) | Bloquear uma subnet inteira |
|
||||
| `hostname` | wildcard `*` e `.` (regex `^[a-z0-9\.\*\-]+$`) | Bloquear por reverse-DNS de um datacenter conhecido |
|
||||
| `userAgent` | substring livre | Bloquear scrapers com UA identificável |
|
||||
| `referrer` | substring livre | Bloquear tráfego de referrer spam |
|
||||
|
||||
```bash
|
||||
wp db query "SELECT id, blockedTime, reason, expiration FROM ${PREFIX}wfblocks7 WHERE type=4 AND (expiration=0 OR expiration>UNIX_TIMESTAMP());" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
### Como o Wordfence decide não bloquear crawlers do Google
|
||||
|
||||
```bash
|
||||
wp db query "SELECT val FROM ${PREFIX}wfconfig WHERE name='neverBlockBG';" --allow-root --path=$PATH
|
||||
# Confirmado no piloto: neverBlockVerified
|
||||
```
|
||||
|
||||
| Valor de `neverBlockBG` | Comportamento |
|
||||
|---|---|
|
||||
| `neverBlockVerified` (default, activo no piloto) | Verifica UA **e** faz PTR/reverse-DNS lookup para confirmar que é mesmo um IP do Google antes de isentar de bloqueio |
|
||||
| `neverBlockUA` | Confia só no User-Agent, sem verificação de IP — menos seguro (fácil de fingir), mas mais barato |
|
||||
| `treatAsOtherCrawlers` | Não dá tratamento especial a "Google" — pode ser bloqueado como qualquer outro crawler |
|
||||
|
||||
---
|
||||
|
||||
## 9. Rate Limiting completo — 5 tipos, `throttle` vs `block`
|
||||
|
||||
`models/block/wfRateLimit.php` define **5 limitadores independentes**,
|
||||
cada um com um par de chaves `<nome>` (limiar) + `<nome>_action`
|
||||
(`throttle` ou `block`). `DISABLED` como valor do limiar desactiva esse
|
||||
limitador especificamente.
|
||||
|
||||
| Limitador | Chave limiar | Chave acção | Valor confirmado (piloto) | Aplica-se a |
|
||||
|---|---|---|---|---|
|
||||
| Global | `maxGlobalRequests` | `maxGlobalRequests_action` | `240` / `throttle` | **Qualquer** pedido, humano ou crawler — se activo, sobrepõe-se aos outros 4 |
|
||||
| Page views de crawlers | `maxRequestsCrawlers` | `maxRequestsCrawlers_action` | `DISABLED` / `throttle` | Só User-Agents identificados como crawler (`wfCrawl::isCrawler`) |
|
||||
| 404s de crawlers | `max404Crawlers` | `max404Crawlers_action` | `60` / `throttle` | Idem, mas só páginas 404 |
|
||||
| Page views de humanos | `maxRequestsHumans` | `maxRequestsHumans_action` | `DISABLED` / `throttle` | Visitantes não identificados como crawler |
|
||||
| 404s de humanos | `max404Humans` | `max404Humans_action` | `60` / `throttle` | Idem, mas só páginas 404 |
|
||||
|
||||
```bash
|
||||
wp db query "SELECT name, val FROM ${PREFIX}wfconfig WHERE name LIKE 'max%Requests%' OR name LIKE 'max404%' OR name='blockedTime';" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
**No piloto, o rate limit global (`maxGlobalRequests=240`) está
|
||||
ACTIVO** — qualquer IP (humano ou bot) que exceda 240 pedidos na janela
|
||||
de 1 minuto (tabela `wfTrafficRates`, campo `eMin`) é afectado. Os
|
||||
limitadores dedicados a crawlers/humanos de page views estão desligados;
|
||||
só os de 404 (60 num minuto) estão activos, o que é uma configuração
|
||||
razoável (protege contra scans de 404 sem penalizar navegação normal).
|
||||
|
||||
**`throttle` vs `block` não são só rótulos — têm durações e severidade
|
||||
diferentes:**
|
||||
|
||||
- `throttle` → `wfBlock::createRateThrottle()`, duração **fixa de 60
|
||||
segundos** (`wfRateLimit::rateLimitThrottleDuration()`) — resposta 503
|
||||
temporária, o visitante volta a conseguir aceder ao fim de 1 minuto.
|
||||
- `block` → `wfBlock::createRateBlock()`, duração = `blockedTime`
|
||||
(`wfconfig`, **300s / 5 min no piloto**, configurável) — bloqueio mais
|
||||
longo, e pode ser promovido a permanente manualmente pelo admin na UI
|
||||
de Blocking (`TYPE_RATE_BLOCK` → `TYPE_IP_AUTOMATIC_PERMANENT`).
|
||||
|
||||
**Excepção comum a 404s permitidos:** `allowed404s` (`wfconfig`, uma
|
||||
entrada por linha, suporta wildcard `*`) — URLs que nunca contam para os
|
||||
limitadores de 404, mesmo que devolvam 404 de facto. Default do piloto:
|
||||
`/favicon.ico`, `/apple-touch-icon*.png`, `/*@2x.png`,
|
||||
`/browserconfig.xml` (ícones/manifestos pedidos por browsers que geram
|
||||
404 legítimos e não devem disparar rate limiting).
|
||||
|
||||
---
|
||||
|
||||
## 10. WAF — arquitectura de armazenamento, modos e categorias de regra
|
||||
|
||||
**Achado arquitectural crítico:** para o WAF funcionar *antes* do
|
||||
WordPress carregar (Extended Protection / auto-prepend), o Wordfence
|
||||
**não pode depender só da base de dados** — mantém uma cópia da config
|
||||
relevante em ficheiros PHP no filesystem, fora de `wp_content/plugins`:
|
||||
|
||||
```bash
|
||||
ls -la wp-content/wflogs/
|
||||
# config.php — config nuclear do WAF (wafStatus, authKey, versão do formato) — 6 chaves só
|
||||
# config-synced.php — MIRROR de chaves relevantes do wfconfig + bloqueios activos, sincronizado
|
||||
# sempre que algo muda (país/IP/pattern blocks, howGetIPs, apiKey, etc.)
|
||||
# config-livewaf.php — config activa/em uso pelo processo WAF autoprepended
|
||||
# config-transient.php— cache de dados de ataque (grande, ~1.7 MB no piloto)
|
||||
# rules.php — ficheiro PHP executável (não serializado) com as regras do WAF, incluído
|
||||
# directamente no bootstrap; NÃO editar/apagar manualmente
|
||||
# attack-data.php, ips.php — logs internos de ataques/IPs vistos pelo WAF
|
||||
```
|
||||
|
||||
Estes ficheiros começam com `<?php exit('Access denied');
|
||||
__halt_compiler(); ?>` seguido de dados serializados em PHP — só são
|
||||
legíveis fazendo `substr()` a partir do offset de `__halt_compiler()` e
|
||||
`unserialize()`. **Nunca editar estes ficheiros manualmente**; qualquer
|
||||
alteração de config deve passar pela UI ou por `wfconfig`, que depois é
|
||||
sincronizada automaticamente para estes ficheiros (via
|
||||
`wfWAFIPBlocksController::setNeedsSynchronizeConfigSettings()`, chamado
|
||||
sempre que `wfBlock::create*()` corre).
|
||||
|
||||
O motor de armazenamento é escolhido por `WFWAF_STORAGE_ENGINE`
|
||||
(`waf/bootstrap.php`): **`file`** por omissão (confirmado no piloto —
|
||||
ficheiros em `wflogs/` existem e têm conteúdo recente), ou **`mysqli`**
|
||||
forçado automaticamente em hosts WP Engine/Flywheel (ou por constante
|
||||
explícita), caso em que a config do WAF passa a viver numa ligação MySQL
|
||||
directa (bypass ao `$wpdb`) em vez de ficheiros.
|
||||
|
||||
### Modos e níveis do WAF (`models/firewall/wfFirewall.php`)
|
||||
|
||||
| Constante | Valores possíveis | Significado |
|
||||
|---|---|---|
|
||||
| `firewallMode()` | `disabled` / `learning-mode` / `enabled` | Estado geral; **`enabled`** no piloto (§1, `waf_status`) |
|
||||
| `protectionMode()` | `basic` / `extended` | `extended` requer `WFWAF_AUTO_PREPEND` activo (ficheiro `.user.ini`/`.htaccess` a fazer `auto_prepend_file` para `wordfence-waf.php` antes do WordPress arrancar) — sem isto, o WAF só corre depois do `muplugins_loaded`, mais tarde no ciclo, "Basic Protection" |
|
||||
| `ruleMode()` | `community` / `premium` | Depende de `isPaid` — piloto usa feed `community` (regras com atraso de propagação face a sites Premium) |
|
||||
| `blacklistMode()` | `disabled` / `enabled` | "Real-Time IP Blocklist" — **só disponível com `isPaid`**, mesmo que `disableWAFBlacklistBlocking=0` |
|
||||
| `learningModeStatus()` | `false` / `true` / timestamp | Se em Learning Mode, indica se há mudança automática agendada para Enabled (`learningModeGracePeriodEnabled` + `learningModeGracePeriod`) |
|
||||
|
||||
### Categorias de regra (fail-score) — confirmado no `rules.php` do piloto
|
||||
|
||||
O motor de regras usa 3 categorias de ataque com pontuação de risco
|
||||
própria (`$this->failScores[...]` em `wflogs/rules.php`):
|
||||
|
||||
```bash
|
||||
ssh server "grep -o \"failScores\\['[a-z]*'\\]\" .../wp-content/wflogs/rules.php | sort -u"
|
||||
# failScores['rce'] — Remote Code Execution
|
||||
# failScores['sqli'] — SQL Injection
|
||||
# failScores['xss'] — Cross-Site Scripting
|
||||
```
|
||||
|
||||
Regras individuais podem ser desactivadas via `disabledRules` — essa
|
||||
chave vive **dentro do storage do WAF** (`wp-content/wflogs/config.php`
|
||||
no motor `file`), não em `wfconfig`; o piloto não tem nenhuma regra
|
||||
desactivada (chave ausente = todas activas). A "pontuação de segurança"
|
||||
mostrada no Dashboard (`wfFirewall::overallStatus()`) combina: % de
|
||||
regras activas (35%), blacklist premium activa (35%), Extended Protection
|
||||
(20%), Rate Limiting/Advanced Blocking ligado (10%) — pesado a favor do
|
||||
WAF (80% do total), com brute-force protection a contar só 20%.
|
||||
|
||||
---
|
||||
|
||||
## 11. Diagnostics (Tools → Diagnostics)
|
||||
|
||||
Gerado por `lib/wfDiagnostic.php`, sem persistência em BD — é sempre
|
||||
calculado on-demand quando a página carrega. Secções e o que cada uma
|
||||
verifica:
|
||||
|
||||
| Secção | O que reporta |
|
||||
|---|---|
|
||||
| Wordfence Status | Versão instalada, versão da base GeoIP, jobs de cron em atraso (>30min) |
|
||||
| Filesystem | Se o webserver consegue ler/escrever `wp-content/plugins/wordfence` e `wp-content/wflogs` |
|
||||
| Wordfence Config | Teste de escrita/leitura real contra `wfconfig` (básico e serializado) — falha aqui = sem permissões de escrita na tabela |
|
||||
| Wordfence Firewall | Auto-prepend activo, motor de storage configurado vs activo, path dos logs, permissões de ficheiros, conteúdo de `.htaccess`/`.user.ini` relacionado com o WAF |
|
||||
| MySQL | Versão do MySQL + privilégios reais do utilizador da BD: `SELECT`/`INSERT`/`UPDATE`/`DELETE`/`CREATE`/`ALTER`/`DROP`/`TRUNCATE` (via `SHOW GRANTS FOR current_user()`) |
|
||||
| PHP Environment | Versão PHP vs mínimo suportado, dono do processo PHP, suporte OpenSSL/cURL (versões, protocolos), `display_errors` |
|
||||
| Connectivity | Ligação de saída a servidores Wordfence (https), ligação de volta ao próprio site (IPv4 e IPv6 — útil para detectar Cloudflare a bloquear o próprio site) |
|
||||
| Time | Hora da rede Wordfence, hora do servidor, offset NTP, fonte de tempo usada para TOTP (2FA), fuso horário do WordPress |
|
||||
|
||||
**Casos de uso práticos:**
|
||||
- `userCanAlter`/`userCanDrop` a `false` → migrações/upgrades do plugin
|
||||
podem falhar silenciosamente; verificar antes de reportar "scan não
|
||||
actualiza issues".
|
||||
- `connectToSelf`/`connectToSelfIpv6` a falhar com sinais de Cloudflare
|
||||
(`cf-mitigated: challenge`, `Cloudflare Ray ID` no body) → o próprio
|
||||
Cloudflare está a desafiar o loopback request do Wordfence; relevante
|
||||
para sites do bundle Descomplicar® (todos atrás de Cloudflare via
|
||||
App for Cloudflare®) em diagnóstico de scans que nunca terminam.
|
||||
- A secção "WordPress" (via `wfDiagnostic::getWordpressValues()`, não
|
||||
listada acima por ser genérica ao core) expõe constantes como
|
||||
`WP_DEBUG`, `DISALLOW_FILE_EDIT`, `WP_CACHE`, `FORCE_SSL_ADMIN` — útil
|
||||
para confirmar hardening sem abrir `wp-config.php` directamente.
|
||||
|
||||
---
|
||||
|
||||
## 12. Tools → Import/Export de configuração
|
||||
|
||||
**Não é um ficheiro local** (ao contrário de outros plugins do bundle) —
|
||||
`wfImportExportController` (`lib/wfImportExportController.php`) faz
|
||||
`export()`/`import()` **através da API do wordfence.com**: o export
|
||||
gera um token remoto (`export_options`), que depois se cola manualmente
|
||||
no site de destino (`import_options` + token). Isto exige que ambos os
|
||||
sites tenham `apiKey` válida e liguem para fora ao wordfence.com — não
|
||||
funciona offline nem é um download/upload de ficheiro local.
|
||||
|
||||
O que é exportado: todas as `wfConfig::getExportableOptionsKeys()`
|
||||
(essencialmente os grupos `checkboxes` + `otherParams` do
|
||||
`$defaultConfig`, não o grupo `defaultsOnly`), o agendamento de scans
|
||||
(`scanSched`, serializado), e todos os registos da tabela de bloqueios
|
||||
(`wfBlock::exportBlocks()` — inclui bloqueios de país, IP e pattern, mas
|
||||
não lockouts nem bloqueios automáticos temporários).
|
||||
|
||||
**Não é adequado para "clonar config para outro site" via SQL directo**
|
||||
(copiar a tabela `wfconfig` entre sites não é suportado oficialmente e
|
||||
arrasta chaves específicas da instalação como `encKey`/`longEncKey` —
|
||||
preferir sempre o fluxo de token oficial acima ou reconfigurar via UI).
|
||||
|
||||
---
|
||||
|
||||
## 13. Wordfence Central — gestão remota multi-site
|
||||
|
||||
```bash
|
||||
wp db query "SELECT name, val FROM ${PREFIX}wfconfig WHERE name LIKE 'wordfenceCentral%';" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
**Achado confirmado no piloto: este site ESTÁ ligado ao Wordfence
|
||||
Central** (`wordfenceCentralConnected=1`), associado a
|
||||
`it@descomplicar.pt` desde 27/02/2025
|
||||
(`wordfenceCentralConnectTime=1740679066`), com um `wordfenceCentralSiteID`
|
||||
próprio (UUID). Central é a consola de gestão remota multi-site do
|
||||
Wordfence (central.wordfence.com) — permite monitorizar/alertar e (em
|
||||
planos pagos) configurar Wordfence em vários sites a partir de um único
|
||||
painel, autenticado via JWT (`wordfenceCentralAccessToken`,
|
||||
`wordfenceCentralUserSiteAccessToken`) trocado através de um par de
|
||||
chaves pública/privada gerado no site (`wordfenceCentralPK`,
|
||||
`wordfenceCentralSecretKey`).
|
||||
|
||||
| Chave relevante | O que é |
|
||||
|---|---|
|
||||
| `wordfenceCentralConnected` | `1`/`0` — liga/desliga a integração |
|
||||
| `wordfenceCentralConnectEmail` / `_ConnectTime` | Quem ligou e quando |
|
||||
| `wordfenceCentralPluginAlertingDisabled` | Se `1`, silencia alertas duplicados no próprio wp-admin porque já chegam via Central |
|
||||
| `wordfenceCentralConfigurationIssue` | Flag interna — `1` indica falha na renovação do token JWT, útil para diagnosticar "Central parou de reportar" |
|
||||
| `wordfenceCentralSiteData` | Cache JSON da última resposta da API Central sobre este site |
|
||||
|
||||
**Widget do dashboard nativo do WordPress:**
|
||||
`email_summary_dashboard_widget_enabled` (`wfconfig`, `1` no piloto)
|
||||
controla o widget "Activity Report" no `/wp-admin/index.php` (WordPress
|
||||
Dashboard nativo) — **não confundir** com o próprio Dashboard do
|
||||
Wordfence (`/wp-admin/admin.php?page=Wordfence`, componente Vue sem
|
||||
chave de config individual para mostrar/esconder secções).
|
||||
|
||||
---
|
||||
|
||||
## Gotchas / erros comuns
|
||||
|
||||
| Sintoma | Causa | Solução |
|
||||
|---|---|---|
|
||||
| `wp option get wordfence_...` devolve vazio/erro | Config do Wordfence não vive em `wp_options` | Usar sempre `wp db query` contra `${PREFIX}wfconfig` (colunas `name`/`val`) |
|
||||
| `SELECT value FROM wfconfig` falha (`Unknown column 'value'`) | A coluna chama-se `val`, não `value` | `SELECT name, val FROM ${PREFIX}wfconfig` |
|
||||
| Contagem de 2FA por `usermeta.meta_key='wordfence_2fa_secret'` parece desactualizada | Essa é a chave legada; o módulo login-security moderno guarda em tabela própria | Preferir `SELECT COUNT(*) FROM ${PREFIX}wfls_2fa_secrets` |
|
||||
| `howGetIPs` vazio mas o site parece "funcionar" na mesma | O Wordfence tem fallback de ordem de headers (`HTTP_CF_CONNECTING_IP` → `HTTP_X_REAL_IP` → `REMOTE_ADDR` → `HTTP_X_FORWARDED_FOR`) — mascara o problema em vez de o resolver | Configurar explicitamente `howGetIPs`, não confiar no fallback silencioso |
|
||||
| `wfpendingissues` vazia mesmo com `scansEnabled_checkHowGetIPs=1` e `howGetIPs` mal configurado | O scan periódico pode não ter corrido recentemente, ou o alerta já expirou/foi dispensado | Não usar `wfpendingissues` vazia como prova de "nada errado" — cruzar sempre com leitura directa da config |
|
||||
| Activar `loginSec_requireAdminTwoFactor` sem aviso prévio | Bloqueia o fluxo normal de login até o admin configurar um autenticador | Confirmar com o utilizador antes; garantir acesso alternativo (SSH/SQL) para reverter |
|
||||
| Prefixo de tabela assumido como `wp_` | Sites CWP podem ter prefixo custom (confirmado `wpne_` no piloto) | `wp db prefix --allow-root --path=$PATH` sempre primeiro |
|
||||
| Editar 2FA/passkeys/CAPTCHA via `UPDATE ${PREFIX}wfconfig` sem efeito | Essas definições vivem em `wfls_settings` (colunas `name`/`value`, não `name`/`val`) — ver §6 | `UPDATE ${PREFIX}wfls_settings SET value='...' WHERE name='...';` |
|
||||
| Editar regras/bloqueios do WAF directamente em `wp-content/wflogs/*.php` | São ficheiros PHP serializados com `__halt_compiler()`, regenerados a partir da BD — editar à mão desalinha-os da BD e pode partir o WAF | Alterar sempre via `wfconfig`/UI; a sincronização para ficheiro é automática (§10) |
|
||||
| Achar que `loginSec_requireAdminTwoFactor=0` prova que 2FA nunca é obrigatório | Essa chave é legada; sites migrados usam `required-2fa-role.<role>` dentro de `wfls_settings` | Verificar sempre `required-2fa-role.*` e as capabilities `wf2fa_*` do role antes de concluir (§6) |
|
||||
| Assumir que `maxRequestsHumans`/`maxRequestsCrawlers`="DISABLED" significa "sem rate limiting nenhum" | Cada um dos 5 limitadores (§9) é independente — `maxGlobalRequests` pode estar activo e a aplicar-se a toda a gente mesmo com os outros 4 desligados | Verificar sempre os 5 pares `<limite>`/`<limite>_action`, não só um |
|
||||
|
||||
---
|
||||
|
||||
*Fonte: `CONFIG-Plugins-Referencia.md` §8 (Wordfence) + verificação
|
||||
SQL/SSH ao vivo em `emanuelalmeida.pt` (16-08-2026, WP 7.0.4/PHP 8.2.31,
|
||||
Wordfence 9.0.0 gratuito) — schema de `wfconfig` (313 chaves confirmadas
|
||||
via `SELECT DISTINCT name`), contagem real de 2FA/passkeys,
|
||||
`detectProxyRecommendation`, valores de scan e login security. **Expandido
|
||||
nesta sessão** com leitura completa do código-fonte do plugin (466
|
||||
ficheiros PHP, ~147k linhas) — `lib/wfConfig.php` (schema completo de
|
||||
defaults, 3 grupos: `checkboxes`/`otherParams`/`defaultsOnly`),
|
||||
`lib/wfJavascriptBridge.php` (labels humanos de todas as opções da UI),
|
||||
`models/block/wfBlock.php` e `wfRateLimit.php` (tipos de bloqueio e os 5
|
||||
limitadores de rate limiting), `models/firewall/wfFirewall.php` (modos e
|
||||
scoring do WAF), `lib/wfDiagnostic.php` (secções de diagnóstico),
|
||||
`lib/wfImportExportController.php` (mecanismo real de import/export via
|
||||
token wordfence.com), `lib/wfCentralAPI.php` (integração Central) e o
|
||||
módulo `modules/login-security/` completo — incluindo a descoberta de que
|
||||
2FA/passkeys/CAPTCHA vivem numa tabela SQL separada (`wfls_settings`,
|
||||
colunas `name`/`value`) e que o WAF mantém uma cópia de config em
|
||||
ficheiros PHP serializados (`wp-content/wflogs/config*.php`), fora de
|
||||
`wfconfig`. Confirmado ao vivo: `wfls_settings` completa, capabilities
|
||||
`wf2fa_*`/`wfls_*` do role administrator, ficheiros WAF (`config.php`,
|
||||
`config-synced.php`, `rules.php`), categorias de regra (`sqli`/`xss`/`rce`)
|
||||
e ligação activa a Wordfence Central desde 27/02/2025.*
|
||||
@@ -0,0 +1,492 @@
|
||||
---
|
||||
name: wp-activity-log
|
||||
description: Gestão e auditoria do WP Activity Log (Melapress, slug wp-security-audit-log — rebranding do antigo "WP Security Audit Log") via WP-CLI/SQL em servidores CWP. Cobre consulta ao log de eventos (tabelas wsal_occurrences/wsal_metadata), replicação do padrão stealth mode + log restrito a um único utilizador, confirmação do gotcha "wp-cli bypassa restrições de UI", e gestão de retenção/volume do log. Usar quando "wp activity log", "wsal", "wp security audit log", "log de auditoria wordpress", "quem alterou isto no site", "histórico de acções wordpress", "esconder plugin de auditoria", "stealth mode plugin", "restringir log a um utilizador".
|
||||
---
|
||||
|
||||
# /wp-activity-log — WP Activity Log (Melapress) via WP-CLI/SQL
|
||||
|
||||
Plugin de log de auditoria WordPress (equivalente a Syslog para WP). Nome
|
||||
comercial mudou de "WP Security Audit Log" para **"WP Activity Log"**
|
||||
(rebranding Melapress) mas o **slug mantém-se `wp-security-audit-log`** — usar
|
||||
sempre este slug em `wp plugin get/activate/deactivate`, nunca o nome
|
||||
comercial.
|
||||
|
||||
**Fonte:** `CONFIG-Plugins-Referencia.md` §9 + verificação SSH ao vivo nesta
|
||||
sessão (`emanuelalmeida.pt`, versão `5.6.5`, prefixo de tabelas `wpne_`).
|
||||
|
||||
---
|
||||
|
||||
## Contexto CWP — sempre obrigatório
|
||||
|
||||
```bash
|
||||
PATH=/home/USER/public_html
|
||||
PREFIX=$(wp db prefix --allow-root --path=$PATH) # ex.: wpne_, wp_, wpah_
|
||||
```
|
||||
|
||||
**Acesso via SSH:** `server.descomplicar.pt`, porta 9443. **Existe sim um
|
||||
comando WP-CLI nativo** — corrige o que estava documentado antes: o plugin
|
||||
regista `WP_CLI::add_command( 'wsal_cli_commands', ... )` em
|
||||
`classes/class-wp-security-audit-log.php`. Ver §1.1 para a lista completa
|
||||
de subcomandos. Fora desses 7 comandos, o resto passa por `wp option`,
|
||||
`wp db query` e `wp eval`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Identificação e configuração (18 opções `wp_options`)
|
||||
|
||||
Prefixos: `wsal_*` (config principal), `Wsal*` (raro), `fs_wsalp` (estado
|
||||
Freemius). Ler tudo de uma vez:
|
||||
|
||||
```bash
|
||||
wp option list --search='wsal*' --format=table --fields=option_name,option_value --allow-root --path=$PATH
|
||||
wp option get fs_wsalp --allow-root --path=$PATH
|
||||
wp plugin get wp-security-audit-log --format=json --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
### Tabela de configuração real (`emanuelalmeida.pt`, verificado ao vivo)
|
||||
|
||||
| Opção | Valor | O que faz |
|
||||
|---|---|---|
|
||||
| `wsal_restrict-log-viewer` | `only_me` | Só o utilizador em `only-me-user-id` vê o log no wp-admin |
|
||||
| `wsal_restrict-plugin-settings` | `only_me` | Só esse utilizador altera a configuração do plugin |
|
||||
| `wsal_only-me-user-id` | `17` | ID do utilizador autorizado — confirmar sempre com `wp user get <ID>` que é a conta de IT correcta, não um utilizador órfão/comprometido |
|
||||
| `wsal_hide-plugin` | `yes` | **Stealth mode** — esconde o plugin da lista `wp-admin/plugins.php` (filtro `all_plugins`); um atacante com sessão de browser comprometida não sabe que o site está a ser auditado |
|
||||
| `wsal_mwp-child-stealth-mode` | `yes` | Idem, mas para dashboards multisite externos (ManageWP e similares) |
|
||||
| `wsal_disabled-alerts` | array de IDs (ver §3) | Tipos de evento que NÃO são registados |
|
||||
| `wsal_plugin_version` | `5.6.5` | Versão instalada |
|
||||
| `wsal_freemius_state` / `fs_wsalp` | `skipped` / `no` | Não activou licenciamento Freemius (versão free) |
|
||||
| `wsal_built-in-notifications` | array serializado | Config de e-mail de resumo diário (`daily_summary_notification`, `daily_email_address`) |
|
||||
| `wsal_notified_plugin_updates`, `wsal_notified_theme_updates`, `wsal_notified_wp_core_update` | arrays/strings | Cache interna de versões já notificadas — não é config de segurança, ignorar em auditorias |
|
||||
| `wsal_feature-highlight-notice-show`, `wsal_upgrade-notice-show`, `wsal_notification-modal-dismissed`, `wsal_free-search-try` | flags de UI | Estado de notices dispensados — irrelevante para segurança |
|
||||
|
||||
### 1.1 Comandos WP-CLI nativos (`wp wsal_cli_commands <subcomando>`)
|
||||
|
||||
Confirmado em `classes/Controllers/WP_CLI/class-wp-cli-commands.php`
|
||||
(registados desde a v4.6, `set_retention` inclusive). Todos aceitam
|
||||
`--allow-root --path=$PATH`.
|
||||
|
||||
| Subcomando | Argumentos | O que faz |
|
||||
|---|---|---|
|
||||
| `remove_wizard` | nenhum | Marca o wizard de setup inicial como dispensado (`setup-modal-dismissed=true`) |
|
||||
| `remove_daily_notification` | nenhum | Desactiva o resumo diário por e-mail (`built-in-notifications.daily_summary_notification=false`) — dispara evento `6310` |
|
||||
| `remove_weekly_notification` | nenhum | Desactiva o resumo semanal por e-mail (`weekly_summary_notification=false`) — dispara evento `6319` |
|
||||
| `disable_enable_alert` | `<alert_id>` | Activa/desactiva um `alert_id` específico (alternativa CLI ao array `wsal_disabled-alerts`) |
|
||||
| `set_hide_plugin` | `<1\|true\|0\|false>` | Equivalente CLI a `wp option update wsal_hide-plugin` (stealth mode) |
|
||||
| `login_page_notification` | `--enabled=<bool>` `--text=<html>` | Activa/desactiva o aviso "este site tem log de actividade" na página de login (`wsal_login-page-notification` + `wsal_login-page-notification-text`) — **não confirmado activo em nenhum site auditado**; texto aceita HTML |
|
||||
| `set_retention` | `--enabled=<bool>` `--pruning-value=<int>` `--pruning-unit=<days\|months\|years>` | Configura a purga automática (pruning) — ver §6 |
|
||||
|
||||
```bash
|
||||
wp wsal_cli_commands disable_enable_alert 1002 --allow-root --path=$PATH
|
||||
wp wsal_cli_commands set_hide_plugin 1 --allow-root --path=$PATH
|
||||
wp wsal_cli_commands set_retention --enabled=true --pruning-value=6 --pruning-unit=months --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Consultar o log de eventos (`wsal_occurrences` + `wsal_metadata`)
|
||||
|
||||
O log real vive em **duas tabelas dedicadas** (não em `postmeta`/`options`):
|
||||
|
||||
```bash
|
||||
wp db query "SHOW TABLES LIKE '%wsal%';" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
### Estrutura de `${PREFIX}wsal_occurrences` (1 linha = 1 evento)
|
||||
|
||||
| Campo | Tipo | Nota |
|
||||
|---|---|---|
|
||||
| `id` | bigint PK | |
|
||||
| `site_id` | bigint | Para multisite |
|
||||
| `alert_id` | bigint | Tipo de evento (ver tabela §3) |
|
||||
| `created_on` | double | Unix timestamp com microssegundos — usar `FROM_UNIXTIME(created_on)` |
|
||||
| `client_ip` | varchar | IP de origem |
|
||||
| `severity` | varchar | Código numérico (ver §3) |
|
||||
| `object` | varchar | Categoria (`user`, `post`, `plugins`, `system`, ...) |
|
||||
| `event_type` | varchar | `created`/`modified`/`deleted`/`login`/... |
|
||||
| `username`, `user_id`, `user_roles` | | Quem fez a acção — `user_id=0` é sistema/anónimo |
|
||||
| `session_id`, `user_agent` | | |
|
||||
| `post_status`, `post_type`, `post_id` | | Preenchido só em eventos de conteúdo |
|
||||
|
||||
Detalhe extra (nome do plugin alterado, ficheiro, etc.) fica em
|
||||
`${PREFIX}wsal_metadata` (`occurrence_id`, `name`, `value` — schema
|
||||
key/value, `LEFT JOIN` por `occurrence_id`).
|
||||
|
||||
### Queries úteis
|
||||
|
||||
```bash
|
||||
PREFIX=$(wp db prefix --allow-root --path=$PATH)
|
||||
|
||||
# Volume total + janela temporal coberta
|
||||
wp db query "SELECT COUNT(*) total, FROM_UNIXTIME(MIN(created_on)) primeiro, FROM_UNIXTIME(MAX(created_on)) ultimo FROM ${PREFIX}wsal_occurrences;" --allow-root --path=$PATH
|
||||
|
||||
# Últimos 50 eventos de um utilizador específico
|
||||
wp db query "SELECT FROM_UNIXTIME(created_on) quando, alert_id, object, event_type, client_ip FROM ${PREFIX}wsal_occurrences WHERE username='it' ORDER BY id DESC LIMIT 50;" --allow-root --path=$PATH
|
||||
|
||||
# Eventos num intervalo de datas
|
||||
wp db query "SELECT FROM_UNIXTIME(created_on) quando, username, object, event_type FROM ${PREFIX}wsal_occurrences WHERE created_on BETWEEN UNIX_TIMESTAMP('2026-08-01') AND UNIX_TIMESTAMP('2026-08-16') ORDER BY id;" --allow-root --path=$PATH
|
||||
|
||||
# Filtrar por tipo de evento (alert_id) — ex.: falhas de login (1002)
|
||||
wp db query "SELECT FROM_UNIXTIME(created_on) quando, username, client_ip FROM ${PREFIX}wsal_occurrences WHERE alert_id=1002 ORDER BY id DESC LIMIT 30;" --allow-root --path=$PATH
|
||||
|
||||
# Distribuição por tipo de evento (para ver o que domina o log)
|
||||
wp db query "SELECT alert_id, COUNT(*) total FROM ${PREFIX}wsal_occurrences GROUP BY alert_id ORDER BY total DESC LIMIT 20;" --allow-root --path=$PATH
|
||||
|
||||
# Distribuição por severidade
|
||||
wp db query "SELECT severity, COUNT(*) total FROM ${PREFIX}wsal_occurrences GROUP BY severity ORDER BY total DESC;" --allow-root --path=$PATH
|
||||
|
||||
# Ver metadados de um evento específico (ex.: qual plugin foi alterado)
|
||||
wp db query "SELECT name, value FROM ${PREFIX}wsal_metadata WHERE occurrence_id=<ID>;" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Tipos de evento e severidade (dados reais observados, `emanuelalmeida.pt`)
|
||||
|
||||
`severity` (código Melapress padrão): `200`=informational, `250`=user
|
||||
activity, `300`=notification, `400`=warning, `500`=critical.
|
||||
|
||||
Top `alert_id` observados em 60.337 eventos (~1,5 anos de histórico) — usar
|
||||
como referência de "normal" ao auditar um site novo, não como lista
|
||||
exaustiva (o WSAL tem 100+ tipos de evento definidos):
|
||||
|
||||
| `alert_id` | Ocorrências | Interpretação provável |
|
||||
|---|---|---|
|
||||
| `6070` | 26.476 | Verificação periódica de sistema (cron interno do WSAL) |
|
||||
| `1003` | 20.276 | Actividade de sessão/login |
|
||||
| `2008` | 3.202 | Conteúdo modificado (post/página) |
|
||||
| `6066` | 2.615 | Verificação periódica de sistema |
|
||||
| `6069` | 2.329 | Verificação periódica de sistema |
|
||||
| `1002` | 1.965 | Login falhado |
|
||||
| `1000` | 389 | Login com sucesso |
|
||||
| `2053`/`2054` | 305/133 | Conteúdo criado/eliminado |
|
||||
|
||||
**Não confiar em interpretações de `alert_id` sem confirmar** contra a
|
||||
documentação oficial Melapress (`https://melapress.com/support/kb/`) ou o
|
||||
código do plugin (`wp-content/plugins/wp-security-audit-log/`) — os números
|
||||
acima são inferência a partir do padrão de volume, não confirmados
|
||||
individualmente nesta sessão.
|
||||
|
||||
### 3.1 Categorias de eventos (mapa completo, `defaults.php`)
|
||||
|
||||
Ficheiro central de definições: `defaults.php` (raiz do plugin, função
|
||||
`set_wsal_alerts()`, ~3.760 linhas). Define **as categorias core** — os
|
||||
eventos de integrações de terceiros (WooCommerce, Yoast, ACF, Rank Math,
|
||||
etc.) vivem em ficheiros separados (ver §3.2). Categorias core, por ordem
|
||||
de aparição no ficheiro (nome + intervalo aproximado de `alert_id`):
|
||||
|
||||
| Categoria (grupo topo) | Subcategorias | Intervalo `alert_id` | Conteúdo |
|
||||
|---|---|---|---|
|
||||
| Users Logins & Sessions Events | User Activity | `1000`–`1099` | Login/logout, falhas de login, sessões, alteração de password |
|
||||
| Content & Comments | Content, Categories, Custom Fields, Custom Fields (ACF), Comments, Widgets, Menus, Custom Post Types, Pages | `2000`–`2999` | Posts/páginas criados/editados/eliminados, categorias, comentários, widgets, menus, custom post types, ACF |
|
||||
| User Accounts | User Profiles, Multisite User Profiles | `4000`–`4999` | Utilizadores criados/editados/eliminados, mudança de role, password reset |
|
||||
| Plugins & Themes | Plugins, Themes, Themes on Multisite | `5000`–`5599` | Instalação/activação/desactivação/actualização de plugins e temas |
|
||||
| Activity Logs | Activity log plugin | `6000`–`6099`, `6300`–`6399` | Config do próprio WSAL alterada (ex.: `6310`/`6311`/`6312`/`6319` já usados pelos comandos WP-CLI de notificação — ver §1.1); também cobre eventos de "Notifications & Integrations" (Slack/SMS/e-mail custom) |
|
||||
| WordPress & System | System | `6000`–`6099` | Cron interno do WSAL, verificações periódicas (os IDs `6066`/`6069`/`6070` de alto volume observados em §3 pertencem aqui) |
|
||||
| — | WordPress Site Settings | `4700`–`4799` (aprox.) | Alteração de opções core do WP (site title, timezone, permalinks, etc.) |
|
||||
| — | Email Events | `8800`–`8899` (aprox.) | Falhas de envio de e-mail via `wp_mail` |
|
||||
| — | Database Events | `9000`–`9099` (aprox.) | Erros de query, updates de schema da BD |
|
||||
|
||||
**Nota:** as gamas de `alert_id` acima são aproximadas (extraídas da ordem
|
||||
de definição em `defaults.php`, não documentadas oficialmente pela
|
||||
Melapress como ranges fixos) — para confirmar a categoria exacta de um
|
||||
`alert_id` específico, o método fiável é `grep -A6 "^\s*$ALERT_ID,$"
|
||||
defaults.php` no código-fonte do servidor.
|
||||
|
||||
### 3.2 Alertas de integrações de terceiros (activados só se o plugin correspondente estiver presente)
|
||||
|
||||
Ficheiros em `classes/WPSensors/Alerts/` (18 ficheiros, um por integração
|
||||
suportada) — cada um define o próprio bloco de `alert_id`, só carregado se
|
||||
o plugin alvo estiver activo no site:
|
||||
|
||||
| Ficheiro | Integração | Volume aprox. de alertas |
|
||||
|---|---|---|
|
||||
| `class-woocommerce-custom-alerts.php` | WooCommerce | ~417 linhas de definição (produtos, encomendas, cupões, definições da loja) |
|
||||
| `class-yoast-custom-alerts.php` | Yoast SEO | Meta SEO, sitemaps, redirects |
|
||||
| `class-rank-math-custom-alerts.php` | Rank Math | Meta SEO, schema, redirects |
|
||||
| `class-acf-custom-alerts.php` | Advanced Custom Fields | Grupos de campos, campos criados/editados |
|
||||
| `class-gravity-forms-custom-alerts.php` | Gravity Forms | Formulários, entradas, notificações |
|
||||
| `class-wpforms-custom-alerts.php` | WPForms | Formulários, entradas |
|
||||
| `class-wp-2fa-custom-alerts.php` | WP 2FA (Melapress) | Activação/desactivação de 2FA por utilizador |
|
||||
| `class-memberpress-custom-alerts.php` | MemberPress | Subscrições, membros |
|
||||
| `class-paid-memberships-pro-custom-alerts.php` | Paid Memberships Pro | Níveis, membros |
|
||||
| `class-learndash-custom-alerts.php` | LearnDash | Cursos, inscrições |
|
||||
| `class-bbpress-custom-alerts.php` | bbPress | Fóruns, tópicos |
|
||||
| `class-tablepress-custom-alerts.php` | TablePress | Tabelas |
|
||||
| `class-redirection-custom-alerts.php` | Redirection | Regras de redirect |
|
||||
| `class-termly-custom-alerts.php` | Termly | Consentimento de cookies |
|
||||
| `class-ai-wp-plugin-alerts.php` | AI (Melapress AI features) | Uso de funcionalidades AI do próprio WSAL |
|
||||
| `class-multisite-custom-alerts.php` | WordPress Multisite | Criação/eliminação de sites na rede |
|
||||
| `class-mainwp-server-custom-alerts.php` | MainWP (servidor gerido) | Propagação de definições via dashboard MainWP — ver aviso em `defaults.php:2593` ("definições do WSAL foram sobrepostas a partir do MainWP") |
|
||||
|
||||
Confirmar quais estão activos num site: `wp plugin list --status=active
|
||||
--allow-root --path=$PATH` e cruzar com a tabela acima — só os que
|
||||
correspondem a um plugin activo geram eventos.
|
||||
|
||||
---
|
||||
|
||||
## 4. Replicar o padrão de segurança num site novo (checklist)
|
||||
|
||||
Baseado na configuração real confirmada em `emanuelalmeida.pt` (avaliada
|
||||
como "acima da média"):
|
||||
|
||||
```bash
|
||||
PATH=/home/USER/public_html
|
||||
|
||||
# 1. Instalar/activar (slug correcto — nome comercial mudou, slug não)
|
||||
wp plugin install wp-security-audit-log --activate --allow-root --path=$PATH
|
||||
|
||||
# 2. Identificar o ID do utilizador de IT/admin de confiança (NÃO um admin genérico partilhado)
|
||||
wp user list --role=administrator --fields=ID,user_login,user_email --allow-root --path=$PATH
|
||||
|
||||
# 3. Restringir visualização do log e config a esse utilizador
|
||||
wp option update wsal_restrict-log-viewer only_me --allow-root --path=$PATH
|
||||
wp option update wsal_restrict-plugin-settings only_me --allow-root --path=$PATH
|
||||
wp option update wsal_only-me-user-id <ID_do_utilizador_IT> --allow-root --path=$PATH
|
||||
|
||||
# 4. Activar stealth mode — esconder o plugin da lista wp-admin
|
||||
wp option update wsal_hide-plugin yes --allow-root --path=$PATH
|
||||
wp option update wsal_mwp-child-stealth-mode yes --allow-root --path=$PATH
|
||||
|
||||
# 5. Confirmar (ler de volta, nunca confiar só no exit code)
|
||||
wp option get wsal_restrict-log-viewer --allow-root --path=$PATH
|
||||
wp option get wsal_only-me-user-id --allow-root --path=$PATH
|
||||
wp user get <ID_do_utilizador_IT> --field=user_login --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
Não mexer em `wsal_disabled-alerts` por defeito — deixar todos os ~900+
|
||||
tipos de evento activos (contando módulos de terceiros — ver §3.1). O padrão
|
||||
observado de apenas 13 IDs desligados, todos de baixo valor informativo, é a
|
||||
postura recomendada; desligar mais do que isso reduz cobertura de auditoria
|
||||
sem ganho real.
|
||||
|
||||
---
|
||||
|
||||
## 5. GOTCHA CRÍTICO — stealth mode e "only_me" não protegem contra WP-CLI/SQL
|
||||
|
||||
**Confirmado nesta sessão por teste directo:** apesar de `hide-plugin=yes`
|
||||
esconder o plugin da lista em `wp-admin/plugins.php` (via hook PHP no ecrã
|
||||
de admin), o plugin continua **totalmente visível e operável via WP-CLI**:
|
||||
|
||||
```bash
|
||||
wp plugin list --allow-root --path=$PATH | grep security-audit
|
||||
# → wp-security-audit-log,active,none,5.6.5,,on (aparece normalmente)
|
||||
|
||||
wp plugin status wp-security-audit-log --allow-root --path=$PATH
|
||||
# → Status: Active (nenhuma restrição aplicada)
|
||||
```
|
||||
|
||||
**Implicação de segurança real:** o padrão "esconder + restringir a
|
||||
`only_me`" protege apenas contra um atacante que compromete uma **sessão de
|
||||
browser wp-admin** de um utilizador administrador genérico (não vê o plugin
|
||||
na UI, não consegue desactivá-lo nem ler o log pela interface). **Não
|
||||
protege** contra:
|
||||
- Acesso SSH/WP-CLI ao servidor (qualquer comando `wp plugin deactivate`,
|
||||
`wp option update wsal_hide-plugin no`, ou `wp db query "DELETE FROM
|
||||
wsal_occurrences"` funciona sem qualquer verificação de `only-me-user-id`);
|
||||
- Acesso directo à base de dados (phpMyAdmin, mysql CLI);
|
||||
- Um plugin malicioso que corra `update_option()`/`deactivate_plugins()` em
|
||||
PHP no mesmo processo WordPress (o hook de stealth só filtra a
|
||||
*renderização* da lista, não a capability real).
|
||||
|
||||
Estas restrições são **apenas de UI**, implementadas por filtros como
|
||||
`all_plugins`/menu — não são um controlo de acesso ao nível dos dados. Ao
|
||||
avaliar a robustez do log de auditoria de um site, tratar sempre acesso
|
||||
SSH/WP-CLI e acesso à BD como "full trust" que ignora completamente esta
|
||||
protecção — a defesa real contra esses vectores é a segurança do próprio
|
||||
servidor (SSH keys, `mysql` sem exposição externa), não a config do plugin.
|
||||
|
||||
---
|
||||
|
||||
## 6. Retenção, arquivo e volume do log
|
||||
|
||||
O plugin **não faz purga agressiva por defeito** — confirmado:
|
||||
`emanuelalmeida.pt` tinha 60.337 eventos cobrindo Mar/2025 a Ago/2026 (~1,5
|
||||
anos) sem gaps aparentes, ocupando `~13 MB` (`wsal_occurrences`) + `~50 MB`
|
||||
(`wsal_metadata`, guarda os detalhes de cada evento — cresce mais rápido
|
||||
que a tabela principal).
|
||||
|
||||
```bash
|
||||
# Verificar tamanho actual antes de decidir sobre arquivo/purga
|
||||
wp db query "SELECT table_name, ROUND(((data_length+index_length)/1024/1024),2) size_mb, table_rows FROM information_schema.TABLES WHERE table_schema=DATABASE() AND table_name LIKE '%wsal%';" --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
### 6.1 Purga automática (pruning) — `wsal_pruning-*`, classe `Plugin_Settings_Helper`/`Settings_Helper`
|
||||
|
||||
Ao contrário do que a auditoria pontual anterior sugeria, a purga
|
||||
automática **não é exclusiva da versão paga** — a lógica e as opções vivem
|
||||
no core (`classes/Helpers/class-plugin-settings-helper.php` +
|
||||
`class-settings-helper.php`) e há um comando WP-CLI dedicado (`set_retention`,
|
||||
ver §1.1). Confirmado nesta expansão: nenhuma destas opções está definida em
|
||||
`emanuelalmeida.pt` (usa os defaults do código, purga desligada).
|
||||
|
||||
| Opção | Default no código | O que faz |
|
||||
|---|---|---|
|
||||
| `wsal_pruning-date-e` | `false` (desligado) | Activa/desactiva a purga automática por data |
|
||||
| `wsal_pruning-date` | calculado por `get_default_pruning_date()` | Data-limite (`strtotime`-compatible, ex. `"6 months"`) — eventos mais antigos são apagados no próximo cron |
|
||||
| `wsal_pruning-unit` | `months` | Unidade usada no picker da UI (`days`/`months`/`years`) |
|
||||
| `wsal_pruning-limit-e` | não confirmado | Activa purga por **limite de contagem** (em vez de por data) |
|
||||
| `wsal_pruning-limit` | `1` (mínimo) | Nº máximo de eventos a manter, quando `pruning-limit-e=true` |
|
||||
| `wsal_delete-data` | `false` | Se `true`, ao desinstalar o plugin todos os dados (`wsal_occurrences`/`wsal_metadata`/opções) são apagados; se `false`, ficam órfãos na BD |
|
||||
|
||||
```bash
|
||||
# Ler estado actual de purga
|
||||
wp option list --search='wsal_pruning*' --format=table --allow-root --path=$PATH
|
||||
|
||||
# Activar purga a 6 meses via WP-CLI (equivalente ao form da UI)
|
||||
wp wsal_cli_commands set_retention --enabled=true --pruning-value=6 --pruning-unit=months --allow-root --path=$PATH
|
||||
wp option get wsal_pruning-date-e --allow-root --path=$PATH
|
||||
wp option get wsal_pruning-date --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
### 6.2 Arquivo (archiving) para BD externa — `wsal_archiving-*`
|
||||
|
||||
Funcionalidade distinta da purga: em vez de apagar, **move** eventos
|
||||
antigos para uma segunda ligação de base de dados (`Archive_Records::archive()`
|
||||
em `classes/Entities/Archive/class-archive-records.php`) via cron. Requer
|
||||
configurar previamente uma "connection" de arquivo (ver §6.3) — sem
|
||||
connection definida, `is_archiving_set_and_enabled()` devolve `false` e o
|
||||
cron não corre, mesmo com `archiving-e=yes`.
|
||||
|
||||
| Opção | O que faz |
|
||||
|---|---|
|
||||
| `wsal_archiving-e` | Liga/desliga o arquivo automático |
|
||||
| `wsal_archiving-date` + `wsal_archiving-date-type` (`days`/`months`/`years`, default `1`/`months`) | Antiguidade a partir da qual um evento é arquivado |
|
||||
| `wsal_archiving-run-every` | Frequência do cron de arquivo (default `hourly`) |
|
||||
| `wsal_archiving-stop` | Pausa temporária do arquivo sem desligar a config |
|
||||
| `wsal_archiving-cron-started` | Flag interna — cron já agendado |
|
||||
|
||||
```bash
|
||||
wp option list --search='wsal_archiving*' --format=table --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
**Não confirmado activo em nenhum site auditado** (`emanuelalmeida.pt` não
|
||||
tem nenhuma destas opções definidas).
|
||||
|
||||
### 6.3 Espelhamento (mirroring) para BD/serviço externo — `wsal_wsal-mirror-*`
|
||||
|
||||
Envia uma cópia em tempo real de cada evento para uma ligação externa
|
||||
(outra tabela MySQL, ou syslog/SIEM de terceiros via plugin de mirror
|
||||
dedicado — **o WSAL não tem integração nativa de syslog/SIEM no core**, só
|
||||
o mecanismo genérico de "connections" reutilizado por mirror e archiving).
|
||||
`Settings_Helper::get_all_mirrors()` lê todas as opções com prefixo
|
||||
`WSAL_MIRROR_PREFIX` (`wsal-mirror-`); cada uma é um array serializado
|
||||
(`connection`, filtros de `alert_id`, etc.).
|
||||
|
||||
```bash
|
||||
wp option list --search='wsal-mirror-*' --format=table --allow-root --path=$PATH
|
||||
wp option list --search='wsal_connection-*' --format=table --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
Se `database_logging_enabled` for `false` E existir pelo menos um mirror
|
||||
configurado, o WSAL passa a **não gravar mais em `wsal_occurrences` local**
|
||||
— todo o log vai só para o(s) destino(s) espelhados. Confirmar sempre
|
||||
`Settings_Helper::is_database_logging_enabled()` (via `wp eval`) antes de
|
||||
assumir que as queries SQL do §2 devolvem o histórico completo num site com
|
||||
mirror activo.
|
||||
|
||||
**Nota operacional (aplica-se a §6.1–§6.3):** a ausência de purga é boa
|
||||
para auditoria (histórico completo disponível), mas em sites com muita
|
||||
actividade o crescimento é linear e sem limite. Se `wsal_metadata`
|
||||
ultrapassar dimensões incómodas (centenas de MB), considerar:
|
||||
- Activar `wsal_pruning-date-e` com uma janela realista (6–12 meses) via
|
||||
`set_retention`;
|
||||
- Arquivar eventos antigos para uma tabela `_archive` antes de apagar
|
||||
(nunca `DELETE` directo sem backup — perde-se rasto de auditoria);
|
||||
- Configurar uma connection de arquivo (§6.2) se o volume justificar
|
||||
automação em vez de purga manual.
|
||||
|
||||
Não foi necessário agir em `emanuelalmeida.pt` nesta sessão — volume actual
|
||||
(~63 MB total) é irrelevante para performance.
|
||||
|
||||
---
|
||||
|
||||
## 7. Notificações, relatórios e integrações
|
||||
|
||||
### 7.1 Notificações incorporadas (resumo diário/semanal por e-mail — gratuito)
|
||||
|
||||
Opção `wsal_built-in-notifications` (array serializado, constante
|
||||
`Notifications::BUILT_IN_NOTIFICATIONS_SETTINGS_NAME`). Confirmado em
|
||||
`emanuelalmeida.pt`: só contém config de resumo diário
|
||||
(`daily_summary_notification`, `daily_email_address`); a v5.3+ acrescentou
|
||||
resumo **semanal** (`weekly_summary_notification`, evento `6319` ao
|
||||
desactivar — ver §1.1 `remove_weekly_notification`).
|
||||
|
||||
```bash
|
||||
wp option get wsal_built-in-notifications --format=json --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
### 7.2 Notificações customizadas (regra "se `alert_id` X ocorrer, notifica Y") — Premium
|
||||
|
||||
Opção `wsal_custom-notifications` (constante
|
||||
`CUSTOM_NOTIFICATIONS_SETTINGS_NAME`) — permite regras condicionais por
|
||||
utilizador/IP/tipo de evento, com entrega por e-mail, **Slack**
|
||||
(`classes/Controllers/slack/`) ou **SMS via Twilio**
|
||||
(`classes/Controllers/twilio/`). Não confirmado activo em nenhum site
|
||||
auditado; `wsal_notifications` (nota: nome sem `custom-`, é outra opção)
|
||||
só guarda config global de encurtamento de URLs (`shorten_notification_urls`,
|
||||
`notification_bitly_shorten_key`) — confirmado vazio/desligado em
|
||||
`emanuelalmeida.pt`.
|
||||
|
||||
```bash
|
||||
wp option get wsal_custom-notifications --format=json --allow-root --path=$PATH
|
||||
wp option get wsal_notifications --format=json --allow-root --path=$PATH
|
||||
```
|
||||
|
||||
### 7.3 Exportação e relatórios
|
||||
|
||||
- **CSV** — gratuito, core. Acção AJAX `wsal_export_csv_results`
|
||||
(`classes/Writers/class-csv-writer.php`), disponível no ecrã do log em
|
||||
wp-admin (botão "Export"). Não há comando WP-CLI dedicado — a exportação
|
||||
é sempre via browser/AJAX; para extrair dados por CLI usar as queries SQL
|
||||
do §2 e `wp db query ... --format=csv` como alternativa equivalente.
|
||||
- **Relatórios agendados** (geração automática + entrega por e-mail,
|
||||
white-label) — feature **Premium** (`classes/Views/class-premium-features.php`,
|
||||
`AuditLog.php:470` mostra link de upsell "Get scheduled reports... with
|
||||
Premium" nos eventos de tipo `2000`/`2001`/`2100`/`4000`). Não existe em
|
||||
wp-options nem endpoint WP-CLI na versão gratuita.
|
||||
|
||||
### 7.4 SIEM/Syslog externo
|
||||
|
||||
**Não existe integração nativa de Syslog/SIEM no core do plugin** —
|
||||
confirmado por ausência de qualquer classe/ficheiro com `syslog`/`SIEM` no
|
||||
código-fonte (`grep -rl` devolveu zero resultados). A única via de exportar
|
||||
eventos em tempo real para um sistema externo é o mecanismo de
|
||||
**espelhamento (mirroring)** descrito em §6.3, que só suporta ligações
|
||||
configuradas como "connections" do próprio plugin (outra BD MySQL) — não um
|
||||
protocolo Syslog/CEF nativo. Para integração SIEM real, a Melapress
|
||||
documenta um add-on comercial separado; confirmar sempre no site do
|
||||
fornecedor antes de assumir que existe suporte nativo.
|
||||
|
||||
---
|
||||
|
||||
## 8. Erros comuns
|
||||
|
||||
| Sintoma | Causa | Solução |
|
||||
|---|---|---|
|
||||
| `wp plugin activate wp-activity-log` falha ("plugin not found") | Usou o nome comercial em vez do slug | Slug é sempre `wp-security-audit-log`, independentemente do rebranding |
|
||||
| Query em `wsal_occurrences` devolve datas erradas | `created_on` é Unix timestamp `double` (com microssegundos), não `DATETIME` | Usar sempre `FROM_UNIXTIME(created_on)` |
|
||||
| Achar que o plugin "não está lá" num site com `hide-plugin=yes` | Confundir stealth mode de UI com ausência real | Confirmar sempre via `wp plugin list`/`wp plugin status` — o WP-CLI nunca respeita esta flag (ver §5) |
|
||||
| `only-me-user-id` aponta para um ID que já não existe/foi desactivado | Utilizador de IT mudou de conta e a opção não foi actualizada | Confirmar sempre com `wp user get <ID>` antes de assumir que a restrição é válida — um ID órfão equivale a log inacessível a todos via UI |
|
||||
| Achar `wsal_disabled-alerts` vazio = tudo activo | O array serializado inclui sempre um `s:0:""` inicial (artefacto de serialização PHP), não é um alerta desligado real | Ignorar a primeira entrada vazia ao contar IDs desligados |
|
||||
| Achar que "não há WP-CLI para este plugin" | Confusão histórica — o WSAL regista `wp wsal_cli_commands` desde a v4.6 | Usar `wp cli cmd-dump \| grep wsal` para confirmar; ver §1.1 |
|
||||
| Achar que purga automática (`pruning`) é só Premium | `set_retention`/`wsal_pruning-*` são core, disponíveis na versão gratuita | Confirmar sempre no código (`class-plugin-settings-helper.php`) antes de recomendar upgrade pago só para ligar retenção |
|
||||
| Confundir `wsal_notifications` com `wsal_custom-notifications` | Nomes parecidos, funções diferentes — a primeira é só config de encurtamento de URL, a segunda são as regras de alerta customizado (Premium) | Ler sempre as duas e não assumir que uma vazia implica a outra desligada |
|
||||
| Assumir que o log SQL (§2) tem o histórico completo num site com mirroring activo | Se `database_logging_enabled=false` com mirror configurado, o WSAL deixa de escrever localmente | Confirmar `Settings_Helper::is_database_logging_enabled()` via `wp eval` antes de tirar conclusões de volume/gaps |
|
||||
|
||||
---
|
||||
|
||||
**Fonte:** `CONFIG-Plugins-Referencia.md` §9 (WP Security Audit Log / WP
|
||||
Activity Log) + verificação SSH ao vivo nesta sessão (`emanuelalmeida.pt`,
|
||||
opções `wsal_*`, estrutura e contagem de `wsal_occurrences`/`wsal_metadata`,
|
||||
teste de bypass `wp plugin list`) + **leitura completa do código-fonte do
|
||||
plugin nesta expansão** (`wp-content/plugins/wp-security-audit-log/`,
|
||||
versão `5.6.5`, ~99.000 linhas PHP): `defaults.php` (definições de todos os
|
||||
eventos core, função `set_wsal_alerts()`), `classes/WPSensors/Alerts/*`
|
||||
(18 integrações de terceiros), `classes/Controllers/WP_CLI/class-wp-cli-commands.php`
|
||||
(comandos WP-CLI nativos), `classes/Helpers/class-settings-helper.php` +
|
||||
`class-plugin-settings-helper.php` (todas as opções `wsal_*` — pruning,
|
||||
archiving, mirroring, notificações), `classes/Entities/Archive/class-archive-records.php`
|
||||
(mecanismo de arquivo), `classes/notification/*` (notificações
|
||||
incorporadas e customizadas, Slack/Twilio), `classes/Views/class-premium-features.php`
|
||||
e `AuditLog.php` (features gated como Premium: relatórios agendados,
|
||||
notificações custom, mirroring/archiving).
|
||||
@@ -276,6 +276,8 @@ done
|
||||
| `Error establishing database connection` | BD em baixo | `wp db check --allow-root` |
|
||||
| `Warning: Could not get lock` | Outro processo activo | `wp cli cache clear --allow-root` |
|
||||
| PHP version wrong | Site usa PHP diferente | `ps aux \| grep "pool USER"` para detectar |
|
||||
| `wp elementor flush_css` apaga CSS de páginas já OK | O comando limpa **todo** o directório `uploads/elementor/css/`, não só a página-alvo — qualquer página não revisitada fica com `post-N.css` 404/HTML até ser visitada de novo | Depois de qualquer flush, fazer loop `curl` por **todos** os permalinks publicados (`wp post list --field=url`) para forçar regeneração; confirmar `content-type: text/css` em cada `post-N.css`; purgar Cloudflare duas vezes se persistir (origem pode ficar um ciclo atrás do edge) |
|
||||
| `wp option update NOME --format=json` parte o site (fatal `json_decode(): array given`) | Alguns plugins guardam a config como **string JSON literal** em `wp_options` (o próprio plugin faz `json_decode()` sobre ela). `--format=json` faz o WP-CLI decodificar o input e gravar o **array PHP resultante** (serializado), não a string — o plugin recebe um array onde esperava string e crasha no bootstrap, ANTES de qualquer comando conseguir corrigir (inclui `wp cache flush`, que também precisa de arrancar o WP) | Verificar sempre `wp option get NOME --format=json` primeiro: resultado entre aspas escapadas `"{...}"` = string (editar com `wp db query "UPDATE wp_options SET option_value='...' WHERE option_name='NOME'"`, nunca `--format=json`); resultado sem aspas exteriores = já é array. Se ficar preso (site em baixo, `wp cache flush` também crasha) e o site tiver Redis/Memcached object cache, o valor corrompido fica cacheado e bloqueia até o WP arrancar — limpar directo com `redis-cli -n DB flushdb` (não precisa de WP a correr) antes de repetir a correcção |
|
||||
|
||||
---
|
||||
|
||||
@@ -328,7 +330,8 @@ wp user list --role=administrator --allow-root --path=$PATH
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
{"date":"2026-08-16","issue":"wp option update WpFastestCache --format=json gravou array PHP serializado em vez de string JSON; o proprio plugin faz json_decode() sobre o valor e partiu com TypeError fatal no bootstrap do WP, derrubando o site (emanuelalmeida.pt); Redis object cache tinha o valor corrompido cacheado, bloqueando ate wp cache flush (que tambem precisa arrancar o WP)","fix":"nunca usar wp option update --format=json para opcoes que o plugin le como string JSON bruta; editar via wp db query UPDATE wp_options SET option_value=... (sempre string literal, nunca decodificado); se object cache (Redis/Memcached) tiver o valor mau cacheado e qualquer comando wp-cli crashar, limpar directo via redis-cli -n DB flushdb (bypassa o bootstrap do WP por completo) antes de tentar de novo","source":"auto"}
|
||||
{"date":"2026-08-16","issue":"wp elementor flush_css limpa TODO o directorio uploads/elementor/css/, nao so a pagina visada; um flush pontual para corrigir 1 pagina (post-9.css 404) reintroduziu 404 noutra pagina ja corrigida antes na mesma sessao (post-6.css)","fix":"apos qualquer flush_css, loop curl por TODOS os permalinks publicados (wp post list --field=url) para regenerar tudo; verificar content-type text/css (nao text/html) em cada ficheiro; purgar Cloudflare 2x se persistir 404 no edge apos origem ja estar OK","source":"auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
|
||||
@@ -77,6 +77,9 @@ Verificar em qualquer publisher antes do `wp post create`:
|
||||
- [ ] ≥1 H2 com a focus_keyword
|
||||
- [ ] Link externo à fonte (`rel="noopener"`)
|
||||
- [ ] 1-3 links internos descomplicar.pt no corpo
|
||||
- [ ] Artigos da categoria **Biblioteca**: terminam sempre com secção FAQ (formato exacto na Secção 10 do PROC — não inventar outro formato, o accordion do site só reconhece formatos já mapeados)
|
||||
- [ ] `content` nunca vazio — confirmar corpo real, não só os campos RankMath (já aconteceu publicar posts com meta completa e corpo vazio)
|
||||
- [ ] `post_author` definido pela categoria do conteúdo, não deixado no autor por omissão (mapa categoria→autor na Secção 11 do PROC — Notícias=it, Redes Sociais/Design=juju, Tecnologia=f35, IA=maisum, Gestão/Estratégia/E-commerce=ealmeida, resto da Biblioteca=info)
|
||||
|
||||
## Erros RankMath mais comuns
|
||||
|
||||
|
||||
@@ -0,0 +1,743 @@
|
||||
---
|
||||
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.
|
||||
@@ -0,0 +1,437 @@
|
||||
---
|
||||
name: wp-font-perf
|
||||
description: Cortar o peso de webfonts e de imagens em background CSS em sites WordPress/Elementor da frota Descomplicar, com medição real de Performance. Cobre o subsetting de fontes de ícones (IconSax, Font Awesome, eicons, elementskit) com `pyftsubset` e rede de segurança por `unicode-range` complementar, a substituição de folhas do Elementor via `style_loader_tag` (e porque um `wp_dequeue_style` não chega), WebP em `background-image` que o WebP Express não cobre, preload de fonte variável para travar CLS, e as duas armadilhas que partem o site ou invalidam medições (purge do Cloudflare avariado, apagar `wpfc-minified`). Usar quando "performance wordpress", "lighthouse", "LCP alto", "CLS", "fontes pesadas", "subset de fontes", "icon fonts", "webfonts", "peso da página", "optimizar site", "core web vitals", "PageSpeed".
|
||||
---
|
||||
|
||||
# /wp-font-perf — Peso de webfonts e imagens CSS, com medição real
|
||||
|
||||
Reduzir peso real de páginas WordPress/Elementor na frota Descomplicar. Validado
|
||||
em piloto em `emanuelalmeida.pt` a 17-08-2026: fontes de ícones **1256KB → 10KB**,
|
||||
peso total **3125KB → 1258KB**, Performance mobile **60 → 68**, desktop **79 → 88**,
|
||||
LCP mobile **14,2s → 6,1s**, CLS **0 estável**.
|
||||
|
||||
**Fonte:** `04-Stack/02.04-Sistemas/71.Seguranca/BUNDLE-Excelencia-WP.md` §2.2.1
|
||||
e §2.2.2 (relato completo, incluindo o incidente).
|
||||
|
||||
---
|
||||
|
||||
## 0. Antes de tudo: medir Performance a sério
|
||||
|
||||
**O `lighthouse_audit` do MCP chrome-devtools NÃO mede a categoria Performance.**
|
||||
Exclui-a por desenho. Um relatório "100/100/100/100" desse MCP pode conviver com
|
||||
um LCP de 14 segundos — aconteceu, duas sessões seguidas.
|
||||
|
||||
```bash
|
||||
# Instalar/usar Lighthouse local (não depende da quota da API do PSI)
|
||||
npx -y lighthouse@12 "https://SITE/" --only-categories=performance \
|
||||
--form-factor=mobile --screenEmulation.mobile --throttling-method=simulate \
|
||||
--output=json --output-path=/tmp/lh.json --chrome-flags="--headless=new --no-sandbox" --quiet
|
||||
|
||||
# desktop
|
||||
npx -y lighthouse@12 "https://SITE/" --only-categories=performance \
|
||||
--form-factor=desktop --screenEmulation.disabled --throttling-method=simulate \
|
||||
--throttling.rttMs=40 --throttling.throughputKbps=10240 --throttling.cpuSlowdownMultiplier=1 \
|
||||
--output=json --output-path=/tmp/lhd.json --chrome-flags="--headless=new --no-sandbox" --quiet
|
||||
```
|
||||
|
||||
**Regra de evidência: mediana de 5 corridas, nunca uma.** A variância entre
|
||||
corridas isoladas da mesma configuração chega a **25 pontos** (medido: 69 e 62
|
||||
para o mesmo estado). Uma corrida não é evidência de nada.
|
||||
|
||||
Peso por tipo (é aqui que se decide onde atacar):
|
||||
|
||||
```bash
|
||||
python3 -c "
|
||||
import json, collections
|
||||
lr=json.load(open('/tmp/lh.json'))
|
||||
r=(lr['audits']['network-requests'].get('details') or {}).get('items',[])
|
||||
by=collections.Counter(); n=collections.Counter()
|
||||
for x in r:
|
||||
t=x.get('resourceType') or 'other'; by[t]+=x.get('transferSize',0); n[t]+=1
|
||||
print('total %.0fKB / %d pedidos' % (sum(by.values())/1024, len(r)))
|
||||
for t,v in by.most_common(): print(f' {t:12} {n[t]:>3} {v/1024:>7.0f}KB')
|
||||
print('perf', round(lr['categories']['performance']['score']*100))
|
||||
for k in ('largest-contentful-paint','cumulative-layout-shift','first-contentful-paint'):
|
||||
print(' ', k, lr['audits'][k].get('displayValue'))
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. Fontes de ícones: o suspeito número um
|
||||
|
||||
Sites Elementor com icon packs acumulam megabytes para desenhar dezenas de
|
||||
glifos. No piloto: **1,2MB para 27 glifos**.
|
||||
|
||||
|Fonte|Original|Subset|Glifos usados / existentes|
|
||||
|---|---|---|---|
|
||||
|IconSax|355.632 B **TTF**|3.172 B|12 / 890|
|
||||
|IconSax-Fino|355.692 B **TTF**|536 B|1 / 906|
|
||||
|eicons|108.000 B|636 B|3 / 515|
|
||||
|fa-brands-400|81.612 B|1.028 B|4|
|
||||
|fa-solid-900|78.196 B|780 B|8|
|
||||
|elementskit (ekiticons)|252KB|**0** (suprimido)|0 / 12|
|
||||
|
||||
Icon packs custom carregados pelo Elementor (`uploads/elementor/custom-icons/`)
|
||||
vêm frequentemente em **TTF/WOFF sem woff2** — formato sem compressão web.
|
||||
|
||||
### 1.1 Levantar os glifos em uso em TODO o site
|
||||
|
||||
Nunca só na homepage. Varrer todos os permalinks publicados:
|
||||
|
||||
```bash
|
||||
ssh server "sudo -u USER /usr/local/bin/wp post list --post_type=page,post \
|
||||
--post_status=publish --field=url --path=WEBROOT 2>/dev/null"
|
||||
```
|
||||
|
||||
Depois `curl` a cada URL e recolher as classes (`icon-sax-*`, `fa-*`, `eicon-*`).
|
||||
Mapear classe → codepoint nos CSS (`content:"\eXXX"`).
|
||||
|
||||
**Método mais fiável, no browser** (apanha o que vem de CSS de widgets e não só
|
||||
de classes no HTML) — itera os pseudo-elementos e lê o `content` computado:
|
||||
|
||||
```js
|
||||
const want = /Font Awesome|eicons|IconSax|elementskit/i;
|
||||
const hits = {};
|
||||
for (const el of document.querySelectorAll('*'))
|
||||
for (const ps of ['::before','::after']) {
|
||||
const cs = getComputedStyle(el, ps);
|
||||
if (!want.test(cs.fontFamily || '')) continue;
|
||||
for (const ch of (cs.content||'').replace(/^["']|["']$/g,'')) {
|
||||
const cp = ch.codePointAt(0);
|
||||
if (cp >= 0xE000) (hits[cs.fontFamily.replace(/["']/g,'').split(',')[0].trim()+'|'+cs.fontWeight] ??= new Set()).add(cp.toString(16));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 1.2 Gerar os subsets
|
||||
|
||||
Requer `fonttools` + `brotli` (`pyftsubset` em `~/.local/bin`):
|
||||
|
||||
```bash
|
||||
pyftsubset FONTE.ttf --unicodes=U+E915,U+E969,... --flavor=woff2 \
|
||||
--layout-features= --no-hinting --desubroutinize --output-file=NOME.subset.woff2
|
||||
|
||||
# fonte completa convertida para woff2 (fallback mais leve que o TTF original)
|
||||
pyftsubset FONTE.ttf --unicodes=U+E000-F8FF --flavor=woff2 \
|
||||
--layout-features= --no-hinting --output-file=NOME.full.woff2
|
||||
```
|
||||
|
||||
### 1.3 Rede de segurança obrigatória: `unicode-range` complementar
|
||||
|
||||
**Nunca servir só o subset.** Declarar duas `@font-face` para a mesma família:
|
||||
o subset com o `unicode-range` dos glifos em uso, e a fonte completa com o
|
||||
`unicode-range` **complementar**. Assim um ícone novo adicionado no Elementor
|
||||
não fica "tofu" — o browser vai buscar a completa só para esse codepoint — e
|
||||
enquanto isso não acontecer não se paga um byte por ela.
|
||||
|
||||
```python
|
||||
def complement(used, lo=0xE000, hi=0xF8FF):
|
||||
u=sorted(int(c,16) for c in used); out=[]; s=lo
|
||||
for c in u:
|
||||
if c>s: out.append((s,c-1))
|
||||
s=c+1
|
||||
if s<=hi: out.append((s,hi))
|
||||
return out # formatar como U+XXXX ou U+XXXX-YYYY
|
||||
```
|
||||
|
||||
**Confirmar que a completa não é descarregada:**
|
||||
|
||||
```js
|
||||
[...document.fonts].filter(f=>/IconSax|Font Awesome|eicons/.test(f.family))
|
||||
.map(f=>f.family+'|'+f.weight+'|'+f.status)
|
||||
// esperado: subsets 'loaded', completas 'unloaded'
|
||||
```
|
||||
|
||||
### 1.4 Substituir a folha, não acrescentar `@font-face` depois
|
||||
|
||||
**Um `wp_dequeue_style` não alcança estas folhas** e um `@font-face` acrescentado
|
||||
na fase de enqueue perde: o Elementor enfileira as folhas de icon library
|
||||
**durante o render do body** (há widgets com esses ícones no `_elementor_data`),
|
||||
pelo que `wp_style_is()` devolve `false`, o CSS nosso sai **antes** do original no
|
||||
documento, perde o desempate "última declaração vence" e **o TTF continua a ser
|
||||
descarregado** (medido, não presumido).
|
||||
|
||||
Padrão correcto:
|
||||
1. Copiar a folha do Elementor, **manter todas as regras de classe** e trocar só
|
||||
os `@font-face`. Verificar que não há `url()` fora dos `@font-face` antes de
|
||||
cortar (backgrounds embutidos).
|
||||
2. Enfileirar a cópia com `wp_enqueue_style`.
|
||||
3. Suprimir a original na **impressão**, imune à ordem de enqueue:
|
||||
|
||||
```php
|
||||
add_filter( 'style_loader_tag', function ( $tag, $handle ) {
|
||||
if ( ! is_admin() && in_array( $handle, array(
|
||||
'elementor-icons-IconSax', 'elementor-icons-IconSax-Fino',
|
||||
'elementor-icons-ekiticons', 'elementor-icons-fa-brands',
|
||||
'elementor-icons-fa-solid', 'elementor-icons',
|
||||
), true ) ) { return ''; }
|
||||
return $tag;
|
||||
}, 10, 2 );
|
||||
```
|
||||
|
||||
Handles reais confirmam-se no HTML: `grep -oE "id='[^']*(icon|ekit)[^']*-css'"`.
|
||||
|
||||
### 1.5 Icon packs 100% mortos
|
||||
|
||||
`elementor-icons-ekiticons` traz `elementskit.woff` (252KB) e um CSS que o
|
||||
Lighthouse dá como 100% não usado: define 12 ícones do **painel** do ElementsKit
|
||||
(tiktok, x-twitter, scroll-reveal, smart-post-list…). Antes de suprimir,
|
||||
confirmar que as classes presentes no HTML não têm regra:
|
||||
|
||||
```bash
|
||||
ssh server "grep -rlE '(icon-checked|icon-menu-11):before' WEBROOT/wp-content/plugins/ WEBROOT/wp-content/themes/"
|
||||
# sem resultado = classes órfãs de versão antiga, não desenham glifo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. CLS: preload da fonte de TEXTO, não das de ícones
|
||||
|
||||
Ao reduzir o preload, o heading do hero volta a re-layoutar quando a fonte de
|
||||
texto chega (no piloto: **CLS 0,213**, com 0,2055 atribuídos a um único `h4`).
|
||||
|
||||
**Não preloadar tudo** — foi o erro que criou o problema de LCP. Preloadar **um**
|
||||
ficheiro: as Google Fonts modernas são **variáveis**, e um só subset latin cobre
|
||||
os pesos 200-900.
|
||||
|
||||
```bash
|
||||
# descobrir qual ficheiro serve latin + todos os pesos
|
||||
ssh server "grep -oE '@font-face\{[^}]*\}' WEBROOT/wp-content/uploads/elementor/google-fonts/css/nunito.css" \
|
||||
# procurar o que tem unicode-range U+0000-00FF (latin) e font-style: normal
|
||||
```
|
||||
|
||||
39KB resolveram o CLS que 1410KB resolviam antes. Confirmar com **5 corridas**,
|
||||
não uma.
|
||||
|
||||
---
|
||||
|
||||
## 3. WebP em `background-image`: ponto cego do WebP Express
|
||||
|
||||
**O WebP Express reescreve as tags `<img>` do HTML mas não os `background-image`
|
||||
do CSS.** E em CWP o **nginx serve os estáticos directamente, sem passar pelo
|
||||
`.htaccess` do plugin**, pelo que também não há negociação por `Accept`.
|
||||
|
||||
Resultado no piloto: `foto-1.png` servia **458KB** (36% da página, e era o recurso
|
||||
LCP) apesar de existir `webp-express/webp-images/uploads/foto-1.png.webp` com
|
||||
181KB, gerado pelo plugin e nunca servido.
|
||||
|
||||
Detectar:
|
||||
|
||||
```bash
|
||||
# candidatos: imagens grandes referenciadas em CSS do Elementor
|
||||
ssh server "grep -rl 'NOME.png' WEBROOT/wp-content/uploads/elementor/css/"
|
||||
ssh server "find WEBROOT/wp-content/webp-express -name 'NOME*' -printf '%s %p\n'"
|
||||
```
|
||||
|
||||
Corrigir com `image-set()` (o PNG fica como segundo candidato para browsers sem
|
||||
suporte). O `!important` é necessário porque o `post-N.css` do Elementor é
|
||||
enfileirado depois:
|
||||
|
||||
```php
|
||||
$css = sprintf(
|
||||
'%s{background-image:image-set(url("%s") type("image/webp"),url("%s") type("image/png")) !important}',
|
||||
$selector, $webp_url, $png_url
|
||||
);
|
||||
wp_register_style( 'desc-lcp-webp', false, array(), '1.0.0' );
|
||||
wp_enqueue_style( 'desc-lcp-webp' );
|
||||
wp_add_inline_style( 'desc-lcp-webp', $css );
|
||||
```
|
||||
|
||||
Preloadar também a imagem LCP (`background-image` só é descoberta depois de o CSS
|
||||
ser descarregado e parseado — Load Delay medido de 8,2s = 87% do LCP):
|
||||
|
||||
```php
|
||||
printf('<link rel="preload" as="image" fetchpriority="high" href="%s">', esc_url($url));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Outros cortes verificados
|
||||
|
||||
- **`dashicons` no frontend:** 750ms de render-blocking + 35KB para **zero**
|
||||
glifos `dashicons-*` no HTML. Remover só para visitantes não autenticados (a
|
||||
admin bar precisa dele). `grep -c 'dashicons-'` na página confirma o uso real.
|
||||
- **Google Fonts remoto duplicado:** `astra-google-fonts` pede o Nunito a
|
||||
`fonts.googleapis.com` (render-blocking ~770ms + ligação a terceiros) quando o
|
||||
Elementor já o serve local. Confirmar que o local cobre os pesos antes de
|
||||
desenfileirar (`grep -c 'font-weight' nunito.css`).
|
||||
|
||||
---
|
||||
|
||||
## 5. 🔴 Armadilhas que partem o site ou invalidam medições
|
||||
|
||||
### 5.1 O purge do Cloudflare reporta sucesso sem purgar
|
||||
|
||||
`wp app-for-cf purge-cache` devolve sempre `Success: Cloudflare cache purged.` e
|
||||
**não purga**. Medido em `emanuelalmeida.pt` (17-08-2026):
|
||||
|
||||
```
|
||||
antes: cf-cache-status: HIT age: 27
|
||||
comando: Success: Cloudflare cache purged.
|
||||
depois: cf-cache-status: HIT age: 34 -> 37 -> 40 # nunca invalidou
|
||||
```
|
||||
|
||||
**É bug do comando, não das credenciais.** O token do plugin verifica `active` e
|
||||
faz `purge_everything` pela API sem problema (`success: true`, `MISS` na visita
|
||||
seguinte). Com `cfPageCachingSeconds=21600`, as alterações ficam **até 6 horas
|
||||
invisíveis** — medições no URL limpo medem HTML pré-alteração.
|
||||
|
||||
**Purge que funciona** (ferramenta da frota; lê as credenciais do próprio plugin,
|
||||
resolve a zona real e confirma o efeito, com exit≠0 se continuar `HIT`):
|
||||
|
||||
```bash
|
||||
04-Stack/02.04-Sistemas/71.Seguranca/tools/cf-purge.py \
|
||||
--account ealmeida --path /home/ealmeida/emanuelalmeida.pt \
|
||||
--url https://emanuelalmeida.pt/
|
||||
```
|
||||
|
||||
**⚠️ Armadilha ao diagnosticar: há vários plugins Cloudflare com credenciais no
|
||||
mesmo site.** Registei duas vezes a causa errada ("token inválido", "falta
|
||||
permissão `Zone → Cache Purge`") por testar as credenciais do plugin errado.
|
||||
|
||||
|Opção|Plugin|
|
||||
|---|---|
|
||||
|`app_for_cf.cloudflareAuth.token` (`cfut_…`, 53 car.) + `app_for_cf.cfZoneId`|**App for Cloudflare** — as que contam|
|
||||
|`swcfpc_config.cf_apitoken` / `cf_zoneid`|Super Page Cache — pode ter token inválido e zona errada|
|
||||
|`wp_turbosafe_cloudflare_api_token`|wp-turbosafe — cifrado, inutilizável|
|
||||
|
||||
**Confirmar sempre no código de onde vem a credencial** antes de a declarar
|
||||
inválida — `app-for-cf` usa `$this->option('cloudflareAuth.token')` em
|
||||
`src/DigitalPoint/Cloudflare/Api/Cloudflare.php`. E distinguir os erros da API:
|
||||
`Invalid API Token` (1000) = o valor não corresponde a nenhum token activo;
|
||||
falta de permissão tem outro código. Se houver `zone_id` divergentes,
|
||||
`GET /zones?name=<dominio>` desempata.
|
||||
|
||||
### 5.2 CLS: o CSS do Elementor sai **depois** de `</head>`
|
||||
|
||||
Em sites Elementor, o CSS de cada widget é enfileirado **durante o render do
|
||||
body** → o browser pinta o header sem estilos e volta a fazer layout quando as
|
||||
folhas chegam. Em `emanuelalmeida.pt` eram **78KB em 7 folhas** e dava
|
||||
**CLS 0,45–1,27 em 8 de 10 cargas** (limite bom = 0,1; pico medido 1,319).
|
||||
|
||||
**Diagnóstico em dois comandos.** Primeiro, contar folhas fora do head:
|
||||
|
||||
```bash
|
||||
python3 - <<'EOF'
|
||||
import re,subprocess,time
|
||||
h=subprocess.run(['curl','-s',f'https://SITE/?x={int(time.time())}'],capture_output=True,text=True).stdout
|
||||
he=h.find('</head>')
|
||||
L=[(m.start(),m.group(0)) for m in re.finditer(r"<link[^>]*rel=['\"]stylesheet['\"][^>]*>",h)]
|
||||
print("HEAD:",len([1 for p,_ in L if p<he]),"| BODY:",len([1 for p,_ in L if p>he]))
|
||||
for p,l in L:
|
||||
if p>he: print(" ", (re.search(r"id='([^']+)'",l) or re.search(r'id="([^"]+)"',l)).group(1))
|
||||
EOF
|
||||
```
|
||||
|
||||
Depois, medir o CLS **a sério** — não confiar no Lighthouse com
|
||||
`--throttling-method=simulate`, que devolvia 0 quase sempre neste caso. Usar
|
||||
`PerformanceObserver`, tab nova por corrida, 6 corridas:
|
||||
|
||||
```js
|
||||
await page.evaluateOnNewDocument(()=>{window.__s=[];
|
||||
new PerformanceObserver(l=>{for(const e of l.getEntries()){
|
||||
if(!e.hadRecentInput) window.__s.push({v:e.value,t:Math.round(e.startTime),
|
||||
src:(e.sources||[]).map(s=>s.node&&s.node.tagName+'.'+String(s.node.className||'').split(' ')[0])});
|
||||
}}).observe({type:'layout-shift',buffered:true});});
|
||||
await tab.goto(URL,{waitUntil:'networkidle2'});
|
||||
await new Promise(r=>setTimeout(r,3000));
|
||||
```
|
||||
|
||||
⚠️ **Dois erros de método a evitar** (cometi ambos): registar `evaluateOnNewDocument`
|
||||
várias vezes na mesma tab **soma observers** e inflaciona o total (vi 5,15 onde o
|
||||
shift real era 0,79); e um `first-paint` ~100ms antes do shift, com
|
||||
`domInteractive` no mesmo instante, é a assinatura de CSS no body — não de fontes.
|
||||
|
||||
**Correcção:** mu-plugin `elementor-css-head.php` (cópia canónica em
|
||||
`04-Stack/02.04-Sistemas/71.Seguranca/mu-plugins/`). Aprende que handles saíram
|
||||
depois do head (`wp_styles()->done` no fecho do `wp_head` vs. no `wp_footer`),
|
||||
guarda num transient por URL (12h) e antecipa-os para o head na visita seguinte.
|
||||
Resultado: **CLS 0 em 6/6**, 0 nas medianas Lighthouse mobile/desktop, 0 na
|
||||
auditoria MCP.
|
||||
|
||||
**❌ Não perder tempo com:** desligar `elementor_experiment-e_optimized_css_loading`
|
||||
(no Elementor 4.x já não desliga o carregamento condicional — as folhas continuam
|
||||
no body); e descartar o WP Meteor por A/B antes de acusar o defer de JS (`?wp-meteor-nooptimize=true`
|
||||
deu o mesmo CLS, logo não era ele).
|
||||
|
||||
**🔴 Aquecimento obrigatório de DUAS passagens depois do deploy** — no primeiro
|
||||
pedido de cada URL o mu-plugin ainda não aprendeu nada, e é esse HTML que fica
|
||||
em cache:
|
||||
|
||||
```bash
|
||||
wp post list --post_type=page,post --post_status=publish --field=url --path=$SITE > /tmp/urls.txt
|
||||
ssh server "rm -rf $SITE/wp-content/cache/all/*"
|
||||
while read -r u; do curl -s -o /dev/null "$u?p1=$(date +%s%N)"; done < /tmp/urls.txt # aprende
|
||||
ssh server "rm -rf $SITE/wp-content/cache/all/*"
|
||||
while read -r u; do curl -s -o /dev/null "$u?p2=$(date +%s%N)"; done < /tmp/urls.txt # HTML bom
|
||||
while read -r u; do curl -s -o /dev/null -w "%{http_code} $u\n" "$u"; done < /tmp/urls.txt
|
||||
```
|
||||
|
||||
**Custo aceite:** as folhas passam a bloquear no head em vez do body — mesmos
|
||||
bytes, mais cedo. Performance mediana mobile 68→64, desktop 88→86 (dentro da
|
||||
variância). CLS é Core Web Vital e estava 4× a 12× acima do limite: a troca paga-se.
|
||||
|
||||
### 5.3 NUNCA apagar `wpfc-minified`
|
||||
|
||||
Com `MinifyCss` do WP Fastest Cache ligado, os `<link>` apontam a
|
||||
`wp-content/cache/wpfc-minified/<hash>/hcd9a.css`. Apagar essa pasta enquanto
|
||||
existe HTML cacheado (no WPFC **ou no Cloudflare**) a referenciar os hashes
|
||||
antigos → **CSS a 404 em massa, site sem estilos**. Foi assim que o piloto
|
||||
apareceu desfigurado ao utilizador.
|
||||
|
||||
```bash
|
||||
# ERRADO
|
||||
rm -rf WEBROOT/wp-content/cache/wpfc-minified/*
|
||||
# CERTO — forçar HTML novo sem tocar nos ficheiros minificados
|
||||
rm -rf WEBROOT/wp-content/cache/all/*
|
||||
```
|
||||
|
||||
### 5.4 Não filtrar a saída do `wp_head` com `ob_start`
|
||||
|
||||
Tentar remover uma tag já emitida com `ob_start`/`ob_get_clean` no `wp_head`
|
||||
partiu o `<head>`. Se a origem de um preload órfão não se encontra, **deixar
|
||||
documentado em vez de mexer em buffers** — no piloto eram 38KB, não valia.
|
||||
|
||||
---
|
||||
|
||||
## 6. Verificação de fecho (obrigatória)
|
||||
|
||||
1. **Todas as folhas do HTML devolvem conteúdo** — foi isto que apanhou o
|
||||
incidente sem ambiguidade:
|
||||
|
||||
```bash
|
||||
python3 - <<'EOF'
|
||||
import subprocess, re
|
||||
h=subprocess.run(['curl','-s','https://SITE/'],capture_output=True,text=True).stdout
|
||||
links=re.findall(r"<link rel='stylesheet' id='([^']+)' href='([^']+)'", h)
|
||||
bad=[]
|
||||
for hid,href in links:
|
||||
u = href if href.startswith('http') else 'https:'+href
|
||||
o=subprocess.run(['curl','-s','-o','/dev/null','-w','%{http_code} %{size_download}',u],capture_output=True,text=True).stdout.split()
|
||||
if o[0]!='200' or int(o[1])==0: bad.append((hid,o))
|
||||
print('folhas:',len(links),'| com problema:',len(bad),bad)
|
||||
EOF
|
||||
```
|
||||
|
||||
2. **Zero glifos em falta, em várias páginas** — medir a largura de cada
|
||||
codepoint em uso contra a largura de um codepoint ausente ("tofu"):
|
||||
|
||||
```js
|
||||
const c=document.createElement('canvas').getContext('2d');
|
||||
const w=(fam,wt,cp)=>{c.font=wt+' 32px "'+fam+'"';return c.measureText(String.fromCharCode(parseInt(cp,16))).width;};
|
||||
const tofu=w('IconSax','400','2764');
|
||||
// falha se w(fam,wt,cp) === tofu
|
||||
```
|
||||
|
||||
3. **Screenshot** do hero e da secção de ícones.
|
||||
4. **CLS em 5 corridas**, não uma.
|
||||
|
||||
---
|
||||
|
||||
## 7. Estado do rollout
|
||||
|
||||
Aplicado só em **`emanuelalmeida.pt`** (piloto, 17-08-2026). Pendente #19 do
|
||||
`BUNDLE-Excelencia-WP.md`: replicar nos outros 6 sites. O padrão do WebP em
|
||||
background CSS (§3) e o `dashicons` (§4) são os mais prováveis de existirem em
|
||||
todos.
|
||||
@@ -0,0 +1,518 @@
|
||||
---
|
||||
name: wp-meteor
|
||||
description: Diagnóstico e configuração do WP Meteor (delay/reorder de JavaScript não crítico) via WP-CLI em servidores CWP. Cobre os 5 módulos reais do plugin — `ultimate-reorder` (atraso de execução de JS até interacção do utilizador, com modo "zero delay" e modo "só interacção"), `exclude` (exclusões manuais por regex), `gdpr` (exclusões automáticas para 8 plugins de cookies), `elementor-animations` e `elementor-pp` (emulação do menu Elementor PowerPack Pro — NÃO é "Elementor Pro") — mais o módulo interno `Compatibility` (sempre activo, não configurável, com exclusões automáticas para dezenas de outros optimizadores). Cobre também os mecanismos de bypass automático (query strings, user agents, page builders, conflito com WP Rocket/Nitropack/FastPixel), o endpoint REST `wpmeteor/v1/detect`, e diagnóstico de CLS/CWV com Chrome DevTools performance trace. Usar quando "wp meteor", "wpmeteor", "atraso javascript", "delay js", "ultimate reorder", "cls alto", "layout shift", "core web vitals wordpress", "facade pattern js", "js não crítico", "elementor powerpack pro", "zero delay mode", "wpmeteordisable", "wpmeteordebug".
|
||||
---
|
||||
|
||||
# /wp-meteor — Diagnóstico e config do WP Meteor (delay de JavaScript)
|
||||
|
||||
Plugin de performance de terceiros (`wp-meteor`, autor Aleksandr Guidrevitch,
|
||||
v`3.4.18`). Melhora TBT/INP **atrasando a execução de JavaScript não crítico**
|
||||
até à primeira interacção do utilizador ou até um timeout fixo. Config
|
||||
completa numa única option serializada, `wp_options.wp-meteor-settings`
|
||||
(array PHP, **5 módulos reais** + versão + campo interno `detected`).
|
||||
Catálogo confirmado por leitura completa do código-fonte do plugin
|
||||
(5718 linhas em todos os `.php`, sessão 16-08-2026) — não há módulos
|
||||
escondidos por descobrir; o que está documentado abaixo é o total.
|
||||
|
||||
Confirmado activo em `emanuelalmeida.pt` (16-08-2026, esta sessão). **Não
|
||||
confirmado noutros sites do bundle** — `wp plugin get wp-meteor` em
|
||||
`carstuff.pt` devolveu vazio/erro, i.e. não está instalado lá. Verificar
|
||||
sempre por site antes de assumir que está presente.
|
||||
|
||||
---
|
||||
|
||||
## Comandos base (SSH + WP-CLI, servidor CWP)
|
||||
|
||||
```bash
|
||||
PATH=/home/USER/public_html # ex: /home/ealmeida/emanuelalmeida.pt
|
||||
|
||||
# Ler a option completa (fonte de verdade)
|
||||
sudo -u USER /usr/local/bin/wp option get wp-meteor-settings --format=json --path=$PATH
|
||||
|
||||
# Confirmar versão e estado do plugin
|
||||
sudo -u USER /usr/local/bin/wp plugin get wp-meteor --format=json --path=$PATH
|
||||
|
||||
# Via SSH directo (alias `server` já configurado, porta 9443)
|
||||
ssh server "sudo -u USER /usr/local/bin/wp option get wp-meteor-settings --path=$PATH --format=json 2>/dev/null"
|
||||
```
|
||||
|
||||
Os avisos PHP (`WP_DEBUG_LOG already defined`) que aparecem em `stderr` são
|
||||
ruído do ambiente — ignorar, não é erro do plugin.
|
||||
|
||||
---
|
||||
|
||||
## Estrutura real da option `wp-meteor-settings` (verificado ao vivo)
|
||||
|
||||
```json
|
||||
{
|
||||
"ultimate-reorder": {
|
||||
"enabled": true,
|
||||
"id": "ultimate-reorder",
|
||||
"delay": "2",
|
||||
"description": ""
|
||||
},
|
||||
"gdpr": {
|
||||
"enabled": true,
|
||||
"id": "gdpr",
|
||||
"description": "Most of the time, you want your GDPR/Cookie to be displayed instantly..."
|
||||
},
|
||||
"exclude": {
|
||||
"enabled": true,
|
||||
"id": "exclude",
|
||||
"description": "Specify URLs or keywords or regular expressions... GA and GTM",
|
||||
"value": []
|
||||
},
|
||||
"elementor-animations": { "enabled": true, "id": "elementor-animations", "description": "" },
|
||||
"elementor-pp": { "enabled": true, "id": "elementor-pp", "description": "" },
|
||||
"v": "3.4.18"
|
||||
}
|
||||
```
|
||||
|
||||
| Módulo | Estado real | O que faz |
|
||||
|---|---|---|
|
||||
| `ultimate-reorder` | `enabled=true`, **`delay=2`** (segundos, string) | Mecanismo central — ver secção seguinte |
|
||||
| `gdpr` | `enabled=true` | Impede que o banner de cookies/GDPR seja atrasado — aparece instantaneamente |
|
||||
| `exclude` | `enabled=true`, **`value: []` — lista vazia** | ⚠️ Lista de URLs/palavras-chave/regex a excluir do atraso. **Nada está excluído hoje.** A própria descrição da opção sugere excluir menus, carrosséis do hero, GA e GTM — nenhum destes está configurado |
|
||||
| `elementor-animations` | `enabled=true` | Compatibilidade com animações nativas do Elementor (deixa correr entrance animations mesmo com scripts atrasados) |
|
||||
| `elementor-pp` | `enabled=true` | ⚠️ **Não é "Elementor Pro"** — emula o menu do plugin de terceiros **Elementor PowerPack Pro** (Livemesh). Título real no código: `"Emulate Elementor Powerpack Pro menu"`. Se o site não usa PowerPack Pro, este módulo é irrelevante e pode ficar ligado sem efeito |
|
||||
| `v` | `"3.4.18"` | Versão do plugin no momento em que a option foi gravada (não confundir com a versão instalada — confirmar sempre via `wp plugin get`) |
|
||||
| `detected` | não presente hoje (array, quando existe) | Campo interno alimentado pelo endpoint REST `wpmeteor/v1/detect` (JS de admin reporta ferramentas de terceiros detectadas, ex. `"marketo"`, `"hubspot"` — dispara um aviso admin sugerindo contacto com o autor do plugin para optimizações extra) |
|
||||
|
||||
Estes **5 módulos são o catálogo completo e definitivo** desta versão do
|
||||
plugin (`3.4.18`) — confirmado por leitura de todo o código-fonte, não só
|
||||
da option gravada. **O plugin NÃO tem** (verificado directamente no
|
||||
código, ausência confirmada, não assumida):
|
||||
|
||||
- Lazy loading de imagens/iframes — zero.
|
||||
- Defer/async de scripts como toggle independente — o mecanismo de delay
|
||||
é tudo-ou-nada por script, controlado só pelo `ultimate-reorder`.
|
||||
- Remoção de query strings de assets estáticos.
|
||||
- Preconnect/dns-prefetch configurável — existe um `preconnect: true`
|
||||
interno calculado automaticamente (`frontend_adjust_wpmeteor` em
|
||||
`UltimateReorder.php`), mas não há opção na UI nem chave na option para
|
||||
o utilizador controlar.
|
||||
- Critical CSS / CSS não usado.
|
||||
- Qualquer módulo específico de WooCommerce (existe apenas uma exclusão
|
||||
automática fixa para um script de troca de classe `woocommerce-no-js` →
|
||||
`woocommerce-js`, dentro do módulo interno `Compatibility`, não é um
|
||||
módulo à parte nem é configurável).
|
||||
|
||||
Não confundir com outros plugins de performance (WP Rocket, Autoptimize,
|
||||
etc.) que têm estas features — o WP Meteor é deliberadamente um plugin de
|
||||
um truque só (delay de JS), bem executado, com módulos de compatibilidade
|
||||
à volta desse truque.
|
||||
|
||||
---
|
||||
|
||||
## Como funciona o `ultimate-reorder` (delay/facade pattern)
|
||||
|
||||
Padrão clássico de optimização de TBT/INP: em vez de deixar o browser
|
||||
executar todo o JavaScript da página logo no carregamento (bloqueando a
|
||||
main thread), o plugin **intercepta os `<script>` da página, remove-os da
|
||||
execução imediata, e só os dispara quando**:
|
||||
|
||||
1. o utilizador interage pela primeira vez (`mousemove`, `scroll`,
|
||||
`touchstart`, `click`, `keydown` — eventos típicos deste padrão), **ou**
|
||||
2. o `delay` configurado expira — aqui **2 segundos fixos**.
|
||||
|
||||
O que ganha: a página fica "interactive-looking" mais cedo, porque o
|
||||
JavaScript pesado (analytics, widgets, sliders, tracking) não compete pela
|
||||
main thread durante o first paint/LCP.
|
||||
|
||||
O que pode perder: **qualquer script que controle dimensões, posição ou
|
||||
visibilidade de elementos visíveis acima da dobra fica também atrasado** —
|
||||
porque o mecanismo não distingue "JS de tracking" de "JS que a página
|
||||
precisa para se renderizar correctamente". Se um elemento Elementor depende
|
||||
de JS para calcular a sua altura final, ícones (`sub-arrow`, Font Awesome),
|
||||
carrosséis do hero, ou animações que definem `opacity`/`transform` no
|
||||
carregamento, esses elementos **saltam de posição/tamanho quando o script
|
||||
finalmente corre** (aos 2s ou na primeira interacção) — a definição exacta
|
||||
de Cumulative Layout Shift.
|
||||
|
||||
### Valores possíveis para `ultimate-reorder.delay` (confirmado no código, `UltimateReorder.php`)
|
||||
|
||||
A chave `delay` não é só "número de segundos" — tem 3 comportamentos
|
||||
distintos consoante o valor gravado (a option guarda string, o PHP faz
|
||||
`(int)` antes de usar):
|
||||
|
||||
| Valor gravado | Comportamento em runtime (`rdelay`, ms enviados ao JS) | Quando usar |
|
||||
|---|---|---|
|
||||
| `"0"` | `rdelay = 0` — scripts disparam assim que possível, sem espera fixa (chamado **"zero delay mode"** pelo próprio autor, promovido num aviso admin permanente em `Enqueue.php`) | Sites onde o TBT já é baixo e só se quer o reorder/facade, sem atraso artificial |
|
||||
| `"2"`, `"5"`, etc. (positivo) | `rdelay = delay * 1000` ms — timeout fixo, script corre ao fim de N segundos **mesmo sem interacção** | Caso geral — garante que scripts de tracking correm mesmo em sessões sem interacção (bounces) |
|
||||
| `"-1"` (ou qualquer negativo) | `rdelay = 86400000` (24h em ms, na prática "nunca por timeout") — **scripts só correm na primeira interacção real do utilizador**, nunca por timeout | Máxima agressividade de TBT/INP; risco: sessões sem interacção (bots de SEO/Lighthouse, utilizadores que só leem) nunca disparam analytics/pixels |
|
||||
| módulo `enabled=false` | `rdelay = 0` e o rewrite de scripts não corre — comportamento idêntico a ter o plugin desligado | Teste de isolamento (ver secção de diagnóstico CLS) |
|
||||
|
||||
Nota de compatibilidade legada (irrelevante para `v3.4.18` mas presente no
|
||||
código): em options gravadas por versões `< 2.3.6`, `delay=3` era mapeado
|
||||
automaticamente para o comportamento "-1" (só interacção). Não se aplica a
|
||||
options novas.
|
||||
|
||||
---
|
||||
|
||||
## Configurar exclusões (o gap real encontrado nesta sessão)
|
||||
|
||||
`exclude.value` é um array de strings (URL, palavra-chave ou regex) que
|
||||
identificam o `src`/conteúdo inline de scripts a **não atrasar**. Hoje está
|
||||
vazio — nada escapa ao atraso de 2s.
|
||||
|
||||
```bash
|
||||
# Adicionar exclusões (substitui o array inteiro — ler primeiro, escrever depois)
|
||||
sudo -u USER /usr/local/bin/wp option patch update wp-meteor-settings exclude value \
|
||||
'["gtag","googletagmanager","gtm.js","analytics","elementor-pro/assets/js/frontend","font-awesome"]' \
|
||||
--format=json --path=$PATH
|
||||
|
||||
# Alterar só o delay (ex.: reduzir de 2s para 0.5s para testar impacto)
|
||||
sudo -u USER /usr/local/bin/wp option patch update wp-meteor-settings ultimate-reorder delay "0.5" --path=$PATH
|
||||
|
||||
# Desligar o módulo por completo (teste de isolamento — ver secção seguinte)
|
||||
sudo -u USER /usr/local/bin/wp option patch update wp-meteor-settings ultimate-reorder enabled false --format=json --path=$PATH
|
||||
|
||||
# Confirmar
|
||||
sudo -u USER /usr/local/bin/wp option get wp-meteor-settings --format=json --path=$PATH
|
||||
```
|
||||
|
||||
**Candidatos reais a excluir** (com base na descrição da própria opção +
|
||||
nesta investigação de CLS):
|
||||
- Google Analytics / GTM (`gtag`, `googletagmanager`, `gtm.js`) — nunca
|
||||
deve ser atrasado, quebra tracking dos primeiros 2s de cada sessão.
|
||||
- Chat widgets (Tawk, Crisp, WhatsApp floating button) — se aparecem
|
||||
instantaneamente no design, precisam de correr logo.
|
||||
- Menus e carrosséis do hero — mencionados explicitamente na descrição da
|
||||
opção como candidatos.
|
||||
- Formulários acima da dobra (Elementor Pro Forms) — se o utilizador pode
|
||||
interagir antes dos 2s, o JS de validação/submit tem de já estar activo.
|
||||
- JS que controla ícones/dimensões de elementos visíveis no first paint
|
||||
(Font Awesome, `elementor-pro/assets/js/frontend`) — candidato directo
|
||||
ligado à investigação de CLS 0,89 desta sessão.
|
||||
|
||||
**⚠️ Não alterar em produção sem GATE de mutação** — esta é uma option viva
|
||||
a servir tráfego real. Qualquer patch aqui é imediato e sem staging.
|
||||
|
||||
---
|
||||
|
||||
## Exclusões automáticas embutidas (não vêm da option, vêm do código — `GDPR.php` + `Compatibility.php`)
|
||||
|
||||
Além do `exclude.value` manual, há **duas camadas de exclusão automática**
|
||||
que correm sempre que o módulo respectivo está `enabled=true` (ou sempre,
|
||||
no caso de `Compatibility`), independentes do que está gravado na option.
|
||||
Isto explica por que alguns scripts "escapam" ao atraso mesmo com
|
||||
`exclude.value: []`.
|
||||
|
||||
### Módulo `gdpr` — regex por plugin de cookies detectado (`blocker/Exclusions/GDPR.php`)
|
||||
|
||||
Quando `gdpr.enabled=true` (default), o plugin testa `is_plugin_active()`
|
||||
para 8 plugins de cookies conhecidos e, para cada um activo, adiciona
|
||||
automaticamente os padrões correspondentes à lista de "não atrasar":
|
||||
|
||||
| Plugin de cookies detectado | Padrões excluídos automaticamente |
|
||||
|---|---|
|
||||
| Sempre (independente de plugin) | `ap.legalblink.it/api/scripts/lb_cs.js` (LegalBlink) |
|
||||
| Complianz (`complianz-gdpr(-premium)`) | id `cmplz-cookiebanner` |
|
||||
| Cookie Notice (`cookie-notice`) | `var cnArgs`, `/cookie-notice/js/front(.min).js` |
|
||||
| GDPR Cookie Compliance / Moove (`gdpr-cookie-compliance`) | jQuery, `var moove_frontend_gdpr_scripts`, `var gdpr_consent__strict`, `/gdpr-cookie-compliance/dist/scripts/main.js` |
|
||||
| Cookie Law Info / CookieYes (`cookie-law-info`) | `var _ckyConfig`, `/cookie-law-info/lite/frontend/js/script(.min).js` |
|
||||
| EU Cookie Law (`eu-cookie-law-compliance`) | jQuery, `window.hasPolisClConsent` |
|
||||
| Iubenda (`iubenda-cookie-law-solution`) | `var _iub`, `cdn.iubenda.com` |
|
||||
| Cookiebot (`cookiebot`) | `consent.cookiebot.com/uc.js` |
|
||||
| Cookie Script (`cookie-script-com`) | `cookie-script.com/s/…js` |
|
||||
|
||||
⚠️ Se `function_exists('is_plugin_active')` falhar (raro, contexto sem
|
||||
`wp-admin/includes/plugin.php` carregado), o código assume **todos** os
|
||||
plugins como activos e aplica todos os padrões de uma vez — não é um bug a
|
||||
corrigir, é o comportamento de fallback do próprio plugin.
|
||||
|
||||
### Módulo interno `Compatibility` — sempre activo, sem toggle, sem entrada na option (`blocker/Exclusions/Compatibility.php`)
|
||||
|
||||
Este blocker **não aparece em nenhum separador da UI nem tem chave própria
|
||||
na option** — corre sempre, com prioridade 100 (a mais baixa, ou seja,
|
||||
aplicado por último). Contém uma lista fixa de ~25 padrões regex para não
|
||||
atrasar scripts-chave de outros optimizadores/plugins, para evitar
|
||||
conflitos duplos de optimização:
|
||||
|
||||
- Lazy loaders: Autoptimize (`lazyLoadOptions`), LazySizes
|
||||
(`lazySizesConfig`, `lazysizes(.min).js` — com excepções para Avada/
|
||||
WPSol addons), WP Rocket lazy load, Rocket Lazy Load CPCSS
|
||||
(`wprRemoveCPCSS`), Easy Image Optimizer (`eio_lazy_vars`), EWWW
|
||||
(`ewww_webp_supported`), Smush (`smush-lazy-load(-native).min.js`),
|
||||
Jetpack Lazy Images (`jetpack-lazy-images-js-enabled`, `lazy-images.js`).
|
||||
- Fast Velocity Minify (`function fvmuag(`).
|
||||
- Page builders / temas: Divi (`function et_core_page_resource_fallback(`,
|
||||
troca de classe `no-js`→`js`), Avada/Fusion (`fusionNavIsCollapsed`),
|
||||
UpSolution (`window.\$us === undefined`).
|
||||
- Swift Performance Lazyload (`data-swift-image-lazyload`).
|
||||
- New Relic (`js-agent.newrelic.com`).
|
||||
- WooCommerce (troca de classe `woocommerce-no-js`→`woocommerce-js`) — o
|
||||
único ponto de contacto do plugin com WooCommerce, **não é um módulo
|
||||
WooCommerce dedicado**.
|
||||
- WPForms (`var wpforms_settings`).
|
||||
- Complianz — camada extra dinâmica: lê o filtro `cmplz_known_script_tags`
|
||||
e a option `complianz_options_custom-scripts` (bloqueios custom
|
||||
configurados no próprio Complianz) e exclui esses URLs também, em cima
|
||||
da lista fixa do módulo `gdpr` acima.
|
||||
|
||||
---
|
||||
|
||||
## Diagnóstico CLS/CWV — ligação à investigação em aberto
|
||||
|
||||
Contexto completo: `BUNDLE-Excelencia-WP.md` §2.2 (Performance) e
|
||||
`CONFIG-Plugins-Referencia.md` §4 (WP Meteor).
|
||||
|
||||
Estado da investigação (`emanuelalmeida.pt`, LCP mobile 4,7s / **CLS
|
||||
desktop 0,89**, não resolvido):
|
||||
|
||||
1. **Rocket Loader (Cloudflare, App for Cloudflare®)** — testado e
|
||||
**descartado** nesta sessão: desligado, purge de cache, novo trace →
|
||||
CLS manteve-se em 0,89. Não era a causa.
|
||||
2. **WP Meteor `ultimate-reorder`** — **ainda não testado**, é o candidato
|
||||
mais forte agora: atraso fixo de 2s, **zero exclusões configuradas**,
|
||||
mecanismo bem mais agressivo que a reordenação leve do Rocket Loader.
|
||||
O `<i class="fa">` (Font Awesome) encontrado no HTML durante a
|
||||
investigação do CLS vem exactamente deste módulo.
|
||||
|
||||
Este é o próximo passo concreto documentado — **não uma conclusão**. Testar
|
||||
antes de decidir se se desliga o módulo, se se reduz o `delay`, ou se se
|
||||
preenche a lista de exclusões.
|
||||
|
||||
---
|
||||
|
||||
## Testar isoladamente via Chrome DevTools performance trace
|
||||
|
||||
Padrão usado nesta sessão para isolar a causa do CLS: baseline → mudar UMA
|
||||
variável → purge de todos os caches → novo trace → comparar.
|
||||
|
||||
### 1. Baseline (config actual: `ultimate-reorder` ligado, `delay=2`, sem exclusões)
|
||||
|
||||
```
|
||||
mcp__chrome_devtools_navigate_page(url: "https://emanuelalmeida.pt/")
|
||||
mcp__chrome_devtools_performance_start_trace(reload: true, autoStop: true)
|
||||
# aguardar conclusão do trace (autoStop com timeout suficiente para cobrir o delay de 2s)
|
||||
mcp__chrome_devtools_performance_stop_trace()
|
||||
mcp__chrome_devtools_performance_analyze_insight(insightName: "CLSCulprits") # ou "LayoutShifts"
|
||||
```
|
||||
Registar o CLS reportado e os elementos culpados (`culprits`) — normalmente
|
||||
identifica o selector/elemento exacto que salta.
|
||||
|
||||
### 2. Alterar a variável a testar (via SSH, fora do browser)
|
||||
|
||||
```bash
|
||||
# Opção A — desligar o módulo por completo (teste mais bruto, isola se é o WP Meteor)
|
||||
sudo -u USER /usr/local/bin/wp option patch update wp-meteor-settings ultimate-reorder enabled false --format=json --path=$PATH
|
||||
|
||||
# Opção B — manter ligado mas excluir os scripts suspeitos (teste mais cirúrgico)
|
||||
sudo -u USER /usr/local/bin/wp option patch update wp-meteor-settings exclude value '["font-awesome","elementor-pro"]' --format=json --path=$PATH
|
||||
```
|
||||
|
||||
### 3. Purgar TODOS os caches antes de repetir o trace
|
||||
|
||||
O HTML/JS servido está em pelo menos duas camadas de cache — sem purgar
|
||||
ambas, o browser continua a ver a versão antiga:
|
||||
|
||||
```bash
|
||||
# WP Fastest Cache
|
||||
sudo -u USER /usr/local/bin/wp cache flush --path=$PATH
|
||||
# (ou, se o WPFC não expõe flush nativo por wp-cli, apagar via admin/plugin action)
|
||||
|
||||
# Cloudflare (App for Cloudflare® — purge via wp-admin ou API directa da zona)
|
||||
```
|
||||
|
||||
### 4. Repetir o trace e comparar
|
||||
|
||||
```
|
||||
mcp__chrome_devtools_navigate_page(url: "https://emanuelalmeida.pt/")
|
||||
mcp__chrome_devtools_performance_start_trace(reload: true, autoStop: true)
|
||||
mcp__chrome_devtools_performance_stop_trace()
|
||||
mcp__chrome_devtools_performance_analyze_insight(insightName: "CLSCulprits")
|
||||
```
|
||||
|
||||
Comparar o valor de CLS e os `culprits` antes/depois. Se o CLS cair de
|
||||
forma consistente com o módulo desligado (opção A) mas os `culprits`
|
||||
apontarem para os mesmos elementos com exclusões configuradas (opção B),
|
||||
confirma que o `ultimate-reorder` é a causa e que a exclusão cirúrgica
|
||||
resolve sem perder o ganho de TBT nos restantes scripts.
|
||||
|
||||
### 5. Reverter se o teste não resolver
|
||||
|
||||
Se o CLS não mudar com o módulo desligado, **reverter imediatamente** ao
|
||||
estado original (não deixar o site sem o ganho de performance do WP Meteor
|
||||
por um teste que não confirmou a hipótese):
|
||||
|
||||
```bash
|
||||
sudo -u USER /usr/local/bin/wp option patch update wp-meteor-settings ultimate-reorder enabled true --format=json --path=$PATH
|
||||
sudo -u USER /usr/local/bin/wp option get wp-meteor-settings --format=json --path=$PATH # confirmar
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Interface admin — localização e separadores (`backend/views/admin.php`)
|
||||
|
||||
`wp-admin` → **Definições → WP Meteor**
|
||||
(`options-general.php?page=wp-meteor`, capacidade `manage_options`).
|
||||
Página com 3 separadores fixos (não há mais nenhum, confirmado no template):
|
||||
|
||||
| Separador (UI) | Slug interno (`tab`) | Módulo(s) renderizado(s) aqui |
|
||||
|---|---|---|
|
||||
| Settings | `ultimate` | `ultimate-reorder` |
|
||||
| Exclusions | `exclusions` | `exclude`, `gdpr` |
|
||||
| Elementor | `elementor` | `elementor-animations`, `elementor-pp` |
|
||||
|
||||
O módulo interno `Compatibility` não tem `$tab` definido — nunca aparece
|
||||
em nenhum separador, coerente com não ser configurável pelo utilizador.
|
||||
|
||||
---
|
||||
|
||||
## Mecanismos de bypass/auto-desactivação automáticos (confirmado em `frontend/Base.php` + `backend/Enqueue.php`)
|
||||
|
||||
O plugin desliga-se a si próprio (não faz rewrite de scripts nessa
|
||||
página/pedido) nas seguintes condições, **sem qualquer intervenção manual
|
||||
necessária**:
|
||||
|
||||
- Query string com `wpmeteordisable` em qualquer posição — desactiva o
|
||||
plugin nesse pedido (útil para QA sem alterar a option: `?wpmeteordisable=1`).
|
||||
- Query string com `wpmeteordebug` — mantém o plugin activo mas carrega a
|
||||
variante `public-debug.js` (não minificada, com logging) em vez de
|
||||
`public.js`.
|
||||
- `User-Agent` a corresponder a `/fastpixel/i`.
|
||||
- `Referer` igual a `https://www.squirrly.co`.
|
||||
- Constante `NITROPACK_VERSION` definida — **incompatibilidade
|
||||
declarada**, dispara aviso de erro admin permanente.
|
||||
- Constante `FASTPIXEL_VERSION` definida — idem.
|
||||
- WP Rocket activo (`WP_ROCKET_VERSION`) **e** a opção `delay_js` do WP
|
||||
Rocket está ligada — o WP Meteor desliga-se para não duplicar o
|
||||
mecanismo, com aviso admin a pedir para desligar um dos dois.
|
||||
- Pedido não é frontend (admin, ajax, cron, REST) — via `Is_Methods::is_frontend()`.
|
||||
- Filtro `wpmeteor_enabled` devolve `false` (hook para terceiros/temas
|
||||
desligarem programaticamente).
|
||||
- Parâmetros GET/POST de modo de edição de **19 page builders** conhecidos:
|
||||
`bricks`, `brizy-edit-iframe`, `builder` (Fusion), `ct_builder`
|
||||
(Oxygen), `elementor-preview`, `et_fb` (Divi), `fb-edit` (Fusion),
|
||||
`fl_builder` (Beaver Builder), `preview` (Gutenberg/block editor),
|
||||
`tb-preview` (Themify), `tve` (Thrive), `uxb_iframe` (Flatsome UX
|
||||
Builder), `vc_action`/`vc_editable`/`vcv-action` (WPBakery), `wyp_mode`/
|
||||
`wyp_page_type` (YellowPencil), `zionbuilder-preview` (Zion Builder).
|
||||
- Endpoint AMP activo (`is_amp_endpoint()` ou `ampforwp_is_amp_endpoint()`).
|
||||
- Modo editor/preview activo detectado directamente via classe do builder
|
||||
(não só GET/POST): Elementor (`Plugin::$instance->editor`/`preview`),
|
||||
Beaver Builder (`FLBuilderModel::is_builder_active()`), WPBakery
|
||||
(`vc_is_inline()`), Divi (`et_core_is_builder_used_on_current_request()`),
|
||||
Avada/Fusion Builder (`Fusion_App::get_instance()->is_builder`).
|
||||
- Content-Type da resposta diferente de `text/html` (ex.: JSON, XML,
|
||||
feeds) — nunca reescreve respostas não-HTML.
|
||||
- Página `wp-login.php`.
|
||||
|
||||
Isto é relevante para diagnóstico: se um script continuar "não atrasado"
|
||||
mesmo com o módulo `ultimate-reorder` ligado e sem exclusão manual,
|
||||
confirmar primeiro se a página em causa não cai numa destas condições de
|
||||
bypass antes de suspeitar de bug/exclusão em falta.
|
||||
|
||||
---
|
||||
|
||||
## Endpoint REST `wpmeteor/v1/detect` (`rest/Marketing.php`)
|
||||
|
||||
`POST /wp-json/wpmeteor/v1/detect` — sem autenticação declarada no
|
||||
registo da rota (`register_rest_route`, sem `permission_callback`
|
||||
restritivo visível). Recebe `{"data": [...]}` do JS de admin/frontend,
|
||||
junta ao array `detected` já gravado na option, corta para os últimos 20
|
||||
valores (`array_slice(..., -20)`) e grava de volta.
|
||||
|
||||
Uso conhecido: o JS reporta strings como `"marketo"` ou `"hubspot"`
|
||||
quando detecta esses formulários na página; se `detected` contém um destes
|
||||
valores, `backend/Enqueue.php` mostra um aviso admin permanente sugerindo
|
||||
contacto com o autor do plugin (`alex@excitingstartup.com`) para
|
||||
optimizações adicionais específicas dessas ferramentas — **não é uma
|
||||
funcionalidade que o utilizador configure**, é telemetria/marketing do
|
||||
próprio plugin.
|
||||
|
||||
```bash
|
||||
# Ler o campo detected (se existir) directamente da option
|
||||
sudo -u USER /usr/local/bin/wp option get wp-meteor-settings --format=json --path=$PATH | jq '.detected'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comandos WP-CLI próprios — confirmação: NÃO existem
|
||||
|
||||
Procurado `WP_CLI::add_command` / `\WP_CLI` em todo o código-fonte do
|
||||
plugin (`grep -rl 'WP_CLI'` em todos os `.php`) — **zero resultados**. A
|
||||
única referência a `WP_CLI` no plugin é em `engine/Is_Methods.php`, e é
|
||||
apenas a verificação `defined('WP_CLI') && WP_CLI` para detectar se o
|
||||
pedido actual corre em contexto de CLI (usado internamente para decidir
|
||||
que classes carregar), **não** um comando registado. `wp help meteor` ou
|
||||
qualquer variante não existe — toda a interacção via linha de comandos é
|
||||
através dos comandos genéricos `wp option get`/`wp option patch` sobre
|
||||
`wp-meteor-settings`, como documentado nas secções acima.
|
||||
|
||||
---
|
||||
|
||||
## Mecânica interna do rewrite de `<script>` (para debugging avançado, `UltimateReorder.php::frontend_rewrite`)
|
||||
|
||||
Quando `ultimate-reorder.enabled=true`, o buffer HTML de saída é
|
||||
reescrito via `ob_start()` (`frontend/Rewrite.php::buffer_start`), e cada
|
||||
`<script>` sofre uma destas transformações:
|
||||
|
||||
- Scripts inline são temporariamente substituídos por um delimitador
|
||||
único (`WPMETEOR` + password aleatória de 16 chars) para não serem
|
||||
reprocessados por engano por regex subsequentes que corram sobre JSON
|
||||
inserido por outros scripts — só no fim são recolocados no buffer.
|
||||
- `src="..."` passa a `data-wpmeteor-src="..."` (o browser não carrega o
|
||||
recurso até o JS do plugin trocar o atributo de volta).
|
||||
- `type="text/javascript"` (ou ausência de `type`, ou `module`) passa a
|
||||
`type="javascript/blocked" data-wpmeteor-type="..."` — o browser
|
||||
reconhece `type` desconhecido e não executa o script.
|
||||
- `onload=`/`onerror=` em `<html|body|img|iframe>` são envolvidos para
|
||||
disparar `window.dispatchEvent(new CustomEvent('fpo:element-loaded', …))`
|
||||
antes do handler original, permitindo ao motor do plugin reagir a
|
||||
carregamento de imagens/iframes mesmo com scripts atrasados.
|
||||
- Atributo de escape manual por tag: `data-wpmeteor-nooptimize="true"`
|
||||
num `<script>` específico impede que **esse** script seja atrasado,
|
||||
independentemente de exclusões globais — mecanismo usado pelo próprio
|
||||
plugin para o seu script de bootstrap injectado, mas também disponível
|
||||
para debugging manual (adicionar o atributo directamente no HTML de um
|
||||
script problemático, via filtro `the_content` ou tema, para testar sem
|
||||
tocar na option).
|
||||
- Scripts já marcados por outros plugins como `data-src=`,
|
||||
`data-wpmeteor-type=`, `data-pmdelayedscript=` ou
|
||||
`data-rocketlazyloadscript=` são ignorados (evita duplo-delay).
|
||||
|
||||
O filtro `wpmeteor_exclude` (booleano, `$exclude, $content` → bool) é o
|
||||
ponto de extensão central — tanto o `exclude.value` manual como as
|
||||
exclusões automáticas do `gdpr` e do `Compatibility` são implementadas
|
||||
como listeners deste mesmo filtro, testados por ordem de prioridade até
|
||||
um devolver `true`.
|
||||
|
||||
---
|
||||
|
||||
## Gotchas / erros comuns
|
||||
|
||||
| Sintoma | Causa | Solução |
|
||||
|---|---|---|
|
||||
| Trace mostra CLS igual antes/depois de mudar a config | Cache (WPFC e/ou Cloudflare) ainda a servir HTML/JS antigo | Purgar as duas camadas de cache antes de cada trace, nunca só uma |
|
||||
| `wp option patch` falha com "No data exists for key" | Caminho de chaves errado — `exclude` tem sub-chave `value`, não é directamente o array | Usar `wp option patch update wp-meteor-settings exclude value '[...]'` (dois níveis) |
|
||||
| `wp plugin get wp-meteor` devolve vazio noutro site do bundle | Plugin não está instalado nesse site — confirmado em `carstuff.pt` | Nunca assumir presença; confirmar por site antes de qualquer diagnóstico |
|
||||
| CLS não muda mesmo com `ultimate-reorder` desligado | Causa pode estar noutro módulo (tema, Elementor, imagens sem dimensões) | Não parar na primeira hipótese testada — este é só o próximo suspeito, não a conclusão |
|
||||
| Analytics/GTM param de disparar nos primeiros segundos | `exclude.value` vazio — GA/GTM ficam sujeitos ao atraso de 2s como qualquer outro script | Adicionar `gtag`/`googletagmanager`/`gtm.js` à lista de exclusões |
|
||||
| Confundir `elementor-pp` com "compatibilidade Elementor Pro" | O nome sugere isso mas o título real no código é "Emulate Elementor Powerpack Pro menu" — é sobre o plugin de terceiros Elementor PowerPack Pro (Livemesh) | Verificar se o site usa mesmo PowerPack Pro antes de investir tempo a testar este módulo como causa de um problema |
|
||||
| Script continua a correr "atrasado" mesmo depois de o adicionar a `exclude.value` | Já está coberto por uma exclusão automática embutida (`gdpr` ou `Compatibility`) que corre por regex diferente do valor manual, ou a página cai numa das condições de bypass automático (builder em modo preview, WP Rocket `delay_js`, etc.) | Confirmar primeiro as secções "Exclusões automáticas embutidas" e "Mecanismos de bypass" antes de assumir que a exclusão manual falhou |
|
||||
| `delay` gravado como `"-1"` e analytics/pixels param de disparar em sessões sem interacção | Comportamento esperado — `-1` significa "só corre na primeira interacção real", nunca por timeout (rdelay=86400000ms) | Se o site precisa de garantia de disparo mesmo sem interacção (bounces), usar um valor positivo, nunca `-1` |
|
||||
| `wp help meteor` ou comando WP-CLI próprio não existe | O plugin não regista nenhum comando WP-CLI — confirmado por grep a todo o código-fonte | Usar sempre `wp option get/patch` sobre `wp-meteor-settings`, nunca procurar um comando dedicado |
|
||||
|
||||
---
|
||||
|
||||
## Fonte
|
||||
|
||||
`CONFIG-Plugins-Referencia.md` §4 (WP Meteor — mapeado 16-08-2026) +
|
||||
`BUNDLE-Excelencia-WP.md` §2.2 (Performance) e tabela de pendências (linhas
|
||||
218 e 233) + verificação SSH ao vivo desta sessão em `emanuelalmeida.pt`
|
||||
(`wp option get wp-meteor-settings --format=json`, `wp plugin get
|
||||
wp-meteor --format=json`) + **leitura completa do código-fonte do plugin**
|
||||
via SSH (`find wp-content/plugins/wp-meteor -iname '*.php' | xargs wc -l`
|
||||
para mapear as 5718 linhas em todos os `.php`, seguido de leitura integral
|
||||
de `wp-meteor.php`, `engine/{Initialize,Base,Is_Methods}.php`,
|
||||
`blocker/{Base,Event}.php`, `blocker/FirstInteraction/{Base,
|
||||
UltimateReorder}.php`, `blocker/Exclusions/{Exclude,GDPR,Compatibility}.php`,
|
||||
`blocker/Integration/{ElementorAnimations,ElementorPP}.php`,
|
||||
`backend/{SettingsPage,SaveSettings,Enqueue,ActDeact,InstUninst}.php`,
|
||||
`backend/views/admin.php`, `frontend/{Base,Rewrite}.php`,
|
||||
`functions/functions.php` e `rest/Marketing.php`, na sessão de expansão de
|
||||
16-08-2026). Catálogo de módulos confirmado como completo e definitivo
|
||||
para `v3.4.18` — não há funcionalidades por documentar além das listadas
|
||||
neste ficheiro. Nenhuma alteração foi feita em produção.
|
||||
Reference in New Issue
Block a user