Přejít k obsahu

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:

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.

Přidejte 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ý klíč vymezuje hranici:

  • postTypes a taxonomies jsou seznamy povolených položek. Nic mimo ně se nečte, nezapisuje ani nemaže. Prázdné postTypes znamená, že se žádných příspěvků nedotknete.
  • meta.include určuje povolené klíče metadat a podporuje zástupné znaky *. meta.exclude má vždy přednost a _edit_lock, _edit_last a _wp_old_slug jsou ve výchozím nastavení vyloučeny.
  • meta.references určuje, které hodnoty metadat jsou ID. Content Sync nikdy neodhaduje, že celé číslo je ID.
  • id pojmenová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.
  • path je 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í:

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

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:

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ýsledek v šabloně:

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

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

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:

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. meta.include považujte za hranici pro potvrzení změn a tento klíč výslovně vylučte:

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

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 stejný plán v pořadí pro odeslání. Použijte 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

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é:

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

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í:

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.

Nanečisto se zobrazí, co by se odstranilo:

Shell
wp bs content push --prune --dry-run
Kód
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říklad could 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:

PHP
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 v content/media/manifest.json společ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: true může Content Sync synchronizovat jejich nastavená metadata, ale za jejich post_content stá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 .html se 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.
  • pull nikdy 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