Adatbázis-tartalom áthelyezése fájlokba a Content Sync segítségével
A blokkok, sablonok és fájlalapú oldalak már a tárházadban élnek. Néhány tartalom azonban nem illik ebbe a modellbe, mert a szerkesztők hozzák létre az adminfelületen: csapattagok, irodai helyszínek, esettanulmányok. Ez a tartalom is fontos a projekt számára. Az éles oldallal megegyező csapatoldalra van szükség az előkészítő környezetben, egy új fejlesztőnek valósághű adatokra van szüksége, egy ellenőrnek pedig látnia kell, ha valaki módosít egy munkaköri megnevezést. Az adatbázis-dumpok egyik problémát sem oldják meg jól. Mindent tartalmaznak, a környezetekben eltérnek az azonosítók, és senki sem vizsgálja át a SQL diffet.
A Content Sync áthidalja ezt a hiányt. Egy WP-CLI parancs a bejegyzések, kifejezések, kapcsolatok és metaadatok engedélyezési listáját JSON és HTML fájlokba vetíti a sablonban. Egy másik parancs ezeket a fájlokat egy másik adatbázisra alkalmazza. Minden entitás hordozható UID-t kap, az entitások közötti hivatkozások pedig csak ott íródnak át, ahol ezt deklarálja.
Ez az útmutató egy csapatnévjegyzéken keresztül mutatja be a folyamatot: fájlokba mentés, áttekintés, egy fájl szerkesztése, átvitel egy új környezetbe, majd biztonságos ritkítás.
A példa
A sablon minden környezetben regisztrál egy acme_member bejegyzéstípust és egy acme_team taxonómiát. Minden tag bejegyzése a következőket tartalmazhatja:
| Meta kulcs | Tartalom |
|---|---|
_acme_role |
A munkakör megnevezése, egyszerű szövegként |
_acme_mentor |
Egy másik tag bejegyzésazonosítója |
_thumbnail_id |
A portré csatolmányazonosítója |
_acme_api_token |
Integrációs token, amely soha nem kerülhet ide: git |
A Content Sync soha nem regisztrál bejegyzéstípusokat vagy taxonómiákat. Ezeknek minden olyan környezetben létezniük kell, ahová feltölt.
1. lépés: A Content Sync beállítása
A Content Sync alapértelmezés szerint ki van kapcsolva; a blockstudio.json beállításban kell engedélyeznie. Addig minden parancs egyetlen skipped sort ad vissza:
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.
Adjon hozzá egy content csoportot:
{
"$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"
}
}
Minden kulcs határt szab:
- A
postTypesés ataxonomiesengedélyezési listák. Rajtuk kívül semmi sem kerül beolvasásra, módosításra vagy ritkításra. Az ürespostTypesesetén egyetlen bejegyzés sem érintett. - A
meta.includea meta kulcsok engedélyezési listája, a*helyettesítő karakterekkel. Ameta.excludemindig elsőbbséget élvez, a_edit_lock,_edit_lastés_wp_old_slugpedig alapértelmezés szerint ki vannak zárva. - A
meta.referencesdeklarálja, hogy mely metaértékek azonosítók. A Content Sync nem találgatja ki, hogy egy egész szám azonosító-e. - A
idnevezi meg a tartalomkészletet. Minden szinkronizált entitásnál tárolódik, a ritkítás pedig csak az azonos készlethez tartozó entitásokat érinti. - A
patha kimeneti mappa, az aktív sablon könyvtárához képest megadva.
2. lépés: Lehívás
Először tekintse meg az előnézetet. Semmi nem íródik ki, a megjelenített UID-k pedig még nem tárolódnak:
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
Ezután végezze el a tényleges lehívást. Ez minden olyan entitáshoz állandó _blockstudio_content_uid értéket rendel, amelynek még nincs, majd kiírja a fájlokat:
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
Az eredmény a sablonban:
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
A fájlnevek a slugot és az UID első részét egyesítik. A bejegyzés JSON mezőket, kifejezéskapcsolatokat és az engedélyezett metaadatokat tartalmaz:
{
"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"
}
}
A kifejezéskapcsolat és az indexkép UID-ket használ, nem helyi azonosítókat. A bejegyzés törzse mellette található a jane.5d4bf9b5.html fájlban, nyers blokkjelölésként. Az üres tartalmú bejegyzésekhez, például Saméhez, nem készül .html fájl. Sam _acme_mentor értéke Jane UID-jeként tárolódik, mert a kulcs post hivatkozásként van deklarálva.
3. lépés: Áttekintés véglegesítés előtt
Véglegesítés előtt futtassa a status parancsot. Összehasonlítja a fájlokat az adatbázissal, és kockázatos adatokat is jelez:
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.
A _acme_* helyettesítő karakter elkapta a tokent. Kezelje a meta.include értéket véglegesítési határként, és zárja ki explicit módon a kulcsot:
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
A következő pull parancs token nélkül újraírja a sam.208db72e.json fájlt, a többi fájlt pedig érintetlenül hagyja. A status a blokkjelölést tartalmazó bejegyzéstörzsekben lévő numerikus azonosítókra is figyelmeztet, mert a Content Sync nem írja át az azonosítókat a .html fájlokban.
Véglegesítse a content/ mappát.
4. lépés: Fájl szerkesztése és feltöltés
A push esetében a fájlok az igazság forrásai. Módosítsa Jane szerepét a JSON fájlban Design Lead értékről Head of Design értékre, majd ellenőrizze, mi történne:
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
A push --dry-run parancs ugyanazt a tervet írja ki, a feltöltési sorrendben. Alkalmazza:
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
A feltöltés írás előtt ellenőrzi a teljes tervet. A fel nem oldott deklarált hivatkozások, a slugütközések, a hiányzó bejegyzéstípusok és a hibás fájlok leállítják a folyamatot.
A WordPress új módosítási időt állít be a frissített bejegyzésnek, miközben a fájlban továbbra is a régi modified érték szerepel. Ezért egy közvetlenül a feltöltés után futtatott status Jane bejegyzését conflict állapotúként jelzi a „Database changed since last sync.” üzenettel. A feltöltés után egyszer futtassa a pull parancsot az új idő rögzítéséhez; ekkor a status már unchanged állapotot jelez.
5. lépés: Tartalom átvitele másik környezetbe
Egy új környezetben a fájlok még nem létező bejegyzéseket írnak le. Ebben a példában a kifejezés és a portrémelléklet már ott van ugyanazokkal az UID-kkel, így csak a két tag hiányzik:
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
A bejegyzések új helyi azonosítókat kaptak: 536 és 537. A hivatkozások is követték az áthelyezést: Sam _acme_mentor értéke most 536, Jane ismét a leadership kifejezéshez tartozik, az ő _thumbnail_id értéke pedig a megfelelő UID-jű helyi mellékletre mutat. A bejegyzésszülők, a kifejezésszülők és a kifejezéskapcsolatok mindig UID-ként tárolódnak; a metaértékek pedig csak a meta.references kulcsoknál íródnak át.
Biztonságos ritkítás
Egy fájl törlése feltöltéskor önmagában nem töröl semmit. Távolítsa el a sam.208db72e.json fájlt, majd próbálja ki a ritkítást:
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
A próbaüzem megmutatja, mi kerülne törlésre:
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
A push --prune --yes ezután a kukába helyezi Sam bejegyzését, és pruned-trash értéket jelez. Több védőkorlát is szűken tartja a műveletet:
- Csak az ehhez a tartalomkészlethez tartozó entitások (
content.id) jelölhetők ki. - Csak a beállított bejegyzéstípusokat és taxonómiákat veszi figyelembe.
- A teljes forrásterv feldolgozása és ellenőrzése megtörténik, mielőtt bármi íródna vagy ritkításra kerülne. Ha hibás JSON fájl van a mappában, a feltöltés egy olyan
errorsort jelez, mint acould not be read: Syntax error, és semmit nem ritkít.
Az alapértelmezett művelet trash. A blockstudio/content/orphan_action szűrő entitásonként trash, delete vagy keep értéket adhat vissza. Így a kifejezések megmaradnak, miközben a bejegyzések az alapértelmezett beállítást követik:
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
Ezzel az árva kifejezés would-prune-keep értékként jelenik meg a would-prune-trash helyett.
Média
A médiafájlok soha nem másolódnak át. A content.media határozza meg, mi történjen a deklarált mellékletekre mutató hivatkozásokkal:
- A
"manifest"(alapértelmezett) melléklet-UID-ket tárol, és felsorolja őket acontent/media/manifest.jsonfájlban az elérési úttal, a MIME típussal és az alternatív szöveggel együtt. A feltöltéshez minden hivatkozott melléklet UID-jének léteznie kell a célkörnyezetben, ezért előbb a szokásos médiafolyamattal vigye át a feltöltéseket. - A
"none"kihagyja a deklarált mellékletekre mutató hivatkozásokat a fájlokból. Jane JSON fájlja ekkor csak a_acme_roleértéket tartalmazza. Mivel a kihagyott kulcsot a feltöltés nem alkalmazza, a célbejegyzés megtartja a jelenlegi indexképét.
Entitás zárolása
Előfordulhat, hogy egy célkörnyezetben meg kell tartani egy bejegyzés saját verzióját. Állítson be igaz értéket a bejegyzés _blockstudio_content_locked metaadatánál; ekkor a feltöltés kihagyja azt egy locked sorral és a „Locked entity skipped.” üzenettel. A metaadat törlésével ismét bevonhatja.
Tulajdonlási szabályok
- A fájlalapú oldalak által kezelt bejegyzések alapértelmezés szerint kimaradnak. A
includePageSyncManaged: truehasználatával a Content Sync szinkronizálhatja a beállított metaadatokat, de a Page Sync továbbra is apost_contentkezeléséért felel. Ezek a JSON kivetítésekbodyOwner: "page-sync"elemet tartalmaznak, a pull pedig külön jelzi a kihagyott törzset. A meglévő.htmlfelülvizsgálati példányok megmaradnak, és a push figyelmen kívül hagyja őket. A metaadat-kivetítések pusholása előtt szinkronizálja az oldalakat a célkörnyezetben. - A szerzők alapértelmezés szerint kimaradnak, mert a felhasználók nincsenek szinkronizálva. A
authors: "login"használatakor a bejegyzésfájlok a szerző bejelentkezési nevét tárolják, a push pedig egy meglévő felhasználóhoz rendeli azt; a hiányzó felhasználó előzetes ellenőrzési hibát okoz. - A
pullsoha nem töröl fájlokat. Ha egy adatbázisbeli entitás megszűnik, a pull elavultként jelzi a fájlt, a tisztítást pedig Önre bízza.
Mikor ne használja
A Content Sync válogatott, ritkán változó tartalomhoz való: néhány tucat vagy néhány száz bejegyzéshez, strukturált adatok esetén akár néhány ezerhez, külön erre szolgáló bejegyzéstípusokra bontva. Nem helyettesíti az adatbázis-mentéseket vagy az áttelepítéseket. A rendelések, űrlapbeküldések, naplók, analitikai adatok és nagy mennyiségű szerkesztőségi tartalom ezekhez a megoldásokhoz tartoznak. A taxonómia-definíciók, a bináris médiafájlok és a blokkjelölésben lévő azonosítók kívül esnek a hatókörén.
Következő lépések
- Content Sync referencia: az összes beállításkulcs, fájlformátum és tárolt szinkronizálási állapot.
- Dokumentációs webhely létrehozása: fájlokban induló, majd fordított irányban WordPress szinkronizáló tartalom.
- Fájlalapú oldalak létrehozása: olyan oldalak, amelyek szerkezetét a sablonban lévő sablonok kezelik.