Spostare i contenuti del database nei file con la sincronizzazione dei contenuti
I blocchi, i template e le pagine basate su file si trovano già nel vostro repository. Alcuni contenuti non si adattano a questo modello, perché vengono creati dagli editor nell’area di amministrazione: membri del team, sedi, casi di studio. Anche questi contenuti sono importanti per il progetto. Un sito di staging deve avere la stessa pagina del team della produzione, un nuovo sviluppatore ha bisogno di dati realistici e un revisore dovrebbe vedere quando qualcuno modifica il titolo di una posizione lavorativa. I dump del database non risolvono bene nessuno di questi problemi. Contengono tutto, gli ID variano da un ambiente all’altro e nessuno rivede un diff SQL.
Content Sync colma questa lacuna. Un comando WP-CLI proietta una lista consentita di articoli, termini, relazioni e metadati in file JSON e HTML nel tema. Un altro comando applica questi file a un database diverso. Ogni entità riceve un UID portatile e i riferimenti tra entità vengono riscritti solo nei casi dichiarati.
Questa guida illustra una directory del team: trasferirla nei file, esaminarla, modificare un file, spostarla in un nuovo ambiente ed eseguire la pulizia in sicurezza.
L’esempio
Il tema registra un tipo di contenuto acme_member e una tassonomia acme_team in
ogni ambiente. Ogni articolo membro può contenere:
| Chiave meta | Contiene |
|---|---|
_acme_role |
La mansione, una semplice stringa |
_acme_mentor |
L’ID dell’articolo di un altro membro |
_thumbnail_id |
L’ID dell’allegato del ritratto |
_acme_api_token |
Un token di integrazione che non deve mai finire in git |
Content Sync non registra mai tipi di contenuto o tassonomie. Devono esistere ovunque si esegua il push.
Passaggio 1: configurare Content Sync
Content Sync è disattivato finché non lo abilitate in blockstudio.json. Fino ad allora, ogni
comando restituisce una sola riga skipped:
wp bs content status
action entity id uid message
skipped content default Content Sync is disabled. Set content.enabled to true to run this command.
Aggiungete un gruppo content:
{
"$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"
}
}
Ogni chiave definisce un limite:
postTypesetaxonomiessono liste consentite. Non si legge, scrive o elimina nulla al di fuori di esse. SepostTypesè vuota, non viene modificato alcun articolo.meta.includedefinisce le chiavi meta consentite, con i caratteri jolly*.meta.excludeha sempre la precedenza, mentre_edit_lock,_edit_laste_wp_old_slugsono esclusi per impostazione predefinita.meta.referencesdichiara quali valori meta sono ID. Content Sync non presume mai che un intero sia un ID.idindica il gruppo di contenuti. Viene salvato in ogni entità sincronizzata e la pulizia interessa solo le entità dello stesso gruppo.pathè la cartella di output, relativa alla directory del tema attivo.
Passaggio 2: eseguire il pull
Prima visualizzate un’anteprima della proiezione. Non viene scritto nulla e gli UID mostrati non sono ancora salvati:
wp bs content pull --dry-run
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
Poi eseguite il pull effettivo. Assegna un _blockstudio_content_uid permanente a ogni
entità che non ne ha uno e scrive i file:
wp bs content pull
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
Risultato nel tema:
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
I nomi dei file combinano lo slug con la prima parte dell’UID. L’articolo JSON contiene i campi, le relazioni tra termini e i metadati consentiti:
{
"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"
}
}
La relazione con il termine e la miniatura sono UID, non ID locali. Il corpo dell’articolo
si trova accanto, in jane.5d4bf9b5.html, come markup grezzo dei blocchi. Un articolo con contenuto vuoto,
come quello di Sam, non riceve alcun file .html. Il valore _acme_mentor di Sam è salvato come
UID di Jane, perché la chiave è dichiarata come riferimento post.
Passaggio 3: esaminare prima del commit
Eseguite status prima del commit. Confronta i file con il database e segnala anche
i dati a rischio:
wp bs content status
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.
Il carattere jolly _acme_* ha intercettato il token. Considerate meta.include un limite per il commit
e escludete esplicitamente la chiave:
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
Il successivo pull riscrive sam.208db72e.json senza il token e lascia invariati gli altri file. Anche status avvisa della presenza di ID numerici nei corpi del markup dei blocchi, perché Content Sync non riscrive gli ID nei file .html.
Eseguite il commit della cartella content/.
Passaggio 4: modificare un file ed eseguire il push
I file sono la fonte di verità per push. Modificate il ruolo di Jane nel file JSON
da Design Lead a Head of Design, poi verificate cosa succederebbe:
wp bs content status
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 stampa lo stesso piano nell’ordine del push. Applicatelo:
wp bs content push
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
Il push convalida l’intero piano prima di scrivere. Riferimenti dichiarati non risolti, conflitti tra slug, tipi di contenuto mancanti e file malformati ne interrompono l’esecuzione.
WordPress assegna all’articolo aggiornato una nuova data di modifica, mentre il file conserva il vecchio valore modified. Pertanto, un’esecuzione di status subito dopo questo push segnala l’articolo di Jane come conflict con «Database changed since last sync.» Eseguite pull una volta dopo il push per acquisire la nuova data; a quel punto status segnalerà unchanged.
Passaggio 5: spostare i contenuti in un altro ambiente
In un ambiente nuovo, i file descrivono articoli che ancora non esistono. In questo esempio, il termine e l’allegato del ritratto sono già presenti con gli stessi UID, quindi mancano solo i due membri:
wp bs content status
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
wp bs content push
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
Gli articoli hanno ricevuto nuovi ID locali, 536 e 537. I riferimenti li hanno seguiti: il campo _acme_mentor di Sam ora contiene 536, Jane si trova di nuovo nel termine leadership e il suo campo _thumbnail_id punta all’allegato locale con l’UID corrispondente. I genitori degli articoli, i genitori dei termini e le relazioni tra termini sono sempre salvati come UID; i valori meta vengono riscritti solo per le chiavi in meta.references.
Eseguire la pulizia in sicurezza
Eliminare un file non elimina nulla durante il push, a meno che non lo chiediate. Rimuovete
sam.208db72e.json e provate a eseguire la pulizia:
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
L’esecuzione di prova mostra cosa verrebbe rimosso:
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
push --prune --yes sposta quindi l’articolo di Sam nel cestino e segnala pruned-trash. Diverse protezioni ne limitano l’ambito:
- Sono candidati solo le entità appartenenti a questo gruppo di contenuti (
content.id). - Vengono presi in considerazione solo i tipi di contenuto e le tassonomie configurati.
- L’intero piano di origine viene analizzato e convalidato prima di qualsiasi scrittura o eliminazione.
Se nella cartella è presente un file JSON malformato, il push segnala una riga
errorcomecould not be read: Syntax errore non elimina nulla.
L’azione predefinita è trash. Il filtro blockstudio/content/orphan_action
può restituire trash, delete o keep per ogni entità. In questo modo i termini vengono mantenuti, mentre per gli articoli resta valida l’impostazione predefinita:
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
Così, un termine orfano viene segnalato come would-prune-keep invece che come
would-prune-trash.
Media
I file multimediali non vengono mai copiati. content.media determina cosa accade ai riferimenti dichiarati agli allegati:
"manifest"(predefinito) salva gli UID degli allegati e li elenca incontent/media/manifest.jsoncon percorso, tipo MIME e testo alternativo. Per il push è necessario che ogni UID di allegato referenziato esista nella destinazione; quindi, prima spostate i file caricati con il vostro consueto flusso di lavoro per i media."none"esclude dai file i riferimenti dichiarati agli allegati. Il campo JSON di Jane contiene quindi solo_acme_role. Poiché le chiavi omesse non vengono applicate durante il push, un articolo già presente nella destinazione conserva la miniatura corrente.
Bloccare un’entità
A volte un ambiente di destinazione deve conservare la propria versione di un articolo. Impostate
il meta _blockstudio_content_locked su un valore vero per quell’articolo e il push lo salterà con una riga locked e il messaggio «Locked entity skipped.» Eliminate il meta per includere di nuovo l’articolo.
Regole di proprietà
- I post gestiti da pagine basate su file sono esclusi per impostazione predefinita. Con
includePageSyncManaged: true, Content Sync può sincronizzare i metadati configurati, ma Page Sync resta responsabile del loropost_content. Queste proiezioni JSON includonobodyOwner: "page-sync"e il pull segnala esplicitamente il corpo ignorato. Le copie di revisione esistenti.htmlvengono conservate e ignorate dal push. Sincronizzate le pagine nell’ambiente di destinazione prima di eseguire il push delle proiezioni dei metadati. - Gli autori vengono ignorati per impostazione predefinita perché gli utenti non vengono sincronizzati. Con
authors: "login", i file dei post memorizzano il login dell’autore e il push lo associa a un utente esistente; se l’utente non esiste, si verifica un errore di preflight. pullnon elimina mai i file. Quando un’entità del database non esiste più, il pull segnala il file come obsoleto e lascia la pulizia a voi.
Quando non usarlo
Content Sync è adatto a contenuti selezionati e aggiornati di rado: decine o centinaia di voci, fino a qualche migliaio se i dati sono strutturati e suddivisi in tipi di contenuto specifici. Non sostituisce i backup o le migrazioni del database. Gli ordini, gli invii di moduli, i log, le analisi e i contenuti editoriali ad alto volume vanno gestiti con quegli strumenti. Le definizioni delle tassonomie, i file binari multimediali e gli ID nei markup dei blocchi esulano dal suo ambito.
Passaggi successivi
- Riferimento di Content Sync: tutte le chiavi di configurazione, i formati dei file e lo stato di sincronizzazione salvato.
- Creare un sito di documentazione: contenuti che partono dai file e si sincronizzano in WordPress, in direzione opposta.
- Creare pagine basate su file: pagine la cui struttura è gestita dai template nel tema.