Preskočiť na obsah

Presun obsahu databázy do súborov pomocou synchronizácie obsahu

Bloky, šablóny a stránky vytvorené zo súborov už máte v úložisku projektu. Časť obsahu do tohto modelu nezapadá, pretože ju vytvárajú redaktori v administrácii: členovia tímu, adresy kancelárií a prípadové štúdie. Tento obsah je stále dôležitý pre projekt. Testovacie prostredie potrebuje rovnakú stránku tímu ako produkčné prostredie, nový vývojár potrebuje realistické údaje a kontrolór by mal vidieť, keď niekto zmení názov pracovnej pozície. Výpisy databázy tento problém dobre neriešia. Zahŕňajú všetko, ID sa v jednotlivých prostrediach líšia a nikto nekontroluje rozdiely SQL.

Content Sync vypĺňa túto medzeru. Príkaz WP-CLI premietne zoznam povolených príspevkov, termínov, vzťahov a metadát do súborov JSON a HTML vo vašej téme. Ďalší príkaz použije tieto súbory v inej databáze. Každá entita dostane prenosné UID a odkazy medzi entitami sa prepíšu iba tam, kde to určíte.

Táto príručka vás prevedie adresárom tímu: jeho exportom do súborov, kontrolou, úpravou súboru, presunom do nového prostredia a bezpečným čistením.

Príklad

Téma registruje typ príspevku acme_member a taxonómiu acme_team v každom prostredí. Každý členský príspevok môže obsahovať:

Meta kľúč Obsah
_acme_role Pracovnú pozíciu, obyčajný reťazec
_acme_mentor ID príspevku iného člena
_thumbnail_id ID prílohy s portrétom
_acme_api_token Integračný token, ktorý sa nikdy nesmie dostať do git

Content Sync nikdy neregistruje typy príspevkov ani taxonómie. Musia existovať všade, kam vykonávate push.

Krok 1: Konfigurácia Content Sync

Content Sync je vypnutý, kým ho nepovolíte v blockstudio.json. Dovtedy každý príkaz vráti jeden riadok skipped:

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.

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

Každý kľúč vymedzuje hranicu:

  • postTypes a taxonomies sú zoznamy povolených položiek. Nič mimo nich sa nečíta, nezapisuje ani nečistí. Prázdne postTypes znamená, že sa nespracujú žiadne príspevky.
  • meta.include určuje povolené meta kľúče, pričom * povoľuje zástupné znaky. meta.exclude má vždy prednosť a _edit_lock, _edit_last a _wp_old_slug sú predvolene vylúčené.
  • meta.references určuje, ktoré meta hodnoty sú ID. Content Sync nepredpokladá, že celé číslo je ID.
  • id označuje množinu obsahu. Ukladá sa pri každej synchronizovanej entite a čistenie sa vždy týka iba entít z rovnakej množiny.
  • path označuje výstupný priečinok vzhľadom na aktívny adresár témy.

Krok 2: Export

Najprv zobrazte ukážku projekcie. Nič sa nezapisuje a zobrazené UID sa zatiaľ neukladajú:

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

Potom vykonajte skutočný export. Každej entite, ktorá ešte nemá UID, sa priradí trvalé _blockstudio_content_uid a zapíšu sa súbory:

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

Výsledok v téme:

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

Názvy súborov tvoria slug a prvá časť UID. Príspevok JSON obsahuje polia, vzťahy k termínom a povolené meta údaje:

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

Vzťah k termínu a miniatúra sú UID, nie lokálne ID. Telo príspevku je vedľa neho v jane.5d4bf9b5.html ako surové značky blokov. Príspevok s prázdnym obsahom, ako Samov, nemá súbor .html. Samovo _acme_mentor sa ukladá ako UID Jane, pretože kľúč je deklarovaný ako referencia post.

Krok 3: Kontrola pred potvrdením zmien

Pred potvrdením zmien spustite status. Porovná súbory s databázou a označí aj rizikové údaje:

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.

Zástupný znak _acme_* zachytil token. Považujte meta.include za hranicu pre potvrdenie zmien a tento kľúč výslovne vylúčte:

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

Nasledujúci príkaz pull prepíše sam.208db72e.json bez tokenu a ostatné súbory ponechá nedotknuté. status upozorní aj na číselné ID v telách značiek blokov, pretože Content Sync neprepisuje ID v súboroch .html.

Potvrďte zmeny v priečinku content/.

Krok 4: Úprava súboru a odoslanie zmien

Súbory sú pre push zdrojom pravdy. Zmeňte Janinu pozíciu v súbore JSON z Design Lead na Head of Design a potom skontrolujte, čo sa stane:

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

push --dry-run vypíše rovnaký plán v poradí pre odoslanie zmien. Použite ho:

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

Push pred zápisom overí celý plán. Nevyriešené deklarované referencie, konflikty slugov, chýbajúce typy príspevkov a chybne formátované súbory ho zastavia.

WordPress nastaví aktualizovanému príspevku nový čas úpravy, zatiaľ čo súbor stále obsahuje starú hodnotu modified. Preto status vykonaný hneď po tomto pushi nahlási Janin príspevok ako conflict s hlásením „Databáza sa od poslednej synchronizácie zmenila.“ Spustite pull raz po odoslaní zmien, aby sa zachytil nový čas; potom status nahlási unchanged.

Krok 5: Presun obsahu do iného prostredia

V novom prostredí súbory opisujú príspevky, ktoré ešte neexistujú. V tomto príklade tam už termín aj príloha s portrétom existujú pod rovnakými UID, takže chýbajú iba dvaja členovia:

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

Príspevky dostali nové lokálne ID: 536 a 537. Odkazy sa preniesli: Samovo _acme_mentor teraz obsahuje 536, Jane je opäť v termíne leadership a jej _thumbnail_id odkazuje na lokálnu prílohu so zodpovedajúcim UID. Rodičovské príspevky, rodičovské termíny a vzťahy k termínom sa vždy ukladajú ako UID; meta hodnoty sa prepisujú iba pre kľúče uvedené v meta.references.

Bezpečné čistenie

Odstránenie súboru pri pushi nič nevymaže, pokiaľ o to nepožiadate. Odstráňte sam.208db72e.json a skúste vyčistenie:

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.

Skúšobný beh ukazuje, čo by sa odstránilo:

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

push --prune --yes potom presunie Samov príspevok do koša a nahlási pruned-trash. Niekoľko ochranných prvkov udržiava rozsah zmien obmedzený:

  • Kandidátmi sú iba entity patriace do tejto množiny obsahu (content.id).
  • Zohľadňujú sa iba nakonfigurované typy príspevkov a taxonómie.
  • Celý zdrojový plán sa spracuje a overí pred akýmkoľvek zápisom alebo čistením. Ak sa v priečinku nachádza chybne formátovaný súbor JSON, push nahlási riadok error, napríklad could not be read: Syntax error, a nič nevyčistí.

Predvolená akcia je trash. Filter blockstudio/content/orphan_action môže pre každú entitu vrátiť trash, delete alebo keep. Vďaka tomu sa zachovajú termíny, pričom príspevky zostanú pri predvolenej akcii:

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

Vďaka tomu sa osirelý termín nahlási ako would-prune-keep namiesto would-prune-trash.

Médiá

Súbory médií sa nikdy nekopírujú. content.media určuje, čo sa stane s deklarovanými odkazmi na prílohy:

  • "manifest" (predvolené) ukladá UID príloh a uvádza ich v content/media/manifest.json spolu s cestou, typom MIME a alternatívnym textom. Push vyžaduje, aby každá odkazovaná príloha s daným UID existovala v cieľovom prostredí, preto ju najprv presuňte pomocou svojho bežného pracovného postupu pre médiá.
  • "none" vynecháva deklarované odkazy na prílohy zo súborov. Janino JSON potom obsahuje iba _acme_role. Keďže vynechaný kľúč sa pri pushi nepoužije, existujúci príspevok v cieľovom prostredí si zachová aktuálnu miniatúru.

Uzamknutie entity

Niekedy musí cieľové prostredie zachovať vlastnú verziu príspevku. Nastavte meta _blockstudio_content_locked daného príspevku na pravdivú hodnotu a push ho preskočí s riadkom locked a hlásením „Preskočená uzamknutá entita.“ Odstránením meta ju znova zahrniete.

Pravidlá vlastníctva

  • Príspevky spravované stránkami založenými na súboroch sú predvolene vylúčené. S includePageSyncManaged: true môže Content Sync synchronizovať ich nakonfigurované metaúdaje, ale Page Sync naďalej spravuje ich post_content. Tieto projekcie JSON obsahujú bodyOwner: "page-sync" a príkaz pull výslovne oznámi, že telo bolo preskočené. Existujúce kontrolné kópie .html sa zachovajú a príkaz push ich ignoruje. Pred odoslaním projekcií ich metadát synchronizujte stránky v cieľovom prostredí.
  • Autori sa predvolene ignorujú, pretože používatelia sa nesynchronizujú. S authors: "login" súbory príspevkov ukladajú prihlasovacie meno autora a príkaz push ho priradí k existujúcemu používateľovi; ak používateľ chýba, kontrola pred spustením skončí chybou.
  • pull nikdy neodstraňuje súbory. Keď entita v databáze zanikne, príkaz pull označí jej súbor za neaktuálny a ponechá jeho vyčistenie na vás.

Kedy ho nepoužívať

Content Sync sa hodí na vybraný obsah, ktorý sa mení zriedka: desiatky či stovky záznamov, prípadne niekoľko tisíc, ak sú údaje štruktúrované a rozdelené do zameraných typov príspevkov. Nenahrádza zálohy databázy ani migrácie. Objednávky, odoslané formuláre, protokoly, analytické údaje a veľké objemy redakčného obsahu patria do iných nástrojov. Definície taxonómií, binárne súbory médií a ID v značkách blokov nespadajú do jeho rozsahu.

Ďalšie kroky