Vai al contenuto

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:

Shell
wp bs content status
Codice
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:

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"
  }
}

Ogni chiave definisce un limite:

  • postTypes e taxonomies sono liste consentite. Non si legge, scrive o elimina nulla al di fuori di esse. Se postTypes è vuota, non viene modificato alcun articolo.
  • meta.include definisce le chiavi meta consentite, con i caratteri jolly *. meta.exclude ha sempre la precedenza, mentre _edit_lock, _edit_last e _wp_old_slug sono esclusi per impostazione predefinita.
  • meta.references dichiara quali valori meta sono ID. Content Sync non presume mai che un intero sia un ID.
  • id indica 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:

Shell
wp bs content pull --dry-run
Codice
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:

Shell
wp bs content pull
Codice
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:

Codice
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:

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"
    }
}

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:

Shell
wp bs content status
Codice
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:

JSON
"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:

Shell
wp bs content status
Codice
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:

Shell
wp bs content push
Codice
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:

Shell
wp bs content status
Codice
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
Codice
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:

Shell
wp bs content push --prune
Codice
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:

Shell
wp bs content push --prune --dry-run
Codice
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 error come could not be read: Syntax error e 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:

PHP
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 in content/media/manifest.json con 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 loro post_content. Queste proiezioni JSON includono bodyOwner: "page-sync" e il pull segnala esplicitamente il corpo ignorato. Le copie di revisione esistenti .html vengono 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.
  • pull non 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