Přesun obsahu databáze do souborů pomocí synchronizace obsahu
Bloky, šablony a stránky založené na souborech už jsou součástí vašeho repozitáře. Některý obsah se do tohoto modelu nehodí, protože ho vytvářejí správci webu: členové týmu, kanceláře nebo případové studie. I tento obsah je pro projekt důležitý. Testovací web potřebuje stejnou stránku týmu jako produkční web, nový vývojář potřebuje realistická data a kontrolující by měl vidět, když někdo změní název pracovní pozice. Výpisy databáze nic z toho neřeší dobře. Obsahují vše, ID se v jednotlivých prostředích liší a nikdo nekontroluje rozdíly v SQL.
Content Sync tuto mezeru pokrývá. Příkaz WP-CLI promítne seznam povolených příspěvků, taxonomií, vztahů a metadat do souborů JSON a HTML ve vaší šabloně. Další příkaz tyto soubory použije v jiné databázi. Každá entita dostane přenositelné UID a odkazy mezi entitami se přepisují pouze tam, kde je výslovně určíte.
Tento průvodce vás provede správou týmového adresáře: jeho exportem do souborů, jejich kontrolou a úpravou, přesunem do nového prostředí a bezpečným čištěním.
Příklad
Šablona registruje v každém prostředí typ příspěvku acme_member a taxonomii acme_team.
Každý příspěvek člena může obsahovat:
| Klíč metadat | Obsahuje |
|---|---|
_acme_role |
Pracovní pozice, prostý řetězec |
_acme_mentor |
ID příspěvku jiného člena |
_thumbnail_id |
ID přílohy s portrétem |
_acme_api_token |
Integrační token, který se nikdy nesmí dostat do git |
Content Sync nikdy neregistruje typy příspěvků ani taxonomie. Musí existovat všude, kam data odesíláte.
Krok 1: Konfigurace Content Sync
Content Sync je vypnutý, dokud ho nepovolíte v blockstudio.json. Do té doby každý
příkaz vrací jediný řádek 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.
Přidejte 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ý klíč vymezuje hranici:
postTypesataxonomiesjsou seznamy povolených položek. Nic mimo ně se nečte, nezapisuje ani nemaže. PrázdnépostTypesznamená, že se žádných příspěvků nedotknete.meta.includeurčuje povolené klíče metadat a podporuje zástupné znaky*.meta.excludemá vždy přednost a_edit_lock,_edit_lasta_wp_old_slugjsou ve výchozím nastavení vyloučeny.meta.referencesurčuje, které hodnoty metadat jsou ID. Content Sync nikdy neodhaduje, že celé číslo je ID.idpojmenovává sadu obsahu. Ukládá se u každé synchronizované entity a při čištění se vždy zasahuje jen do entit ze stejné sady.pathje výstupní složka relativní k aktivnímu adresáři šablony.
Krok 2: Stažení
Nejprve si prohlédněte náhled. Nic se nezapisuje a zobrazená UID se zatím neukládají:
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
Pak proveďte skutečné stažení. Každé entitě, která ho ještě nemá, se přiřadí trvalé
_blockstudio_content_uid a zapíší se soubory:
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ýsledek v šabloně:
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
Názvy souborů se skládají z identifikátoru URL a první části UID. Příspěvek JSON obsahuje pole, vztahy k termům a povolená metadata:
{
"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"
}
}
Vztah k termu i náhledový obrázek jsou uloženy jako UID, nikoli lokální ID. Tělo příspěvku
je vedle něj v jane.5d4bf9b5.html jako surové blokové značení. Příspěvek s prázdným
obsahem, jako má Sam, nedostane soubor .html. Samovo _acme_mentor se ukládá jako
Janeino UID, protože je tento klíč určen jako odkaz post.
Krok 3: Kontrola před potvrzením změn
Před potvrzením změn spusťte status. Porovná soubory s databází a upozorní také
na riziková data:
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. meta.include považujte za hranici pro potvrzení změn
a tento klíč výslovně vylučte:
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
Následující pull přepíše sam.208db72e.json bez tokenu a ostatní soubory ponechá beze změny.
status také upozorňuje na číselná ID v tělech blokového značení, protože Content Sync ID
v souborech .html nepřepisuje.
Potvrďte změny ve složce content/.
Krok 4: Úprava souboru a odeslání
U push jsou zdrojem pravdy soubory. V souboru JSON změňte Janeinu roli z Design Lead
na Head of Design a pak zkontrolujte, co se 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 stejný plán v pořadí pro odeslání. Použijte 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
Před zápisem odeslání ověří celý plán. Nevyřešené určené odkazy, konflikty identifikátorů URL, chybějící typy příspěvků a chybně formátované soubory proces zastaví.
WordPress přiřadí aktualizovanému příspěvku nový čas poslední změny, zatímco soubor stále obsahuje
starou hodnotu modified. Bezprostředně následující spuštění status proto ohlásí Janein příspěvek
jako conflict se zprávou „Databáze se od poslední synchronizace změnila.“ Po odeslání spusťte pull
ještě jednou, aby se zaznamenal nový čas; status pak ohlásí unchanged.
Krok 5: Přesun obsahu do jiného prostředí
V novém prostředí soubory popisují příspěvky, které ještě neexistují. V tomto příkladu tam term i příloha s portrétem už existují pod stejnými UID, takže chybí pouze dva členové:
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
Příspěvky dostaly nová lokální ID, 536 a 537. Odkazy se aktualizovaly: Samovo
_acme_mentor nyní obsahuje 536, Jane je opět v termu leadership a její
_thumbnail_id odkazuje na lokální přílohu se shodným UID. Nadřazené příspěvky,
nadřazené termy i vztahy mezi termy se vždy ukládají jako UID; hodnoty metadat se přepisují
pouze u klíčů uvedených v meta.references.
Bezpečné mazání
Smazání souboru při odeslání nic nesmaže, pokud o to výslovně nepožádáte. Odeberte
sam.208db72e.json a zkuste provést čištění:
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
Nanečisto se zobrazí, co by se odstranilo:
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
push --prune --yes pak přesune Samův příspěvek do koše a ohlásí
pruned-trash. Rozsah operace omezují tyto pojistky:
- Kandidáty jsou pouze entity patřící do této sady obsahu (
content.id). - Zohledňují se pouze nakonfigurované typy příspěvků a taxonomie.
- Celý plán ze zdrojových souborů se před jakýmkoli zápisem nebo čištěním analyzuje a ověří.
Pokud složka obsahuje chybně formátovaný soubor JSON, odeslání ohlásí řádek
error, napříkladcould not be read: Syntax error, a nic nesmaže.
Výchozí akce je trash. Filtr blockstudio/content/orphan_action může pro každou entitu vrátit trash,
delete nebo keep. Díky tomu se termy zachovají, zatímco příspěvky zůstanou
na výchozí akci:
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
S tímto nastavením se osiřelý term ohlásí jako would-prune-keep místo would-prune-trash.
Média
Mediální soubory se nikdy nekopírují. content.media určuje, co se stane s deklarovanými
odkazy na přílohy:
"manifest"(výchozí) ukládá UID příloh a uvádí je vcontent/media/manifest.jsonspolečně s cestou, typem MIME a alternativním textem. Při odeslání musí v cílovém prostředí existovat každá odkazovaná příloha podle svého UID, proto nejprve přeneste nahrané soubory obvyklým postupem."none"vynechá deklarované odkazy na přílohy ze souborů. Janeino JSON pak obsahuje pouze_acme_role. Vynechaný klíč se při odeslání nepoužije, takže existující cílový příspěvek si ponechá aktuální náhledový obrázek.
Uzamčení entity
Někdy je potřeba zachovat v cílovém prostředí vlastní verzi příspěvku. Nastavte u něj
metadata _blockstudio_content_locked na pravdivou hodnotu a odesílání jej přeskočí s řádkem locked a zprávou
„Uzamčená entita přeskočena.“ Chcete-li jej znovu zahrnout, metadata smažte.
Pravidla vlastnictví
- Příspěvky spravované stránkami založenými na souborech jsou ve výchozím nastavení vyloučeny. Pomocí
includePageSyncManaged: truemůže Content Sync synchronizovat jejich nastavená metadata, ale za jejichpost_contentstále odpovídá Page Sync. Tyto projekce JSON obsahujíbodyOwner: "page-sync"a načtení výslovně hlásí přeskočený obsah. Stávající kontrolní kopie.htmlse zachovají a při odesílání se ignorují. Před odesláním projekcí metadat synchronizujte stránky v cílovém prostředí. - Autoři se ve výchozím nastavení ignorují, protože uživatelé se nesynchronizují. Pomocí
authors: "login"se v souborech příspěvků ukládá přihlašovací jméno autora a při odesílání se vyhledá odpovídající existující uživatel; chybějící uživatel způsobí chybu při předběžné kontrole. pullnikdy nemaže soubory. Když entita v databázi zmizí, načtení označí její soubor jako zastaralý a úklid ponechá na vás.
Kdy nástroj nepoužívat
Content Sync se hodí pro pečlivě spravovaný obsah, který se mění jen zřídka: desítky nebo stovky položek, případně nižší tisíce, pokud jsou data strukturovaná a rozdělená do účelově zaměřených typů příspěvků. Nenahrazuje zálohy ani migrace databáze. Objednávky, odeslané formuláře, protokoly, analytická data a velkoobjemový redakční obsah patří do jiných nástrojů. Definice taxonomií, binární mediální soubory a ID uvnitř blokového značení jsou mimo jeho rozsah.
Další kroky
- Reference Content Sync: všechny konfigurační klíče, formáty souborů a uložený stav synchronizace.
- Vytvoření dokumentačního webu: obsah, který začíná v souborech a synchronizuje se do WordPress opačným směrem.
- Vytvoření stránek založených na souborech: stránky, jejichž strukturu určují šablony v motivu.