Ga naar de inhoud

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:

Shell
wp bs content status
Code
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:

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

Elke sleutel stelt een grens:

  • postTypes en taxonomies zijn allowlists. Alles wat daarbuiten valt, wordt niet gelezen, geschreven of opgeschoond. Een lege postTypes betekent dat er geen berichten worden aangepast.
  • meta.include bepaalt welke metasleutels op de allowlist staan, met jokertekens *. meta.exclude heeft altijd voorrang, en _edit_lock, _edit_last en _wp_old_slug zijn standaard uitgesloten.
  • meta.references geeft aan welke metawaarden ID’s zijn. Content Sync gaat er nooit zomaar van uit dat een geheel getal een ID is.
  • id geeft de inhoudsset een naam. Deze wordt opgeslagen bij elke gesynchroniseerde entiteit, en bij het opschonen worden alleen entiteiten uit dezelfde set aangepast.
  • path is 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:

Shell
wp bs content pull --dry-run
Code
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:

Shell
wp bs content pull
Code
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:

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

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

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:

Shell
wp bs content status
Code
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:

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

Shell
wp bs content status
Code
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:

Shell
wp bs content push
Code
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:

Shell
wp bs content status
Code
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
Code
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:

Shell
wp bs content push --prune
Code
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:

Shell
wp bs content push --prune --dry-run
Code
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 zoals could not be read: Syntax error en 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:

PHP
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 in content/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: true kan Content Sync hun geconfigureerde meta synchroniseren, maar blijft Page Sync eigenaar van hun post_content. Die JSON-projecties bevatten bodyOwner: "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.
  • pull verwijdert 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