Database-inhoud naar bestanden verplaatsen met Content Sync
Blocks, templates en pagina’s op basis van bestanden staan al in je repository. Sommige inhoud past niet in dat model, omdat redacteuren die in het beheergedeelte aanmaken: teamleden, kantoorlocaties en casestudy’s. Die inhoud blijft belangrijk voor het project. Een stagingwebsite heeft dezelfde teampagina nodig als productie, een nieuwe ontwikkelaar heeft realistische gegevens nodig en een reviewer moet kunnen zien wanneer iemand een functietitel wijzigt. Database-dumps lossen dit probleem niet goed op. Ze bevatten alles, ID’s verschillen per omgeving en niemand controleert een SQL-diff.
Content Sync vult die leemte op. Met een WP-CLI-opdracht projecteer je een allowlist van berichten, termen, relaties en metadata naar JSON- en HTML-bestanden in je thema. Met een andere opdracht pas je die bestanden toe op een andere database. Elke entiteit krijgt een draagbare UID en verwijzingen tussen entiteiten worden alleen herschreven waar je dat aangeeft.
Deze gids laat zien hoe je een teamgids naar bestanden haalt, deze controleert, een bestand bewerkt, naar een nieuwe omgeving verplaatst en veilig opschoont.
Het voorbeeld
Het thema registreert in elke omgeving een acme_member-berichttype en een acme_team-taxonomie. Elk lidbericht kan het volgende bevatten:
| Metasleutel | Bevat |
|---|---|
_acme_role |
De functietitel, een gewone tekenreeks |
_acme_mentor |
De bericht-ID van een ander lid |
_thumbnail_id |
De bijlage-ID van de portretfoto |
_acme_api_token |
Een integratietoken dat nooit in git terecht mag komen |
Content Sync registreert nooit berichttypen of taxonomieën. Deze moeten bestaan in elke omgeving waarnaar je pusht.
Stap 1: Content Sync configureren
Content Sync is uitgeschakeld totdat je deze inschakelt in blockstudio.json. Tot die tijd retourneert elke
opdracht één enkele skipped-rij:
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.
Voeg een content-groep toe:
{
"$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"
}
}
Elke sleutel stelt een grens:
postTypesentaxonomieszijn allowlists. Alles wat daarbuiten valt, wordt niet gelezen, geschreven of opgeschoond. Een legepostTypesbetekent dat er geen berichten worden aangepast.meta.includebepaalt welke metasleutels op de allowlist staan, met jokertekens*.meta.excludeheeft altijd voorrang, en_edit_lock,_edit_lasten_wp_old_slugzijn standaard uitgesloten.meta.referencesgeeft aan welke metawaarden ID’s zijn. Content Sync gaat er nooit zomaar van uit dat een geheel getal een ID is.idgeeft de inhoudsset een naam. Deze wordt opgeslagen bij elke gesynchroniseerde entiteit, en bij het opschonen worden alleen entiteiten uit dezelfde set aangepast.pathis de uitvoermap, relatief aan de actieve themamap.
Stap 2: Ophalen
Bekijk eerst een voorbeeld van de projectie. Er wordt niets weggeschreven en de getoonde UID’s zijn nog niet opgeslagen:
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
Voer de opdracht daarna echt uit om op te halen. Hiermee krijgt elke entiteit die nog geen UID heeft
een permanente _blockstudio_content_uid toegewezen en worden de bestanden weggeschreven:
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
Het resultaat in het thema:
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
Bestandsnamen combineren de slug met het eerste deel van de UID. Het bericht JSON bevat de velden, de termrelaties en de toegestane 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"
}
}
De termrelatie en de miniatuurafbeelding zijn UID’s, geen lokale ID’s. De berichtinhoud
staat ernaast in jane.5d4bf9b5.html als ruwe blokmarkup. Een bericht zonder inhoud, zoals dat van Sam, krijgt geen .html-bestand. Sams _acme_mentor wordt opgeslagen als de UID van Jane, omdat de sleutel is ingesteld als een post-verwijzing.
Stap 3: Controleren voordat je commit
Voer status uit voordat je commit. Dit vergelijkt de bestanden met de database en markeert ook
risicovolle gegevens:
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.
Het jokerteken _acme_* heeft het token gevonden. Beschouw meta.include als een grens voor commits en sluit de sleutel expliciet uit:
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
De volgende pull herschrijft sam.208db72e.json zonder het token en laat de
andere bestanden ongemoeid. status waarschuwt ook voor numerieke ID’s in de
blokmarkup van inhoud, omdat Content Sync ID’s in .html-bestanden niet herschrijft.
Commit de map content/.
Stap 4: Een bestand bewerken en pushen
Bestanden zijn de bron van waarheid voor push. Wijzig Janes functie in het JSON-bestand
van Design Lead naar Head of Design en bekijk vervolgens wat er zou gebeuren:
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 toont hetzelfde plan in de volgorde van pushen. Pas het toe:
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 valideert het volledige plan voordat er iets wordt weggeschreven. Onopgeloste gedeclareerde verwijzingen, slugconflicten, ontbrekende berichttypen en ongeldige bestanden zorgen ervoor dat de opdracht stopt.
WordPress geeft een bijgewerkt bericht een nieuwe wijzigingstijd, terwijl het bestand nog de oude modified-waarde heeft. Een status-uitvoering direct na deze push meldt Janes bericht daarom als conflict met “Database changed since last sync.” Voer pull één keer uit na het pushen om de nieuwe tijd vast te leggen; status rapporteert daarna unchanged.
Stap 5: De inhoud naar een andere omgeving verplaatsen
In een nieuwe omgeving beschrijven de bestanden berichten die nog niet bestaan. In dit voorbeeld bestaan de term en de portretbijlage daar al met dezelfde UID’s, dus ontbreken alleen de twee leden:
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
De berichten kregen nieuwe lokale ID’s, 536 en 537. De verwijzingen zijn mee overgezet: Sams
_acme_mentor bevat nu 536, Jane staat opnieuw in de leadership-term en haar
_thumbnail_id verwijst naar de lokale bijlage met de overeenkomende UID. Bovenliggende berichten, bovenliggende termen en termrelaties worden altijd als UID’s opgeslagen; metawaarden worden alleen herschreven voor sleutels in meta.references.
Veilig opschonen
Een bestand verwijderen verwijdert bij het pushen niets, tenzij je daarom vraagt. Verwijder
sam.208db72e.json en probeer de inhoud op te schonen:
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
De dry-run toont wat er zou worden verwijderd:
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
push --prune --yes verplaatst Sams bericht vervolgens naar de prullenbak en meldt
pruned-trash. Verschillende beveiligingen houden de actie beperkt:
- Alleen entiteiten die bij deze inhoudsset horen (
content.id) komen in aanmerking. - Alleen geconfigureerde berichttypen en taxonomieën worden meegenomen.
- Het volledige bronplan wordt verwerkt en gevalideerd voordat er iets wordt weggeschreven of
opgeschoond. Staat er een ongeldig JSON-bestand in de map, dan meldt push een
error-rij zoalscould not be read: Syntax erroren wordt er niets opgeschoond.
De standaardactie is trash. Het filter blockstudio/content/orphan_action
kan voor elke entiteit trash, delete of keep retourneren. Zo blijven termen behouden, terwijl berichten de standaardactie gebruiken:
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
Hierdoor wordt een verweesde term gemeld als would-prune-keep in plaats van
would-prune-trash.
Media
Mediabestanden worden nooit gekopieerd. Met content.media bepaal je wat er gebeurt met gedeclareerde
verwijzingen naar bijlagen:
"manifest"(standaard) slaat bijlage-UID’s op en vermeldt ze incontent/media/manifest.json, samen met het pad, het MIME-type en de alternatieve tekst. Push vereist dat elke verwezen bijlage-UID in het doel bestaat. Zet de uploads dus eerst over met je gebruikelijke mediaworkflow."none"laat gedeclareerde verwijzingen naar bijlagen weg uit de bestanden. Janes JSON bevat dan alleen_acme_role. Omdat een weggelaten sleutel niet wordt toegepast tijdens het pushen, behoudt een bestaand doelbericht de huidige miniatuurafbeelding.
Een entiteit vergrendelen
Soms moet een doelomgeving de eigen versie van een bericht behouden. Stel de _blockstudio_content_locked-metadata op dat bericht in op een truthy waarde. Push slaat het dan over met een locked-rij en het bericht “Locked entity skipped.” Verwijder de metadata om het bericht weer mee te nemen.
Eigendomsregels
- Berichten die door pagina’s op basis van bestanden worden beheerd, zijn standaard uitgesloten. Met
includePageSyncManaged: truekan Content Sync hun geconfigureerde meta synchroniseren, maar blijft Page Sync eigenaar van hunpost_content. Die JSON-projecties bevattenbodyOwner: "page-sync"en pull meldt expliciet dat de body is overgeslagen. Bestaande.html-reviewkopieën blijven behouden en worden door push genegeerd. Synchroniseer de pagina’s in een doelomgeving voordat je hun metadataprojecties pusht. - Auteurs worden standaard genegeerd, omdat gebruikers niet worden gesynchroniseerd. Met
authors: "login"slaan berichtbestanden de login van de auteur op en zoekt push een bestaande gebruiker op; een ontbrekende gebruiker veroorzaakt een preflight-fout. pullverwijdert nooit bestanden. Als een database-entiteit is verwijderd, meldt pull dat het bestand verouderd is en laat het opruimen aan jou over.
Wanneer je dit niet moet gebruiken
Content Sync is geschikt voor samengestelde inhoud die weinig verandert: tientallen of honderden items, tot enkele duizenden wanneer de gegevens gestructureerd zijn en over gerichte berichttypen zijn verdeeld. Het is geen vervanging voor databaseback-ups of migraties. Bestellingen, formulierinzendingen, logboeken, analyses en redactionele inhoud met een hoog volume horen thuis in die hulpmiddelen. Taxonomiedefinities, binaire mediabestanden en ID’s in blokmarkup vallen buiten het toepassingsgebied.
Volgende stappen
- Content Sync-naslag: alle configuratiesleutels, bestandsindelingen en opgeslagen synchronisatiestatus.
- Een documentatiesite bouwen: inhoud die in bestanden begint en naar WordPress de andere kant op wordt gesynchroniseerd.
- Pagina’s op basis van bestanden bouwen: pagina’s waarvan de structuur wordt beheerd door templates in het thema.