Cloudflare Cache Manager

Plugin WordPress para gerenciamento inteligente de limpeza de cache na Cloudflare, com purga granular por URLs para eventos de conteúdo e purge_everything apenas para alterações estruturais do site.

O que faz

Purga seletiva por URLs — ao editar/publicar um post, apenas as URLs relacionadas são invalidadas (permalink, home, feeds, taxonomias, autor, paginação, etc.). O restante do cache permanece intacto.
Purge Everything somente para alterações globais (tema, menus, widgets, permalinks, etc.).
Purga manual via botão no painel administrativo, com feedback detalhado.
Debounce inteligente — evita chamadas excessivas à API em operações em lote.
Debug configurável via error_log() e/ou WooCommerce Logger.
Filter hook ccm_post_purge_urls para personalizar a lista de URLs purgadas.

Por que purga granular?

Em portais com alto tráfego, um purge_everything a cada edição de post pode causar:

Indisponibilidade momentânea — todas as páginas perdem cache simultaneamente
Sobrecarga no servidor — milhares de visitantes simultâneos batem no origin
Tempo de re-cache elevado — até o Cloudflare recachear, a performance cai

Com purga seletiva, apenas as URLs afetadas pelo post editado são invalidadas (~15-40 URLs), preservando o cache de todo o restante do site.

Requisitos

WordPress 5.0+
PHP 7.4+
Conta Cloudflare com API Token com permissão de Zone > Cache Purge > Purge
(Opcional) WooCommerce — para debug via WC Logger

Instalação

Como plugin normal

Copie a pasta cloudflare-cache-manager/ para wp-content/plugins/.
Ative o plugin no painel Plugins do WordPress.
Acesse Configurações > Cloudflare Cache Manager.
Preencha o Zone ID e o API Token da Cloudflare.
Salve as configurações.

Como Must-Use plugin (mu-plugin)

Copie a pasta cloudflare-cache-manager/ para wp-content/mu-plugins/cloudflare-cache-manager/.
Copie o arquivo ccm-loader.php para wp-content/mu-plugins/ccm-loader.php.
Acesse Configurações > Cloudflare Cache Manager para configurar.

wp-content/mu-plugins/
├── ccm-loader.php                         ← loader (carrega o plugin)
└── cloudflare-cache-manager/              ← pasta do plugin
    ├── cloudflare-cache-manager.php
    ├── hooks/
    ├── logic/
    ├── callbacks/
    └── views/

MU plugins são carregados automaticamente e não podem ser desativados pelo painel. Se as credenciais não estiverem configuradas, um aviso aparecerá no admin.

WP-CLI

O plugin registra o comando wp ccm com os seguintes subcomandos:

`wp ccm purge`

Purga todo o cache da zona (purge_everything). Pede confirmação antes de executar.

wp ccm purge

# Sem confirmação (útil em scripts/cron)
wp ccm purge --yes

`wp ccm purge --post=<id>`

Purga apenas as URLs relacionadas a um post específico (granular).

wp ccm purge --post=42

`wp ccm urls <post_id>`

Lista todas as URLs que seriam purgadas para um post (dry-run — não envia nada à Cloudflare).

wp ccm urls 42

# Exportar como JSON
wp ccm urls 42 --format=json

`wp ccm config`

Gerencia as configurações do plugin diretamente pelo terminal.

# Configurar credenciais
wp ccm config set zone_id abc123def456
wp ccm config set api_token cftoken_xxxxx

# Ajustar debounce
wp ccm config set purge_interval 30

# Ativar/desativar debug
wp ccm config set debug_error_log on
wp ccm config set debug_woocommerce off

# Ver um valor específico
wp ccm config get zone_id
wp ccm config get zone_id --reveal

# Listar todas as configurações
wp ccm config list
wp ccm config list --reveal
wp ccm config list --format=json

# Resetar tudo para os padrões
wp ccm config reset

Chaves disponíveis:

Chave	Tipo	Padrão	Descrição
`zone_id`	string	(vazio)	Zone ID da Cloudflare
`api_token`	string	(vazio)	API Token da Cloudflare
`purge_interval`	int	10	Debounce em segundos
`debug_error_log`	bool	off	Debug via `error_log()`
`debug_woocommerce`	bool	off	Debug via WC Logger

Campos sensíveis (zone_id, api_token) são mascarados por padrão. Use --reveal para exibir o valor real.

`wp ccm status`

Exibe a configuração atual do plugin e testa conectividade com a API da Cloudflare.

wp ccm status

Saída exemplo:

  Configuração              Valor
  ──────────────────────────────────────────────────
  Modo de instalação        Must-Use plugin
  Zone ID                   a1b2••••••••••••y3z4
  API Token                 cfpk••••••••••••abcd
  Debounce (segundos)       10
  Debug error_log           Ativado
  Debug WooCommerce         Desativado

  ✔ Conectado! Zona: meusite.com.br (status: active)

Configurações

Campo	Descrição
Zone ID	Identificador da zona no Cloudflare.
API Token	Token de API com permissão de purge.
Intervalo mínimo entre purges	Debounce em segundos (padrão: 10s). Valor `0` desativa.
Debug: error_log()	Grava logs de cada purge no log do PHP.
Debug: WooCommerce	Grava logs no WooCommerce Logger.

Como funciona

Purga seletiva (eventos de conteúdo)

Quando um post é publicado/editado/excluído, o plugin coleta todas as URLs relacionadas:

URL coletada	Descrição
Permalink do post	URL principal
Home page	Página inicial
Página de posts	Se usar front page estática
Paginação	Até 3 páginas da home
Taxonomias	Links de categorias, tags e custom taxonomies (+ ancestrais)
Feeds de taxonomias	RSS/Atom de cada termo
Página do autor	URL + feed do autor
Archive do CPT	Se for custom post type
Feeds globais	RSS2, Atom, RDF, RSS, comentários
Feed do post	Feed de comentários do post
Posts adjacentes	Anterior e próximo
Posts ancestrais	Para páginas hierárquicas
Archives de datas	Ano, mês e dia
AMP	Se o plugin AMP estiver ativo

As URLs são enviadas à API da Cloudflare em lotes de 30 (limite da API por request).

Purge Everything (eventos globais)

Apenas alterações estruturais do site disparam purge total:

Tema alterado/atualizado
Menu de navegação editado
Widgets alterados
Customizer salvo
Estrutura de permalinks alterada
Visibilidade do site alterada
Termos de taxonomia criados/editados/excluídos
Usuários criados/editados/excluídos

Purga manual

O botão "Limpar Cache Agora" na página de configurações sempre faz purge_everything.

Hooks monitorados

Conteúdo → Purga seletiva por URLs

Hook	Quando dispara
`publish_post` / `publish_page`	Post ou página publicado
`future_to_publish`	Post agendado publicado
`wp_trash_post`	Post enviado para lixeira
`delete_post`	Post excluído permanentemente
`delete_attachment`	Attachment excluído/re-uploadado
`clean_post_cache`	Cache interno do WP limpo
`transition_post_status`	Transições de status envolvendo publish
`pre_post_update`	Mudança publish→draft e alteração de slug
`comment_post`	Novo comentário aprovado
`transition_comment_status`	Status de comentário alterado
`wp_update_comment_count`	Contagem de comentários atualizada

Configurações do site → Purge Everything

Hook	Quando dispara
`switch_theme`	Tema ativado
`upgrader_process_complete`	Tema/plugin atualizado
`wp_update_nav_menu`	Menu de navegação
`update_option_sidebars_widgets` / `widget_update_callback`	Widgets
`customize_save` / `customize_save_after`	Customizer
`permalink_structure_changed` / `update_option_category_base` / `update_option_tag_base`	Permalinks
`update_option_blog_public`	Visibilidade do site
`create_term` / `edit_term` / `delete_term`	Taxonomias públicas
`add_link` / `edit_link` / `delete_link`	Blogroll
`profile_update` / `delete_user` / `user_register`	Usuários

Personalizando URLs purgadas

Use o filter ccm_post_purge_urls para adicionar ou remover URLs da lista:

add_filter( 'ccm_post_purge_urls', function( $urls, $post_id ) {
    // Adicionar URL customizada
    $urls[] = home_url( '/minha-pagina-especial/' );

    // Remover feeds da lista
    $urls = array_filter( $urls, function( $url ) {
        return strpos( $url, '/feed/' ) === false;
    } );

    return $urls;
}, 10, 2 );

Estrutura do projeto

cloudflare-cache-manager/
├── cloudflare-cache-manager.php   # Bootstrap, constantes e loader de módulos
├── ccm-loader.php                 # Loader para instalação como MU plugin
├── hooks/
│   ├── admin-menu.php             # Registro do submenu em Configurações
│   ├── save-post.php              # Hooks de conteúdo → purga seletiva por URLs
│   └── site-changes.php           # Hooks globais → purge_everything
├── callbacks/
│   └── settings-callbacks.php     # Callback de renderização da página
├── logic/
│   ├── cloudflare-cache.php       # API Cloudflare: purge_everything, purge por URLs, debug
│   └── url-collector.php          # Coleta URLs relacionadas a um post
├── cli/
│   └── class-ccm-cli.php         # Comandos WP-CLI (wp ccm purge/urls/status)
└── views/
    └── settings-form.php          # Página de configurações no admin

Criando o API Token na Cloudflare

Acesse dash.cloudflare.com/profile/api-tokens.
Clique em Create Token.
Use o template Custom token:
- Zone > Cache Purge > Purge
Em Zone Resources, selecione a zona desejada.
Copie o token gerado e cole no campo API Token do plugin.

Limites da API Cloudflare

Operação	Limite
`purge_everything`	1.000 requests / 5 min / zona
Purge por URLs (`files`)	30 URLs por request

Com o debounce de 10s, o máximo de purge_everything é ~30 req/5min.

Observações

A autenticação utiliza Bearer Token (API Token), não a Global API Key.
As credenciais são armazenadas na tabela wp_options.
Inspirado nos hooks do WP Rocket e do plugin oficial Cloudflare (v4.14.2).

Navigation Menu

Uh oh!

Repository files navigation

Cloudflare Cache Manager

O que faz

Por que purga granular?

Requisitos

Instalação

Como plugin normal

Como Must-Use plugin (mu-plugin)

WP-CLI

`wp ccm purge`

`wp ccm purge --post=<id>`

`wp ccm urls <post_id>`

`wp ccm config`

`wp ccm status`

Configurações

Como funciona

Purga seletiva (eventos de conteúdo)

Purge Everything (eventos globais)

Purga manual

Hooks monitorados

Conteúdo → Purga seletiva por URLs

Configurações do site → Purge Everything

Personalizando URLs purgadas

Estrutura do projeto

Criando o API Token na Cloudflare

Limites da API Cloudflare

Observações

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
callbacks		callbacks
cli		cli
hooks		hooks
logic		logic
views		views
.gitignore		.gitignore
README.md		README.md
ccm-loader.php		ccm-loader.php
cloudflare-cache-manager.php		cloudflare-cache-manager.php

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Cloudflare Cache Manager

O que faz

Por que purga granular?

Requisitos

Instalação

Como plugin normal

Como Must-Use plugin (mu-plugin)

WP-CLI

wp ccm purge

wp ccm purge --post=<id>

wp ccm urls <post_id>

wp ccm config

wp ccm status

Configurações

Como funciona

Purga seletiva (eventos de conteúdo)

Purge Everything (eventos globais)

Purga manual

Hooks monitorados

Conteúdo → Purga seletiva por URLs

Configurações do site → Purge Everything

Personalizando URLs purgadas

Estrutura do projeto

Criando o API Token na Cloudflare

Limites da API Cloudflare

Observações

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`wp ccm purge`

`wp ccm purge --post=<id>`

`wp ccm urls <post_id>`

`wp ccm config`

`wp ccm status`