Importando conteúdo para o WordPress com Blueprints

Um novo site do WordPress Playground começa com um conteúdo básico. Uma Blueprint pode ajudar a preencher este gap a partir de um arquivo de exportação do WordPress, gerar conteúdo com as APIs do WordPress ou restaurar um snapshot ZIP do Playground.

Este guia se concentra na escolha dos métodos de importação de conteúdo via blueprints criar um pequeno benchmark comparando estes três métodos de importação. Importação de dados podem ser úties para conteúdo inicial de temas, base de testes e conteúdo educacional para outras estratégias de criação de demonstrações, consulte Fornecer conteúdo para sua demonstração com o Playground.

Essas abordagens resolvem problemas diferentes:

Método	Melhor opção para	O que transfere
importWxr	Conteúdo portátil compartilhado entre sites WordPress ideal para importar o conteúdo sem sobrescrever o conteúdo antecessor	Posts, páginas, tipos de post personalizados, termos, autores, comentários e referências de anexos
runPHP	Pequenos conjuntos de dados determinísticos e lógica personalizada	Tudo o que o código PHP criar por meio das APIs do WordPress
importWordPressFiles	Restaurar uma demonstração completa do Playground	O banco de dados e os arquivos WordPress presentes no ZIP, como plugins, temas e arquivos enviados

Se você precisa apenas de posts e termos, comece com WXR. Se o conteúdo for gerado ou depender da lógica de configuração, use runPHP. Se o banco de dados, a mídia, os plugins, os temas e as configurações precisarem ser restaurados juntos, use um snapshot ZIP.

Importar uma exportação XML do WordPress com importWxr

O WordPress chama seu formato de exportação XML de WordPress eXtended RSS, ou WXR. Crie um em Ferramentas > Exportar em um site WordPress existente e depois forneça-o ao passo importWxr.

Este exemplo espera encontrar content.xml ao lado de blueprint.json em um pacote de Blueprint:

{
	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
	"landingPage": "/wp-admin/edit.php",
	"preferredVersions": {
		"php": "8.3",
		"wp": "7.0"
	},
	"login": true,
	"steps": [
		{
			"step": "importWxr",
			"file": {
				"resource": "bundled",
				"path": "/content.xml"
			},
			"fetchAttachments": false,
			"rewriteUrls": true,
			"importComments": false,
			"authorsMode": "default-author",
			"defaultAuthorUsername": "admin"
		}
	]
}

Para um arquivo hospedado, substitua o recurso bundled por um recurso url. Defina fetchAttachments como true quando o importador precisar baixar os arquivos de mídia referenciados pelo arquivo WXR. A transferência de rede pode dominar o tempo total de configuração, por isso o benchmark apresentado mais adiante desativa a obtenção de anexos.

O importWxr também pode mapear autores importados para usuários locais, criar usuários e aplicar substituições explícitas de URL. Consulte as opções de importWxr antes de importar conteúdo de outro domínio.

Vantagens

• Usa o formato padrão e portátil do WordPress para troca de conteúdo.
• Preserva tipos de post, taxonomias, metadados de posts, autores, comentários e relações de conteúdo representadas na exportação.
• Pode obter anexos e reescrever URLs de conteúdo antigas para o novo site.
• Mantém o conteúdo separado do núcleo do WordPress, dos plugins, dos temas e da maioria das configurações do site de destino.
• É fácil de inspecionar, pode ser editado manualmente por qualquer editor de texto, versionar e editar porque a origem está em XML.

Desvantagens

• Não clona o site inteiro. Plugins, temas, tabelas de plugins, opções e arquivos que não estão representados no WXR precisam de passos de Blueprint separados.
• A importação de anexos exige acesso à rede e depende da disponibilidade das URLs antigas de mídia.
• Arquivos XML grandes usam mais tempo de análise e memória do que a restauração de um banco de dados SQLite existente.
• Reimportar o mesmo arquivo pode criar duplicatas; esse não é um formato de sincronização idempotente.
• O Blueprint instala automaticamente a dependência WordPress Importer, o que adiciona trabalho de configuração antes do início da importação WXR.

Gerar conteúdo com runPHP

O passo runPHP pode chamar as APIs do WordPress diretamente. Sempre carregue /wordpress/wp-load.php antes de chamar funções como wp_insert_post().

O exemplo a seguir cria os 100 posts usados pelo benchmark:

{
	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
	"landingPage": "/wp-admin/edit.php",
	"preferredVersions": {
		"php": "8.3",
		"wp": "7.0"
	},
	"login": true,
	"steps": [
		{
			"step": "runPHP",
			"code": "<?php\nrequire_once '/wordpress/wp-load.php';\n\nfor ( $index = 1; $index <= 100; $index++ ) {\n\t$result = wp_insert_post(\n\t\tarray(\n\t\t\t'post_title'   => 'Benchmark post ' . $index,\n\t\t\t'post_content' => '<!-- wp:paragraph --><p>Blueprint import benchmark content.</p><!-- /wp:paragraph -->',\n\t\t\t'post_status'  => 'publish',\n\t\t\t'post_type'    => 'post',\n\t\t),\n\t\ttrue\n\t);\n\tif ( is_wp_error( $result ) ) {\n\t\tthrow new RuntimeException( $result->get_error_message() );\n\t}\n}"
		}
	]
}

Para programas maiores, mantenha o código em um pequeno plugin ou divida a configuração em passos específicos em vez de manter uma string JSON muito longa. Use as APIs do WordPress em vez de gravar diretamente nas tabelas do banco de dados para que os ganchos, caches e a validação de dados continuem funcionando.

Vantagens

• Oferece controle completo sobre os dados gerados e suas relações.
• Não exige arquivo de conteúdo nem acesso à rede.
• Pode configurar opções, metadados de posts, usuários, taxonomias e dados específicos de plugins na mesma operação.
• Funciona bem para pequenos dados de teste cuja fonte de verdade deve permanecer no código.
• Pode se tornar idempotente ao procurar registros existentes antes de criá-los.

Desvantagens

• O PHP personalizado é mais detalhado do que exportar conteúdo editorial existente.
• O script precisa tratar erros, novas execuções, dependências e falhas parciais.
• O código pode ficar acoplado às APIs ou ao modelo de banco de dados de um plugin.
• Criar muitos registros individualmente ainda executa os ganchos do WordPress e gravações no banco de dados para cada registro, portanto o desempenho piora à medida que o conjunto de dados cresce.
• Um Blueprint é uma entrada confiável. Execute PHP apenas de uma fonte em que você confia.

Restaurar um ZIP do Playground com importWordPressFiles

O passo importWordPressFiles é uma restauração de site, não uma importação apenas de conteúdo. Ele descompacta os arquivos WordPress de nível superior de um ZIP e substitui os caminhos correspondentes na nova instância. Um ZIP criado com a opção Download as zip do Playground inclui wp-content, seu banco de dados SQLite, os arquivos enviados e um manifesto usado para ajustar as URLs de escopo do Playground.

Coloque o arquivo baixado ao lado de blueprint.json e referencie-o como um recurso bundled:

{
	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
	"landingPage": "/",
	"preferredVersions": {
		"php": "8.3",
		"wp": "7.0"
	},
	"login": true,
	"steps": [
		{
			"step": "importWordPressFiles",
			"wordPressFilesZip": {
				"resource": "bundled",
				"path": "/site.zip"
			}
		}
	]
}

O ZIP pode conter apenas wp-content, um diretório WordPress completo ou um diretório WordPress aninhado em uma pasta externa. Use pathInZip quando o arquivo contiver vários sites ou quando a detecção automática da raiz não for suficiente.

Mantenha compatíveis as versões do WordPress, PHP, tema e plugin na origem e no destino. O passo atualiza o banco de dados importado e ajusta as URLs de escopo do Playground, mas não é uma ferramenta geral de migração para configurações arbitrárias de servidores de produção.

Vantagens

• Restaura juntos o banco de dados, os arquivos enviados, os plugins, os temas e as configurações.
• Preserva tabelas e opções específicas de plugins que o WXR não pode representar.
• Evita recriar cada post por meio das APIs do WordPress, o que pode ser eficiente para uma demonstração preparada e repetível.
• Funciona offline quando o snapshot está incluído no pacote do Blueprint.
• Produz a cópia mais próxima da instância de origem do Playground.

Desvantagens

• Substitui todos os caminhos de nível superior presentes no ZIP, por isso pode sobrescrever o estado atual do site em vez de mesclar conteúdo a ele.
• É maior, menos transparente e mais difícil de revisar ou resolver em mesclagens de controle de versão.
• Acopla o snapshot às versões do WordPress, PHP, tema, plugin e banco de dados de forma mais rígida que o WXR.
• Não é adequado para importar posts selecionados em um site existente.
• Deve ser restaurado apenas de uma fonte confiável; pode conter PHP executável e um banco de dados inteiro.

Resultado dos testes entre os diferentes métodos

O resultado dos testes a seguir foi medido em 13 de julho de 2026, em um Apple M4 Pro com 24 GB de memória. Foram usados Node.js 22.16, WordPress 7.0, PHP 8.3, 100 posts e cinco rodadas com um site novo para cada método:

Método	Tamanho da entrada	Mediana	Mínimo	Máximo	Em relação ao mais rápido
XML / importWxr	106.0 KiB	2.21 s	2.16 s	2.25 s	6.90x
PHP / runPHP	Código gerado	2.78 s	2.76 s	2.80 s	8.68x
ZIP / importWordPressFiles	50.5 KiB	320 ms	318 ms	322 ms	1.00x

Considere esses valores como referência de uma única máquina, não como uma classificação universal. O formato do conjunto de dados importa: os anexos favorecem um ZIP autocontido, ganchos complexos do WordPress podem tornar runPHP mais lento e a portabilidade do WXR pode ser mais importante que a velocidade bruta.

Outras fontes de conteúdo

Os Blueprints também oferecem suporte a importThemeStarterContent para o conteúdo inicial registrado de um tema e ao passo wp-cli para comandos como wp post generate. Eles são úteis quando o tema ou o comando WP-CLI já é a fonte canônica dos dados da demonstração, mas estão fora deste benchmark de importação de conteúdo.