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:
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.
Pridajte skupinu content:
{
"$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:
postTypesataxonomiessú zoznamy povolených položiek. Nič mimo nich sa nečíta, nezapisuje ani nečistí. PrázdnepostTypesznamená, že sa nespracujú žiadne príspevky.meta.includeurčuje povolené meta kľúče, pričom*povoľuje zástupné znaky.meta.excludemá vždy prednosť a_edit_lock,_edit_lasta_wp_old_slugsú predvolene vylúčené.meta.referencesurčuje, ktoré meta hodnoty sú ID. Content Sync nepredpokladá, že celé číslo je ID.idoznač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.pathoznač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ú:
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
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:
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
Výsledok v téme:
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:
{
"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:
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.
Zástupný znak _acme_* zachytil token. Považujte meta.include za hranicu pre potvrdenie zmien
a tento kľúč výslovne vylúčte:
"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:
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
push --dry-run vypíše rovnaký plán v poradí pre odoslanie zmien. Použite ho:
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
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:
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
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:
wp bs content push --prune
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:
wp bs content push --prune --dry-run
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íkladcould 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:
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 vcontent/media/manifest.jsonspolu 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: truemôže Content Sync synchronizovať ich nakonfigurované metaúdaje, ale Page Sync naďalej spravuje ichpost_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.htmlsa 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. pullnikdy 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
- Referenčná príručka Content Sync: všetky konfiguračné kľúče, formáty súborov a uložený stav synchronizácie.
- Tvorba dokumentačnej stránky: obsah, ktorý sa začína v súboroch a synchronizuje do WordPress, teda opačným smerom.
- Tvorba stránok založených na súboroch: stránky, ktorých štruktúru určujú šablóny v téme.