Pereiti prie turinio

Duomenų bazės turinio perkėlimas į failus naudojant turinio sinchronizavimą

Blokai, šablonai ir iš failų sudaromi puslapiai jau yra jūsų saugykloje. Dalis turinio į šį modelį netelpa, nes jį administratoriuje sukuria redaktoriai: komandos nariai, biurų vietos, atvejų analizės. Šis turinys projektui vis tiek svarbus. Testinėje svetainėje reikia tokio pat komandos puslapio kaip ir produkcinėje, naujam kūrėjui reikia tikroviškų duomenų, o peržiūrintis asmuo nori matyti, kai kas nors pakeičia pareigų pavadinimą. Duomenų bazės kopijos šios problemos gerai neišsprendžia. Jose yra viskas, ID kiekvienoje aplinkoje skiriasi, be to, niekas neperžiūri SQL pakeitimų.

„Content Sync“ užpildo šią spragą. WP-CLI komanda perkelia į JSON ir HTML failus temoje leidžiamų įrašų, terminų, ryšių ir metaduomenų sąrašą. Kita komanda pritaiko šiuos failus kitoje duomenų bazėje. Kiekvienas objektas gauna perkeliamą UID, o ryšiai tarp objektų perrašomi tik ten, kur tai nurodote.

Šiame vadove žingsnis po žingsnio aptariamas komandos katalogas: kaip perkelti jį į failus, juos peržiūrėti ir redaguoti, perkelti į naują aplinką ir saugiai išvalyti.

Pavyzdys

Kiekvienoje aplinkoje tema registruoja acme_member įrašo tipą ir acme_team taksonomiją. Kiekviename nario įraše gali būti:

Meta raktas Turinys
_acme_role Pareigos, paprasta eilutė
_acme_mentor Kito nario įrašo ID
_thumbnail_id Portreto priedo ID
_acme_api_token Integravimo žetonas, kuris jokiu būdu neturi patekti į git

„Content Sync“ neregistruoja įrašų tipų ar taksonomijų. Jie turi būti sukurti visur, kur siunčiate duomenis.

1 žingsnis: sukonfigūruokite „Content Sync“

„Content Sync“ neveikia, kol jo neįjungiate blockstudio.json. Iki tol kiekviena komanda grąžina vieną skipped eilutę:

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

Pridėkite content grupę:

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

Kiekvienas raktas nustato ribas:

  • postTypes ir taxonomies yra leidžiamų reikšmių sąrašai. Už jų ribų niekas neskaitoma, neįrašoma ar nešalinama. Jei postTypes tuščias, įrašai neliečiami.
  • meta.include nurodo leidžiamus meta raktus, o * leidžia naudoti pakaitos simbolius. Jam visada teikiama pirmenybė prieš meta.exclude, o _edit_lock, _edit_last ir _wp_old_slug pagal numatytąsias nuostatas neįtraukiami.
  • meta.references nurodo, kurios meta reikšmės yra ID. „Content Sync“ nespėlioja, kad sveikasis skaičius yra ID.
  • id suteikia pavadinimą turinio rinkiniui. Jis įrašomas kiekviename sinchronizuojamame objekte, o šalinant paliečiami tik to paties rinkinio objektai.
  • path yra išvesties aplankas, nurodomas santykiniu keliu nuo aktyvios temos katalogo.

2 žingsnis: perkelkite į failus

Pirmiausia peržiūrėkite projekciją. Nieko neįrašoma, o rodomi UID dar neišsaugomi:

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

Tada perkelkite iš tikrųjų. Kiekvienam objektui, kuris dar neturi UID, priskiriamas nuolatinis _blockstudio_content_uid, o failai įrašomi:

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

Rezultatas temoje:

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

Failų pavadinimuose derinamas trumpinys ir pirmoji UID dalis. Įraše JSON saugomi laukai, terminų ryšiai ir leidžiami meta duomenys:

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

Termino ryšys ir miniatiūra yra UID, o ne vietiniai ID. Įrašo turinys laikomas šalia jo, jane.5d4bf9b5.html, kaip neapdorotas blokų žymėjimas. Įrašui be turinio, kaip Semo atveju, .html failas nesukuriamas. Semo _acme_mentor saugomas Džeinės UID, nes šis raktas nurodytas kaip post nuoroda.

3 žingsnis: peržiūrėkite prieš patvirtindami pakeitimus

Prieš patvirtindami pakeitimus paleiskite status. Ši komanda palygina failus su duomenų baze ir pažymi rizikingus duomenis:

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

_acme_* pakaitos simbolis aptiko žetoną. Laikykite meta.include pakeitimų patvirtinimo riba ir aiškiai neįtraukite šio rakto:

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

Kita pull komanda perrašo sam.208db72e.json be žetono ir nepakeičia kitų failų. status taip pat įspėja apie skaitinius ID blokų žymėjimo turinyje, nes „Content Sync“ neperrašo ID .html failuose.

Patvirtinkite aplanko content/ pakeitimus.

4 žingsnis: redaguokite failą ir perkelkite pakeitimus į duomenų bazę

Failai yra push tiesos šaltinis. Pakeiskite Jane vaidmenį faile JSON iš Design Lead į Head of Design, tada patikrinkite, kas nutiktų:

Shell
wp bs content status
Kodas
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 pateikia tą patį planą duomenų bazės atnaujinimo tvarka. Pritaikykite jį:

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

Prieš įrašydama duomenis, komanda patikrina visą planą. Neišspręstos nurodytos nuorodos, trumpinių konfliktai, trūkstami įrašų tipai ir netaisyklingi failai sustabdo procesą.

WordPress atnaujintam įrašui priskiria naują pakeitimo laiką, o faile lieka sena modified reikšmė. Todėl iškart po šio duomenų bazės atnaujinimo paleidus status, Džeinės įrašas nurodomas kaip conflict su pranešimu „Duomenų bazė pakeista po paskutinio sinchronizavimo.“ Po atnaujinimo vieną kartą paleiskite pull, kad būtų įrašytas naujas laikas; tada status nurodo unchanged.

5 žingsnis: perkelkite turinį į kitą aplinką

Naujoje aplinkoje failuose aprašyti įrašai dar neegzistuoja. Šiame pavyzdyje terminas ir portreto priedas joje jau yra ir turi tuos pačius UID, todėl trūksta tik dviejų narių:

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

Įrašams priskirti nauji vietiniai ID: 536 ir 537. Nuorodos atnaujintos: Semo _acme_mentor dabar turi 536, Džeinė vėl yra termino leadership narė, o jos _thumbnail_id nurodo į vietinį priedą su atitinkamu UID. Įrašų pirminiai įrašai, terminų pirminiai terminai ir terminų ryšiai visada saugomi kaip UID; meta reikšmės perrašomos tik tiems raktams, kurie įtraukti į meta.references.

Saugus šalinimas

Ištrynus failą, duomenys nepašalinami atnaujinant duomenų bazę, nebent to paprašote. Pašalinkite sam.208db72e.json ir pabandykite išvalyti:

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

Bandomasis vykdymas parodo, kas būtų pašalinta:

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

Tada push --prune --yes perkelia Semo įrašą į šiukšlinę ir pateikia pruned-trash. Šios apsaugos priemonės užtikrina, kad veiksmas būtų ribotas:

  • Kandidatais laikomi tik objektai, priklausantys šiam turinio rinkiniui (content.id).
  • Atsižvelgiama tik į sukonfigūruotus įrašų tipus ir taksonomijas.
  • Prieš įrašant ar šalinant duomenis išanalizuojamas ir patikrinamas visas šaltinio planas. Jei aplanke yra netaisyklingas JSON failas, atnaujinimo komanda pateikia error eilutę, pvz., could not be read: Syntax error, ir nieko nepašalina.

Numatytasis veiksmas yra trash. Filtras blockstudio/content/orphan_action gali kiekvienam objektui grąžinti trash, delete arba keep. Taip galima išsaugoti terminus, o įrašams palikti numatytąjį veiksmą:

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

Naudojant šį filtrą, našlaitis terminas nurodomas kaip would-prune-keep, o ne would-prune-trash.

Medija

Medijos failai niekada nekopijuojami. content.media nustato, kaip tvarkomos nurodytos priedų nuorodos:

  • Pagal numatytąsias nuostatas "manifest" saugo priedų UID ir pateikia juos faile content/media/manifest.json kartu su keliu, MIME tipu ir alternatyviuoju tekstu. Kad atnaujinimas pavyktų, kiekvienas nurodytas priedo UID turi egzistuoti tikslinėje aplinkoje, todėl pirmiausia perkelkite įkeltus failus įprastu medijos perkėlimo būdu.
  • "none" neįtraukia nurodytų priedų nuorodų į failus. Tuomet Džeinės JSON turi tik _acme_role. Kadangi atnaujinant praleistas raktas nepritaikomas, esamo įrašo miniatiūra tikslinėje aplinkoje išlieka nepakitusi.

Objekto užrakinimas

Kartais tikslinėje aplinkoje reikia išsaugoti vietinę įrašo versiją. Įrašykite tam įrašui į meta _blockstudio_content_locked reikšmę, kuri laikoma teisinga, ir atnaujinant duomenų bazę jis bus praleistas; pateikiama locked eilutė su pranešimu „Užrakintas objektas praleistas.“ Pašalinkite meta reikšmę, kad įrašas vėl būtų įtrauktas.

Nuosavybės taisyklės

  • Pagal numatytuosius nustatymus failais pagrįstų puslapių tvarkomi įrašai neįtraukiami. Naudojant includePageSyncManaged: true, „Content Sync“ gali sinchronizuoti jų sukonfigūruotus meta duomenis, tačiau jų post_content vis tiek tvarko „Page Sync“. Šios JSON projekcijos turi bodyOwner: "page-sync", o atliekant gavimą aiškiai pranešama apie praleistą turinį. Esamos .html peržiūros kopijos išsaugomos ir ignoruojamos siunčiant pakeitimus. Prieš siųsdami jų metaduomenų projekcijas, sinchronizuokite puslapius tikslinėje aplinkoje.
  • Pagal numatytuosius nustatymus autoriai ignoruojami, nes naudotojai nesinchronizuojami. Naudojant authors: "login", įrašų failuose saugomas autoriaus prisijungimo vardas, o siunčiant pakeitimus jis susiejamas su esamu naudotoju; jei naudotojo nėra, patikra prieš vykdymą pateikia klaidą.
  • pull failų niekada nešalina. Jei duomenų bazėje esantis objektas ištrinamas, gavimo metu pranešama, kad jo failas pasenęs, o jį išvalyti paliekama jums.

Kada šio įrankio nenaudoti

„Content Sync“ tinka atrinktam, retai keičiamam turiniui: dešimtims ar šimtams įrašų, o struktūruotiems duomenims, suskirstytiems į konkrečius įrašų tipus, galima naudoti ir kelis tūkstančius. Šis įrankis nepakeičia duomenų bazės atsarginių kopijų ar perkėlimo įrankių. Užsakymai, formų pateikimai, žurnalai, analitika ir didelės apimties redakcinis turinys turėtų būti tvarkomi kitais įrankiais. Taksonomijų apibrėžimai, dvejetainiai medijos failai ir ID blokų žymėjime nepatenka į jo aprėptį.

Tolesni žingsniai