Zum Inhalt springen

Content-Synchronisierung

Blockstudio basiert auf einem dateibasierten Workflow: Blöcke, Felder, Templates, Assets, Patterns und dateibasierte Seiten können alle in deinem Projekt liegen. Content Sync erweitert dieses Modell auf ausgewählte WordPress-Datenbankinhalte für Teams, die kuratierte Beiträge, Begriffe, Beziehungen und deklarierte Metadaten ebenfalls in git verwalten möchten.

Es handelt sich um einen WP-CLI-Workflow, keine laufende Datenbankreplikation. Beim Abruf überführt Content Sync freigegebene Beiträge, postmeta, Begriffe, termmeta und Beitrags-Begriffs-Beziehungen in portable Dateien in deinem Theme. Beim Übertragen wendet es diese Dateien auf eine andere Umgebung an. Dabei verwendet es stabile UIDs und schreibt nur Referenzen um, die du ausdrücklich deklarierst.

Hinweis

Content Sync wird bei Bedarf ausgeführt. Es läuft nicht bei jeder Admin-Anfrage. Bis content.enabled den Status true hat, melden Befehle, dass eine Zeile übersprungen wurde.

Wann du Content Sync verwenden solltest

Verwende Content Sync für Inhaltsbestände, die versioniert, geprüft und zwischen Umgebungen übertragen werden sollen:

  • strukturierte Inhalte wie Teammitglieder, Standorte, Fallstudien, Produkte, Dokumentationseinträge oder Kampagnenseiten
  • Taxonomien und Beziehungen, die zu diesen Inhaltsbeständen gehören
  • freigegebene Metadaten, die sicher eingecheckt werden können und stabile Referenzen benötigen
  • kleine bis mittelgroße Inhaltsbestände, deren Dateien sich noch gut in git prüfen lassen

Als Faustregel eignet sich Content Sync gut für Dutzende oder Hunderte von Datensätzen und kann bei strukturierter, selten geänderter und auf bestimmte Beitragstypen verteilter Daten auch einige Tausend verarbeiten. Es ist nicht dafür gedacht, eine gesamte Produktionsdatenbank, redaktionelle Inhalte mit hohem Aufkommen, Protokolle, Bestellungen, Analysen, Formulareinsendungen, Sitzungen oder andere umfangreiche oder häufig geänderte Daten zu spiegeln. Werden die generierten Dateien unübersichtlich, dauern Pushes zu lange, um sie nachvollziehen zu können, oder ändern sich die meisten Datensätze außerhalb deines Deployment-Workflows, verwende stattdessen ein Datenbank-Backup, Migrationstool oder Import-/Export-Tool.

Mediendateien werden nicht kopiert. Referenzen auf Anhänge können in einem Manifest erfasst und validiert werden, aber die Dateien selbst müssen in der Zielumgebung vorhanden sein.

Konfiguration

Aktiviere Content Sync in blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "content": {
    "enabled": true,
    "id": "default",
    "path": "content",
    "includePageSyncManaged": false,
    "authors": "ignore",
    "postTypes": ["team_member"],
    "meta": {
      "include": ["_my_*"],
      "exclude": ["_edit_lock", "_edit_last", "_wp_old_slug"],
      "references": {
        "_thumbnail_id": { "kind": "attachment" },
        "_related_posts": { "kind": "post", "path": "*" },
        "_hero": { "kind": "attachment", "path": "image.id" }
      }
    },
    "taxonomies": [],
    "media": "manifest"
  }
}

postTypes ist eine Freigabeliste. Ist sie leer, greift Content Sync nicht auf Beiträge zu. taxonomies ist eine Freigabeliste registrierter Taxonomien, deren Begriffe und Beitragsbeziehungen synchronisiert werden sollen. Blockstudio registriert keine Taxonomiedefinitionen aus Content-Sync-Dateien. postmeta und termmeta werden über meta.include freigegeben; meta.exclude hat immer Vorrang.

Warnung

Betrachte meta.include als Grenze dafür, was eingecheckt wird. Synchronisierte Dateien gehören in git. Nimm daher keine Schlüssel auf, die Geheimnisse, Tokens, Zugangsdaten oder personenbezogene Daten enthalten. wp bs content status meldet Warnungen, wenn ein freigegebener Metaschlüssel sensibel zu sein scheint.

content.id wird für synchronisierte Entitäten als _blockstudio_content_set gespeichert. Bereinigungen und Besitzprüfungen beziehen sich auf diesen Wert, damit ein Inhaltsbestand nicht die Inhalte eines anderen löschen kann.

Von Page Sync verwaltete Beiträge sind standardmäßig ausgeschlossen. Wenn includePageSyncManaged aktiviert ist, kann Content Sync ihre konfigurierten Metadaten synchronisieren; post_content bleibt jedoch im Besitz von Page Sync.

Diese Projektionen enthalten "bodyOwner": "page-sync". Pull kennzeichnet den Schreibvorgang von JSON als reine Metadatenänderung und fügt eine skipped-Body-Zeile hinzu, statt den Beitrag so darzustellen, als hätte er einen leeren Body. Eine zugehörige .html-Datei wird weder geschrieben noch gelöscht. Eine vorhandene Review-Kopie bleibt erhalten und wird von Push ignoriert. Dieselben Hinweise zur Zuständigkeit sind in der Dry-Run-Ausgabe enthalten.

Führe Page Sync zuerst in einer anderen Umgebung aus. Eine Projektion mit bodyOwner: "page-sync" muss auf einen vorhandenen, von Page Sync verwalteten Beitrag verweisen; beim Push wird kein leerer Ersatzbeitrag erstellt und keine Prüffassung dieses Inhalts angewendet. Projektionen aus älteren Versionen ohne den Marker werden weiterhin unterstützt.

Autoren werden standardmäßig ignoriert, weil Benutzer nicht synchronisiert werden. Setze authors: "login", um den Login des Autors in Beitragsdateien zu speichern und ihn beim Push einem vorhandenen Benutzer zuzuordnen. Fehlt der Benutzer, schlägt die Vorabprüfung fehl; Content Sync erstellt keine Benutzer.

Befehle

Shell
wp bs content pull [--post-type=<type>] [--taxonomy=<taxonomy>] [--dry-run]
wp bs content push [--dry-run] [--prune] [--yes]
wp bs content status

pull überführt Datenbankinhalte in Dateien. Weist in den Geltungsbereich fallenden Beiträgen, die noch keine haben, eine _blockstudio_content_uid zu und meldet veraltete Dateien, deren Datenbankquelle nicht mehr existiert. Veraltete Dateien werden beim Abruf nicht gelöscht.

push wendet Dateien auf die aktuelle Datenbank an. Vor dem Schreiben wird der Plan validiert; nicht auflösbare deklarierte Referenzen, Slug-Konflikte, gesperrte Entitäten und fehlende Beitragstypen verhindern den Vorgang.

status vergleicht Dateien mit der Datenbank und meldet für jede Entität den Status unchanged, would-update, missing-db, conflict, locked oder orphaned. Außerdem warnt der Befehl vor dem Einchecken vor freigegebenen Metaschlüsseln, die wie Geheimnisse aussehen, sowie vor numerischen IDs in Block-Markup-Inhalten, da Content Sync IDs in .html-Dateien nicht umschreibt.

Verwende --dry-run, um einen Abruf oder Push ohne Schreibvorgänge zu prüfen. Mit push --prune --yes entfernst du Datenbankentitäten eines Inhaltsbestands, die in den Dateien nicht mehr vorhanden sind.

Sicherheit bei Fehlern

push parst und validiert den vollständigen Quellplan, bevor es schreibt oder Daten bereinigt. Ungültige JSON, nicht auflösbare deklarierte Referenzen, ungültige Besitzangaben und andere Fehler bei der Vorabprüfung verhindern destruktive Vorgänge. Bereinigungen bleiben auf die konfigurierten Beitragstypen, Taxonomien und content.id beschränkt.

pull schreibt jede überführte Datei, bevor es die Entität als synchronisiert vermerkt. Schlägt das Schreiben im Dateisystem fehl, wird dies als Fehlerzeile zurückgegeben und der gespeicherte Synchronisierungsstatus der Entität bleibt unverändert.

Die Behandlung von Anhängen richtet sich nach content.media. Mit "manifest" müssen referenzierte Anhang-UIDs in der Zielumgebung vorhanden sein. Mit "none" werden deklarierte Anhangsreferenzen absichtlich aus der portablen Ausgabe entfernt, statt umgebungsspezifische IDs beizubehalten.

Dateien

Content Sync schreibt Dateien in das konfigurierte content.path:

Code
content/
  posts/
    team_member/
      jane.9b1c0e6e.json
      jane.9b1c0e6e.html
  terms/
    category/
      leadership.5e900000.json
  media/
    manifest.json

Beitragsdateien .json enthalten Identität, Beitragsfelder, Begriffsbeziehungen, deklarierte Metadaten und deren Kodierung. Die benachbarte Datei .html enthält post_content als rohes Block-Markup und wird bei leerem Inhalt weggelassen. Begriffsdateien .json enthalten Identität, Taxonomie, Slug, Namen, Beschreibung, übergeordnete UID, deklarierte Begriffsmetadaten und deren Kodierung.

Der andere Fall ohne .html-Datei ist ein von Page Sync verwalteter Inhalt, erkennbar an bodyOwner oben. Bei gewöhnlichen Beiträgen, deren Inhalt leer wird, entfernt pull die alte Inhaltsdatei und führt sie in einer separaten Inhaltszeile deleted auf.

JSON
{
  "uid": "9b1c0e6e-0000-4000-9000-000000000000",
  "type": "team_member",
  "status": "publish",
  "slug": "jane",
  "title": "Jane",
  "parent": null,
  "menuOrder": 0,
  "terms": {
    "category": ["5e900000-0000-4000-9000-000000000000"]
  },
  "meta": {
    "_my_subtitle": "Creative Director",
    "_thumbnail_id": "a1b2c3d4-0000-4000-9000-000000000000"
  },
  "metaEncoding": {
    "_my_subtitle": "scalar",
    "_thumbnail_id": "scalar"
  }
}

Der gespeicherte Synchronisierungsstatus lautet:

Metaschlüssel Zweck
_blockstudio_content_uid Portable Inhaltsidentität
_blockstudio_content_set Namensraum des Inhaltsbestands aus content.id
_blockstudio_content_source Theme-relativer Quellpfad
_blockstudio_content_fingerprint Letzter Fingerabdruck von Datei/Datenbank-Abgleich
_blockstudio_content_locked Ein wahrer Wert verhindert, dass ein Push die Entität überschreibt

Referenzen

Content Sync nimmt niemals an, dass eine Ganzzahl eine ID ist. Referenzen werden nur umgeschrieben, wenn sie in meta.references konfiguriert sind.

JSON
{
  "meta": {
    "references": {
      "_related_posts": { "kind": "post", "path": "*" },
      "_topic": { "kind": "term" },
      "_hero": { "kind": "attachment", "path": "image.id" }
    }
  }
}

Beim Abruf werden lokale IDs an diesen Pfaden in portable UIDs umgewandelt. Beim Push werden die UIDs in der aktuellen Datenbank wieder lokalen IDs zugeordnet.

Übergeordnete Beiträge, übergeordnete Begriffe und Beitrags-Begriffs-Beziehungen sind strukturelle Referenzen, die Content Sync verwaltet und automatisch als UIDs speichert. Konfigurierte Taxonomien werden auch dann in Beitragsdateien geschrieben, wenn sie leer sind; ein leeres Array entfernt beim Push die Beziehungen dieser Taxonomie.

Anhangsreferenzen werden validiert, aber nicht importiert. Mit media: "manifest" werden referenzierte Anhänge in content/media/manifest.json aufgeführt; beim Push muss die UID des referenzierten Anhangs lokal vorhanden sein. Mit media: "none" werden deklarierte Anhangsreferenzen aus portablen Dateien ausgelassen. Da ein ausgelassener Schlüssel beim Push nicht angewendet wird, behält ein vorhandener Zielbeitrag seine aktuellen Anhangsmetadaten.

Portabilitäts-Workflow

  1. Registriere den Zielbeitragstyp in jeder Umgebung.
  2. Konfiguriere content.postTypes, meta.include und alle deklarierten Referenzen.
  3. Führe wp bs content pull in der Quellumgebung aus.
  4. Checke die generierten Dateien ein.
  5. Führe wp bs content push in der Zielumgebung aus.
  6. Führe wp bs content status aus, um zu prüfen, ob die Datenbank mit den Dateien übereinstimmt.

Für push sind die Dateien die maßgebliche Quelle. Mit pull werden Datenbankinhalte wieder in Dateien überführt.

Geltungsbereich

Content Sync unterstützt:

  • Beiträge aus freigegebenen Beitragstypen
  • freigegebenes postmeta
  • Begriffe aus freigegebenen registrierten Taxonomien
  • freigegebenes termmeta
  • Beitrags-Begriffs-Beziehungen
  • deklarierte Referenzen vom Typ post, attachment und term
  • portable Beitrags- und Begriffs-UIDs sowie die Zuordnung zu Inhaltsbeständen
  • standardmäßigen Ausschluss durch Page Sync
  • Anhangsmanifest und Vorabprüfung
  • Behandlung von pull, push, status, --dry-run, --prune und gesperrten Entitäten

Das Erfassen von Taxonomiedefinitionen, das Kopieren von Mediendateien und das Umschreiben von IDs im Block-Markup werden nicht unterstützt.