Treci la conținut

Mutarea conținutului din baza de date în fișiere cu Sincronizarea conținutului

Blocurile, șabloanele și paginile bazate pe fișiere se află deja în depozitul proiectului. Unele tipuri de conținut nu se potrivesc acestui model, deoarece editorii le creează în zona de administrare: membrii echipei, locațiile birourilor, studiile de caz. Acest conținut rămâne important pentru proiect. Un site de pregătire are nevoie de aceeași pagină a echipei ca site-ul de producție, un dezvoltator nou are nevoie de date realiste, iar un evaluator ar trebui să observe când cineva schimbă titlul unui post. Exporturile bazei de date nu rezolvă bine niciuna dintre aceste nevoi. Ele includ totul, ID-urile diferă de la un mediu la altul și nimeni nu verifică diferențele din SQL.

Content Sync acoperă acest gol. O comandă WP-CLI proiectează o listă permisă de articole, termeni, relații și metadate în fișierele JSON și HTML din tema dvs. O altă comandă aplică aceste fișiere într-o bază de date diferită. Fiecare entitate primește un UID portabil, iar referințele dintre entități sunt rescrise numai acolo unde declarați acest lucru.

Acest ghid parcurge exemplul unui director de echipă: exportarea sa în fișiere, revizuirea acestora, editarea unui fișier, mutarea într-un mediu nou și curățarea în siguranță.

Exemplul

Tema înregistrează un tip de articol acme_member și o taxonomie acme_team în fiecare mediu. Fiecare articol al unui membru poate conține:

Cheie meta Conține
_acme_role Funcția, un șir simplu
_acme_mentor ID-ul articolului unui alt membru
_thumbnail_id ID-ul atașamentului pentru portret
_acme_api_token Un token de integrare care nu trebuie să ajungă niciodată la git

Content Sync nu înregistrează niciodată tipuri de articole sau taxonomii. Acestea trebuie să existe oriunde trimiteți date.

Pasul 1: Configurați Content Sync

Content Sync este dezactivat până când îl activați în blockstudio.json. Până atunci, fiecare comandă returnează un singur rând skipped:

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

Adăugați un grup 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"
  }
}

Fiecare cheie stabilește o limită:

  • postTypes și taxonomies sunt liste de permisiuni. Nimic din afara lor nu este citit, scris sau eliminat. O valoare postTypes goală înseamnă că nu sunt atinse articole.
  • meta.include stabilește lista de permisiuni pentru cheile meta, cu metacaractere *. meta.exclude are întotdeauna prioritate, iar _edit_lock, _edit_last și _wp_old_slug sunt excluse implicit.
  • meta.references declară care valori meta sunt ID-uri. Content Sync nu presupune niciodată că un număr întreg este un ID.
  • id denumește setul de conținut. Este stocat pe fiecare entitate sincronizată, iar eliminarea vizează numai entitățile din același set.
  • path este dosarul de ieșire, relativ la directorul temei active.

Pasul 2: Extragerea

Previzualizați mai întâi proiecția. Nu se scrie nimic, iar UID-urile afișate nu sunt încă stocate:

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

Apoi extrageți datele efectiv. Astfel se atribuie un _blockstudio_content_uid permanent fiecărei entități care nu are unul și se scriu fișierele:

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

Rezultatul în temă:

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

Numele fișierelor combină slugul cu prima parte a UID-ului. Articolul JSON conține câmpurile, relațiile dintre termeni și metadatele permise:

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

Relația cu termenul și miniatura sunt UID-uri, nu ID-uri locale. Corpul articolului se află alături, în jane.5d4bf9b5.html, ca marcaj brut de bloc. Un articol cu conținut gol, precum cel al lui Sam, nu primește niciun fișier .html. Valoarea _acme_mentor a lui Sam este stocată ca UID-ul lui Jane, deoarece cheia este declarată drept referință post.

Pasul 3: Revizuiți înainte de confirmare

Rulați status înainte de confirmare. Compară fișierele cu baza de date și semnalează și datele riscante:

Shell
wp bs content status
Cod
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.

Metacaracterul _acme_* a identificat tokenul. Tratați meta.include ca pe o limită pentru confirmare și excludeți explicit cheia:

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

Următoarea comandă pull rescrie sam.208db72e.json fără token și lasă celelalte fișiere nemodificate. status avertizează și asupra ID-urilor numerice din corpurile cu marcaj de bloc, deoarece Content Sync nu rescrie ID-urile din fișierele .html.

Confirmați dosarul content/.

Pasul 4: Editați un fișier și trimiteți-l

Fișierele sunt sursa de adevăr pentru push. Schimbați funcția lui Jane în fișierul JSON din Design Lead în Head of Design, apoi verificați ce s-ar întâmpla:

Shell
wp bs content status
Cod
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 afișează același plan în ordinea trimiterii. Aplicați-l:

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

Trimiterea validează întregul plan înainte de a scrie. Referințele declarate nerezolvate, conflictele de sluguri, tipurile de articole lipsă și fișierele malformate opresc procesul.

WordPress atribuie unui articol actualizat o nouă oră de modificare, în timp ce fișierul păstrează valoarea modified veche. Prin urmare, o rulare status imediat după această trimitere raportează articolul lui Jane ca conflict, cu mesajul „Baza de date s-a schimbat de la ultima sincronizare”. Rulați pull o dată după trimitere pentru a înregistra noua oră; apoi, status raportează unchanged.

Pasul 5: Mutați conținutul într-un alt mediu

Într-un mediu nou, fișierele descriu articole care încă nu există. În acest exemplu, termenul și atașamentul portretului există deja acolo cu aceleași UID-uri, așa că lipsesc doar cei doi membri:

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

Articolele au primit ID-uri locale noi, 536 și 537. Referințele au fost actualizate: valoarea _acme_mentor a lui Sam conține acum 536, Jane se află din nou în termenul leadership, iar valoarea _thumbnail_id a ei indică atașamentul local cu UID-ul corespunzător. Articolele părinte, termenii părinte și relațiile dintre termeni sunt întotdeauna stocate ca UID-uri; valorile meta sunt rescrise numai pentru cheile din meta.references.

Eliminarea în siguranță

Ștergerea unui fișier nu șterge nimic la trimitere decât dacă solicitați acest lucru. Eliminați sam.208db72e.json și încercați să curățați:

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

Rularea de probă arată ce ar fi eliminat:

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

Apoi, push --prune --yes mută articolul lui Sam în coșul de gunoi și raportează pruned-trash. Mai multe măsuri de protecție mențin acțiunea limitată:

  • Sunt eligibile numai entitățile deținute de acest set de conținut (content.id).
  • Sunt luate în considerare numai tipurile de articole și taxonomiile configurate.
  • Întregul plan sursă este analizat și validat înainte de orice scriere sau eliminare. Dacă în dosar se află un fișier JSON malformat, trimiterea raportează un rând error, precum could not be read: Syntax error, și nu elimină nimic.

Acțiunea implicită este trash. Filtrul blockstudio/content/orphan_action poate returna trash, delete sau keep pentru fiecare entitate. Astfel, termenii sunt păstrați, iar articolele folosesc acțiunea implicită:

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

Cu această setare, un termen orfan este raportat ca would-prune-keep în loc de would-prune-trash.

Fișiere media

Fișierele media nu sunt niciodată copiate. content.media stabilește ce se întâmplă cu referințele declarate la atașamente:

  • "manifest" (implicit) stochează UID-urile atașamentelor și le listează în content/media/manifest.json împreună cu calea, tipul MIME și textul alternativ. Trimiterea necesită ca fiecare UID de atașament referit să existe în destinație, așa că mutați mai întâi încărcările folosind fluxul obișnuit pentru fișiere media.
  • "none" omite din fișiere referințele declarate la atașamente. Atunci, valoarea JSON a lui Jane conține doar _acme_role. Deoarece o cheie omisă nu este aplicată la trimitere, un articol existent în destinație își păstrează miniatura curentă.

Blocarea unei entități

Uneori, un mediu destinație trebuie să-și păstreze propria versiune a unui articol. Setați metadatele _blockstudio_content_locked la o valoare truthy pentru articolul respectiv, iar trimiterea îl va omite și va afișa un rând locked cu mesajul „Entitate blocată omisă”. Ștergeți metadatele pentru a-l include din nou.

Reguli privind proprietatea

  • Postările gestionate de pagini bazate pe fișiere sunt excluse implicit. Cu includePageSyncManaged: true, Content Sync poate sincroniza metadatele configurate ale acestora, dar Page Sync rămâne responsabil de post_content. Aceste proiecții JSON conțin bodyOwner: "page-sync", iar operațiunea pull raportează explicit corpul omis. Copiile de revizuire .html existente sunt păstrate și ignorate de push. Sincronizați paginile într-un mediu țintă înainte de a trimite proiecțiile metadatelor.
  • Autorii sunt ignorați implicit, deoarece utilizatorii nu sunt sincronizați. Cu authors: "login", fișierele postărilor stochează numele de autentificare al autorului, iar push îl asociază unui utilizator existent; lipsa utilizatorului este o eroare la verificarea preliminară.
  • pull nu șterge niciodată fișiere. Când o entitate din baza de date dispare, pull raportează fișierul ca învechit și vă lasă curățarea în seama dumneavoastră.

Când să nu-l folosiți

Content Sync este potrivit pentru conținut selectat, care se schimbă rar: zeci sau sute de înregistrări, până la câteva mii dacă datele sunt structurate și împărțite în tipuri de articole bine delimitate. Nu înlocuiește copiile de rezervă ale bazei de date sau migrările. Comenzile, trimiterile de formulare, jurnalele, analizele și conținutul editorial cu volum mare țin de alte instrumente. Definițiile taxonomiilor, fișierele media binare și ID-urile din marcajul blocurilor nu intră în domeniul său de aplicare.

Pașii următori