Maintenance Snapshot Recorder

Plugin WordPress para registrar snapshots manuais das atualizacoes disponiveis de core, plugins e temas.

Objetivo

Permitir que administradores registrem, em um clique, o estado de atualizacoes do site na tela wp-admin/update-core.php, com armazenamento historico no admin (CPT privado).

Funcionalidades implementadas

• Cria o CPT maintenance_snapshot (nao publico, visivel no admin como submenu de Ferramentas).
• Adiciona botao Registrar snapshot de atualizacoes na tela de updates.
• Salva snapshot via POST seguro com nonce.
• Captura:
  • status de atualizacao do core
  • lista de plugins com update
  • lista de temas com update
  • metadados (data, WP, PHP, URL do site)
• Salva o JSON no meta snapshot_data.
• Exibe notice de sucesso/erro apos registro.
• Exibe visualizacao organizada do snapshot na edicao do CPT.
• Tenta capturar changelog de plugins e recorta o trecho do gap de versoes.

Estrutura do plugin

maintenance-snapshot-recorder/
  assets/
    admin.css
  includes/
    class-cpt.php
    class-snapshot-service.php
    class-snapshot-repository.php
    class-admin-ui.php
    class-snapshot-view.php
  maintenance-snapshot-recorder.php
  index.php
  uninstall.php
  README.md

Fluxo de funcionamento

1. Admin abre wp-admin/update-core.php.
2. Plugin renderiza o botao no topo da tela de updates usando hook nativo do WordPress.
3. Clique no botao envia POST para admin-post.php?action=msr_register_snapshot.
4. MSR_Admin_UI valida permissao e nonce.
5. MSR_Snapshot_Service coleta os dados.
6. MSR_Snapshot_Repository cria post maintenance_snapshot e salva snapshot_data (JSON).
7. Usuario e redirecionado para updates com notice.

Estrutura do JSON salvo (snapshot_data)

Exemplo de estrutura:

{
  "meta": {
    "date": "2026-03-20T18:52:30+00:00",
    "wp_version_current": "6.9.4",
    "php_version": "8.3.23",
    "site_url": "https://exemplo.com"
  },
  "core": {
    "current": "6.9.4",
    "latest": "6.9.4",
    "needs_update": false
  },
  "plugins": [
    {
      "name": "Nome do plugin",
      "slug": "plugin-slug",
      "current_version": "1.0.0",
      "new_version": "1.0.1",
      "needs_update": true,
      "changelog": "Version 1.0.1: ...apenas o gap..."
    }
  ],
  "themes": [
    {
      "name": "Nome do tema",
      "slug": "tema-slug",
      "current_version": "1.0.0",
      "new_version": "1.0.1",
      "needs_update": true
    }
  ]
}

Changelog de plugins (como funciona hoje)

• Fonte 1: upgrade_notice vindo do transient de updates.
• Fonte 2: plugins_api('plugin_information'), secao changelog.
• O texto e normalizado e o plugin tenta identificar blocos por versao.
• Se conseguir identificar, salva apenas versoes > current_version e <= new_version.
• Se nao conseguir identificar headings de versao, salva fallback curto (primeiras linhas).

Visualizacao no admin

Na edicao de cada snapshot (Ferramentas > Maintenance Snapshots > Edit), existe a metabox Resumo do Snapshot com:

• tabela de metadados
• status do core
• plugins e temas em tabela
• changelog colapsavel por item
• JSON bruto formatado

Seguranca e boas praticas aplicadas

• Bloqueio de acesso direto em todos os arquivos (ABSPATH).
• Validacao de permissao (current_user_can('update_core')).
• Nonce (wp_create_nonce + check_admin_referer).
• Sanitizacao e escaping na captura e na renderizacao.
• Sem parsing de HTML externo da tela de updates.
• Sem dependencias JS/jQuery.
• CSS admin carregado apenas nas telas necessarias (update-core e maintenance_snapshot).
• Pronto para internacionalizacao via load_plugin_textdomain.
• Arquivos de distribuicao adicionados (index.php e uninstall.php).

Checklist de conformidade (WordPress Handbook)

Itens revisados com base no Plugin Handbook e Coding Standards:

• Validacao de permissao por capability antes de acoes sensiveis.
• Uso de nonce para acao administrativa com POST.
• Sanitizacao na entrada e escaping na saida.
• Internacionalizacao com text domain.
• Prefixo consistente (MSR) para classes/constantes globais.
• Documentacao inline em PHPDoc para classes, propriedades e metodos.
• Bloqueio de acesso direto a arquivos PHP.

Limitacoes atuais

• Changelog varia muito entre plugins; nem todos publicam formato consistente.
• Captura de changelog de tema nao foi implementada nesta versao.

Como usar

1. Ative o plugin no painel.
2. Acesse Dashboard > Updates.
3. Clique em Registrar snapshot de atualizacoes.
4. Consulte em Ferramentas > Maintenance Snapshots.

Checklist de validacao manual

• Botao visivel na tela de updates.
• Snapshot criado com status publish.
• Meta snapshot_data preenchido com JSON valido.
• Notice de sucesso apos salvar.
• Metabox de resumo exibindo os dados corretamente.

Possiveis proximos passos

• Adicionar colunas customizadas na listagem do CPT (data, qtd plugins, qtd temas, core update).
• Exportar snapshot em JSON/CSV.
• Adicionar comparador entre snapshots.
• Capturar changelog de temas (quando disponivel).
• Criar WP-CLI command para gerar snapshot.