Pular para o conteúdo

Mover conteúdo do banco de dados para arquivos com Content Sync

Blocos, templates e páginas baseadas em arquivos já vivem no seu repositório. Parte do conteúdo não se encaixa nesse modelo, porque os editores o criam no painel administrativo: membros da equipe, locais de escritório, estudos de caso. Esse conteúdo continua sendo importante para o projeto. Um site de staging precisa ter a mesma página da equipe que o site de produção, um novo desenvolvedor precisa de dados realistas e um revisor deve perceber quando alguém altera o título de uma vaga. Dumps do banco de dados não resolvem bem nenhum desses problemas. Eles contêm tudo, os IDs diferem entre ambientes e ninguém revisa um diff SQL.

Content Sync preenche essa lacuna. Um comando WP-CLI projeta uma lista permitida de posts, termos, relações e metadados em arquivos JSON e HTML no seu tema. Outro comando aplica esses arquivos a um banco de dados diferente. Cada entidade recebe um UID portátil, e as referências entre entidades são reescritas somente onde você as declara.

Este guia percorre um diretório de equipe: exportá-lo para arquivos, revisá-lo, editar um arquivo, transferi-lo para um ambiente novo e fazer a limpeza com segurança.

O exemplo

O tema registra um tipo de post acme_member e uma taxonomia acme_team em todos os ambientes. Cada post de membro pode conter:

Chave de metadados Contém
_acme_role O cargo, uma string simples
_acme_mentor O ID do post de outro membro
_thumbnail_id O ID do anexo do retrato
_acme_api_token Um token de integração que nunca deve chegar a git

Content Sync nunca registra tipos de post nem taxonomias. Eles precisam existir em todos os ambientes para os quais você envia dados.

Etapa 1: configurar o Content Sync

O Content Sync fica desativado até você habilitá-lo em blockstudio.json. Até lá, todo comando retorna uma única linha skipped:

Shell
wp bs content status
Código
action   entity   id       uid  message
skipped  content  default       Content Sync is disabled. Set content.enabled to true to run this command.

Adicione um grupo content:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "content": {
    "enabled": true,
    "id": "team",
    "path": "content",
    "postTypes": ["acme_member"],
    "taxonomies": ["acme_team"],
    "meta": {
      "include": ["_acme_*", "_thumbnail_id"],
      "references": {
        "_acme_mentor": { "kind": "post" },
        "_thumbnail_id": { "kind": "attachment" }
      }
    },
    "media": "manifest"
  }
}

Cada chave define um limite:

  • postTypes e taxonomies são listas de permissões. Nada fora delas é lido, gravado ou removido. Um postTypes vazio significa que nenhum post será afetado.
  • meta.include define as chaves de metadados permitidas, com curingas *. meta.exclude sempre prevalece, e _edit_lock, _edit_last e _wp_old_slug são excluídos por padrão.
  • meta.references declara quais valores de metadados são IDs. Content Sync nunca presume que um número inteiro seja um ID.
  • id nomeia o conjunto de conteúdo. Ele é armazenado em cada entidade sincronizada, e a limpeza só afeta entidades do mesmo conjunto.
  • path é a pasta de saída, relativa ao diretório do tema ativo.

Etapa 2: exportar

Primeiro, visualize a projeção. Nada é gravado, e os UIDs exibidos ainda não estão armazenados:

Shell
wp bs content pull --dry-run
Código
action       entity  id   uid          message
would-write  post    530  4c8e9997-...  .../posts/acme_member/jane.4c8e9997.json
would-write  post    531  6cddc303-...  .../posts/acme_member/sam.6cddc303.json
would-write  term    4    6661b6d9-...  .../terms/acme_team/leadership.6661b6d9.json

Depois, faça a exportação de verdade. Isso atribui um _blockstudio_content_uid permanente a cada entidade que ainda não tenha um e grava os arquivos:

Shell
wp bs content pull
Código
action   entity  id        uid          message
written  post    530       5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
written  post    531       208db72e-...  .../posts/acme_member/sam.208db72e.json
written  term    4         7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
written  media   manifest                .../media/manifest.json

O resultado no tema:

Código
content/
├── media/
│   └── manifest.json
├── posts/
│   └── acme_member/
│       ├── jane.5d4bf9b5.html
│       ├── jane.5d4bf9b5.json
│       └── sam.208db72e.json
└── terms/
    └── acme_team/
        └── leadership.7491a6a1.json

Os nomes dos arquivos combinam o slug com o início do UID. O post JSON contém os campos, as relações com termos e os metadados permitidos:

JSON
{
    "uid": "5d4bf9b5-16b7-4975-acc6-51dc1d4e49ec",
    "type": "acme_member",
    "status": "publish",
    "slug": "jane",
    "title": "Jane Doe",
    "date": "2026-10-13T03:03:02+00:00",
    "modified": "2026-10-13T03:03:02+00:00",
    "parent": null,
    "menuOrder": 0,
    "terms": {
        "acme_team": [
            "7491a6a1-702c-4a29-9993-9ae7b2a79c0a"
        ]
    },
    "meta": {
        "_acme_role": "Design Lead",
        "_thumbnail_id": "72a2db75-6fd2-41f9-8d3c-b323ce3b3551"
    },
    "metaEncoding": {
        "_acme_role": "scalar",
        "_thumbnail_id": "scalar"
    }
}

A relação com o termo e a imagem em destaque são UIDs, não IDs locais. O corpo do post fica ao lado dele em jane.5d4bf9b5.html, como marcação de blocos bruta. Um post sem conteúdo, como o de Sam, não recebe um arquivo .html. O _acme_mentor de Sam é armazenado como UID de Jane, pois a chave está declarada como referência post.

Etapa 3: revisar antes de confirmar as alterações

Execute status antes de confirmar as alterações. Ele compara os arquivos com o banco de dados e também sinaliza dados arriscados:

Shell
wp bs content status
Código
action     entity  id               uid          message
unchanged  post    530              5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
unchanged  post    531              208db72e-...  .../posts/acme_member/sam.208db72e.json
unchanged  term    4                7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
warning    meta    _acme_api_token                Allowlisted meta key may contain secrets or PII; review before committing synced files.

O curinga _acme_* detectou o token. Considere meta.include um limite para as alterações confirmadas e exclua a chave explicitamente:

JSON
"meta": {
  "include": ["_acme_*", "_thumbnail_id"],
  "exclude": ["_acme_api_token"],
  "references": {
    "_acme_mentor": { "kind": "post" },
    "_thumbnail_id": { "kind": "attachment" }
  }
}

O próximo pull regrava sam.208db72e.json sem o token e deixa os outros arquivos intactos. status também alerta sobre IDs numéricos no conteúdo da marcação de blocos, pois Content Sync não reescreve IDs em arquivos .html.

Confirme as alterações na pasta content/.

Etapa 4: editar um arquivo e enviar

Os arquivos são a fonte de verdade do push. Altere o cargo de Jane no arquivo JSON de Design Lead para Head of Design e confira o que aconteceria:

Shell
wp bs content status
Código
action        entity  id   uid          message
would-update  post    530  5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
unchanged     post    531  208db72e-...  .../posts/acme_member/sam.208db72e.json
unchanged     term    4    7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json

push --dry-run exibe o mesmo plano na ordem de envio. Aplique-o:

Shell
wp bs content push
Código
action     entity  id   uid          message
unchanged  term    4    7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
updated    post    530  5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
unchanged  post    531  208db72e-...  .../posts/acme_member/sam.208db72e.json

O envio valida o plano completo antes de gravar. Referências declaradas não resolvidas, conflitos de slug, tipos de post ausentes e arquivos malformados interrompem o processo.

WordPress atribui um novo horário de modificação a um post atualizado, enquanto o arquivo ainda contém o valor modified antigo. Portanto, uma execução de status logo após esse envio informa que o post de Jane está conflict com “Banco de dados alterado desde a última sincronização.” Execute pull uma vez após o envio para registrar o novo horário; então, status informa unchanged.

Etapa 5: transferir o conteúdo para outro ambiente

Em um ambiente novo, os arquivos descrevem posts que ainda não existem. Neste exemplo, o termo e o anexo do retrato já existem nesse ambiente com os mesmos UIDs, então apenas os dois membros estão ausentes:

Shell
wp bs content status
Código
action      entity  id    uid          message
missing-db  post    jane  5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
missing-db  post    sam   208db72e-...  .../posts/acme_member/sam.208db72e.json
unchanged   term    4     7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
Shell
wp bs content push
Código
action     entity  id   uid          message
unchanged  term    4    7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
created    post    536  5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
created    post    537  208db72e-...  .../posts/acme_member/sam.208db72e.json

Os posts receberam novos IDs locais, 536 e 537. As referências acompanharam a mudança: o _acme_mentor de Sam agora contém 536, Jane voltou ao termo leadership, e o _thumbnail_id dela aponta para o anexo local com o UID correspondente. Os posts pais, os termos pais e as relações com termos são sempre armazenados como UIDs; os valores de metadados são reescritos somente para as chaves em meta.references.

Remover com segurança

Excluir um arquivo não exclui nada durante o envio, a menos que você solicite. Remova sam.208db72e.json e tente fazer a limpeza:

Shell
wp bs content push --prune
Código
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.

A execução simulada mostra o que seria removido:

Shell
wp bs content push --prune --dry-run
Código
action             entity  id   uid          message
...
would-prune-trash  post    537  208db72e-...

push --prune --yes então move o post de Sam para a lixeira e informa pruned-trash. Várias proteções mantêm o escopo restrito:

  • Apenas entidades pertencentes a este conjunto de conteúdo (content.id) são candidatas.
  • Apenas os tipos de post e as taxonomias configurados são considerados.
  • Todo o plano de origem é analisado e validado antes que algo seja gravado ou removido. Se houver um arquivo JSON malformado na pasta, o envio informa uma linha error, como could not be read: Syntax error, e nada é removido.

A ação padrão é trash. O filtro blockstudio/content/orphan_action pode retornar trash, delete ou keep para cada entidade. Assim, os termos são mantidos, enquanto os posts continuam com a ação padrão:

PHP
add_filter(
	'blockstudio/content/orphan_action',
	function ( string $action, string $type ) {
		return 'term' === $type ? 'keep' : $action;
	},
	10,
	2
);

Com isso, um termo órfão é informado como would-prune-keep em vez de would-prune-trash.

Mídia

Os arquivos de mídia nunca são copiados. content.media determina o que acontece com as referências declaradas a anexos:

  • "manifest" (padrão) armazena os UIDs dos anexos e os lista em content/media/manifest.json com o caminho, o tipo MIME e o texto alternativo. O envio exige que cada UID de anexo referenciado exista no destino; portanto, transfira os arquivos enviados usando primeiro o fluxo de trabalho de mídia habitual.
  • "none" exclui dos arquivos as referências declaradas a anexos. O JSON de Jane passa a conter apenas _acme_role. Como uma chave omitida não é aplicada no envio, um post já existente no destino mantém sua imagem em destaque atual.

Bloquear uma entidade

Às vezes, um ambiente de destino precisa manter sua própria versão de um post. Defina _blockstudio_content_locked nos metadados desse post com um valor verdadeiro, e o envio vai ignorá-lo, com uma linha locked e a mensagem “Entidade bloqueada ignorada.” Exclua os metadados para incluí-lo novamente.

Regras de propriedade

  • Por padrão, as publicações gerenciadas por páginas baseadas em arquivos são excluídas. Com includePageSyncManaged: true, o Content Sync pode sincronizar os metadados configurados delas, mas o Page Sync continua responsável pelo post_content. Essas projeções de JSON carregam bodyOwner: "page-sync", e a busca informa explicitamente que o corpo foi ignorado. As cópias de revisão .html existentes são preservadas e ignoradas pelo envio. Sincronize as páginas em um ambiente de destino antes de enviar as projeções de metadados.
  • Por padrão, os autores são ignorados porque os usuários não são sincronizados. Com authors: "login", os arquivos de publicação armazenam o login do autor, e o envio o associa a um usuário existente; a ausência de um usuário gera um erro de pré-verificação.
  • pull nunca exclui arquivos. Quando uma entidade do banco de dados deixa de existir, a busca informa que o arquivo está obsoleto e deixa a limpeza por sua conta.

Quando não usar

Content Sync é adequado para conteúdo selecionado e com poucas alterações: dezenas ou centenas de entradas, até alguns milhares quando os dados são estruturados e divididos em tipos de post específicos. Não substitui backups nem migrações de banco de dados. Pedidos, envios de formulários, registros, análises e conteúdo editorial de alto volume devem ser gerenciados por essas ferramentas. Definições de taxonomias, arquivos de mídia binários e IDs dentro da marcação de blocos estão fora do escopo.

Próximas etapas