Ugrás a tartalomhoz

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:

Shell
wp bs content status
Kód
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:

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

Minden kulcs határt szab:

  • A postTypes és a taxonomies engedélyezési listák. Rajtuk kívül semmi sem kerül beolvasásra, módosításra vagy ritkításra. Az üres postTypes esetén egyetlen bejegyzés sem érintett.
  • A meta.include a meta kulcsok engedélyezési listája, a * helyettesítő karakterekkel. A meta.exclude mindig elsőbbséget élvez, a _edit_lock, _edit_last és _wp_old_slug pedig alapértelmezés szerint ki vannak zárva.
  • A meta.references deklará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 id nevezi 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 path a 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:

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

Shell
wp bs content pull
Kód
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:

Kód
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:

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

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:

Shell
wp bs content status
Kód
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:

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

Shell
wp bs content status
Kód
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:

Shell
wp bs content push
Kód
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:

Shell
wp bs content status
Kód
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
Kód
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:

Shell
wp bs content push --prune
Kód
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:

Shell
wp bs content push --prune --dry-run
Kód
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 error sort jelez, mint a could 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:

PHP
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 a content/media/manifest.json fá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: true használatával a Content Sync szinkronizálhatja a beállított metaadatokat, de a Page Sync továbbra is a post_content kezeléséért felel. Ezek a JSON kivetítések bodyOwner: "page-sync" elemet tartalmaznak, a pull pedig külön jelzi a kihagyott törzset. A meglévő .html felü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 pull soha 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