Ga naar de inhoud

Contentsynchronisatie

Blockstudio is opgezet rond een bestandsgerichte workflow: blokken, velden, templates, assets, patronen en op bestanden gebaseerde pagina’s kunnen allemaal in je project staan. Contentsynchronisatie breidt dit model uit naar geselecteerde database-inhoud van WordPress, voor teams die ook samengestelde berichten, termen, relaties en gedeclareerde metadata in git willen beheren.

Het is een workflow voor WP-CLI, geen live databasereplicatie. Bij het ophalen projecteert Content Sync toegestane berichten, postmeta, termen, termmeta en bericht-termrelaties naar draagbare bestanden in je theme. Bij het pushen past het die bestanden toe op een andere omgeving, met stabiele UID’s en waarbij alleen verwijzingen worden herschreven die je expliciet opgeeft.

Opmerking

Contentsynchronisatie wordt op aanvraag uitgevoerd. Het wordt niet bij elk beheerdersverzoek gestart. Opdrachten geven een overgeslagen rij terug totdat content.enabled true is.

Wanneer gebruik je Contentsynchronisatie?

Gebruik Contentsynchronisatie voor inhoudssets die je wilt versiebeheren, beoordelen en tussen omgevingen verplaatsen:

  • gestructureerde inhoud zoals teamleden, locaties, casestudy’s, producten, documentatie-items of campagnepagina’s
  • taxonomieën en relaties die bij die inhoudssets horen
  • toegestane metadata die veilig kan worden vastgelegd en stabiele verwijzingen nodig heeft
  • kleine tot middelgrote inhoudssets waarvan de bestanden nog praktisch te beoordelen zijn in git

Als vuistregel is Contentsynchronisatie geschikt voor tientallen of honderden rijen, en kan het duizenden rijen aan als de gegevens gestructureerd en weinig veranderlijk zijn en over gerichte berichttypen zijn verdeeld. Het is niet bedoeld om een volledige productiedatabase, redactionele inhoud met veel verkeer, logs, bestellingen, analyses, formulierinzendingen, sessies of andere gegevens met een groot volume of veel wijzigingen te spiegelen. Als de gegenereerde bestanden lastig te beoordelen zijn, pushes te lang duren om te beoordelen of de meeste rijen veranderen buiten je implementatieworkflow om, gebruik dan een databaseback-up, migratie- of import-/exporttool.

Mediabestanden worden niet gekopieerd. Bijlageverwijzingen kunnen worden vastgelegd in een manifest en gevalideerd, maar de bestanden zelf moeten in de doelomgeving bestaan.

Configuratie

Schakel Contentsynchronisatie in via 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 is een toestemmingslijst. Als deze leeg is, raakt Contentsynchronisatie geen berichten aan. taxonomies is een toestemmingslijst van al geregistreerde taxonomieën waarvan de termen en berichtrelaties moeten worden gesynchroniseerd. Blockstudio registreert geen taxonomiedefinities vanuit Contentsynchronisatiebestanden. Postmeta en termmeta worden toegestaan via meta.include; meta.exclude heeft altijd voorrang.

Waarschuwing

Behandel meta.include als een grens voor wat je vastlegt. Gesynchroniseerde bestanden zijn bedoeld voor git, dus neem geen sleutels op die geheimen, tokens, inloggegevens of persoonsgegevens bevatten. wp bs content status meldt waarschuwingsrijen wanneer een toegestane metasleutel gevoelig lijkt.

content.id wordt op gesynchroniseerde entiteiten opgeslagen als _blockstudio_content_set. Opschonen en eigendomscontroles zijn op die waarde afgestemd, zodat de inhoud van de ene set die van een andere set niet kan verwijderen.

Berichten die door Page Sync worden beheerd, zijn standaard uitgesloten. Als includePageSyncManaged is ingeschakeld, kan Contentsynchronisatie de ingestelde metadata ervan synchroniseren, maar Page Sync blijft eigenaar van post_content.

Deze projecties bevatten "bodyOwner": "page-sync". Pull rapporteert de schrijfbewerking JSON als alleen metadata en voegt een skipped-rij voor de inhoud toe, in plaats van het bericht weer te geven alsof het een lege inhoud heeft. Er wordt geen aangrenzend bestand .html geschreven of verwijderd. Een bestaande beoordelingskopie blijft behouden en wordt genegeerd door push. Dezelfde meldingen over eigenaarschap staan ook in de uitvoer van dry-run.

Voer op een andere omgeving eerst Page Sync uit. Een projectie met bodyOwner: "page-sync" moet verwijzen naar een bestaande, door Page Sync beheerde post; push weigert een lege plaatsvervanger aan te maken of de beoordelingskopie van die body toe te passen. Projecties zonder de marker uit oudere versies blijven ondersteund.

Auteurs worden standaard genegeerd, omdat gebruikers niet worden gesynchroniseerd. Stel authors: "login" in om de loginnaam van de auteur in berichtbestanden op te slaan en die loginnaam bij het pushen te koppelen aan een bestaande gebruiker. Ontbrekende gebruikers veroorzaken een fout bij de controle vooraf; Contentsynchronisatie maakt geen gebruikers aan.

Opdrachten

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 legt database-inhoud vast in bestanden. Het wijst _blockstudio_content_uid toe aan berichten binnen het bereik die er nog geen hebben en meldt verouderde bestanden waarvan de databasebron niet meer bestaat. Verouderde bestanden worden bij het ophalen niet verwijderd.

push past bestanden toe op de huidige database. Het valideert het plan voordat het schrijft en blokkeert onopgeloste gedeclareerde verwijzingen, slugconflicten, vergrendelde entiteiten en ontbrekende berichttypen.

status vergelijkt bestanden met de database en meldt voor elke entiteit een status: unchanged, would-update, missing-db, conflict, locked of orphaned. Het waarschuwt ook voor toegestane metasleutels die op geheimen lijken voordat die waarden worden vastgelegd, en voor numerieke ID’s in block-markup, omdat Contentsynchronisatie ID’s in bestanden van het type .html niet herschrijft.

Gebruik --dry-run om een ophaal- of pushbewerking te controleren zonder iets te schrijven. Gebruik push --prune --yes om database-entiteiten te verwijderen die eigendom zijn van inhoudssets en niet meer in de bestanden voorkomen.

Foutafhandeling

push parseert en valideert het volledige bronplan voordat het schrijft of opschoont. Foutieve JSON, onopgeloste gedeclareerde verwijzingen, ongeldig eigenaarschap en andere fouten bij de controle vooraf blokkeren de destructieve fase. Opschonen blijft beperkt tot de geconfigureerde berichttypen, taxonomieën en content.id.

pull schrijft elk geprojecteerd bestand voordat het die entiteit als gesynchroniseerd registreert. Een fout bij het schrijven naar het bestandssysteem wordt als foutmelding geretourneerd en werkt de opgeslagen synchronisatiestatus van die entiteit niet bij.

Bijlagen worden afgehandeld volgens content.media. Met "manifest" moeten de UID’s van verwezen bijlagen in de doelomgeving bestaan. Met "none" worden gedeclareerde bijlagereferenties bewust uit de draagbare uitvoer verwijderd in plaats van omgevingsspecifieke ID’s te behouden.

Bestanden

Content Sync schrijft bestanden onder de geconfigureerde content.path:

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

Berichtsbestanden .json bevatten identiteit, berichtvelden, termrelaties, gedeclareerde metadata en metadata-encoding. Het bijbehorende bestand .html bevat post_content als onbewerkte blokmarkup en wordt weggelaten wanneer de inhoud leeg is. Termbestanden .json bevatten identiteit, taxonomie, slug, naam, beschrijving, bovenliggende UID, gedeclareerde termmetadata en metadata-encoding.

Het andere geval zonder .html-bestand is een body die eigendom is van Page Sync, herkenbaar aan bodyOwner hierboven. Voor gewone posts waarvan de body leeg wordt, verwijdert pull het oude bodybestand en vermeldt het dit in een aparte bodyrij deleted.

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

De opgeslagen synchronisatiestatus is:

Metasleutel Doel
_blockstudio_content_uid Draagbare inhoudsidentiteit
_blockstudio_content_set Inhoudsset-namespace van content.id
_blockstudio_content_source Bronbestandspad relatief aan het thema
_blockstudio_content_fingerprint Laatste fingerprint van bestand/database bij synchronisatie
_blockstudio_content_locked Een truthy waarde voorkomt dat push de entiteit overschrijft

Verwijzingen

Content Sync raadt nooit dat een geheel getal een ID is. Verwijzingen worden alleen herschreven wanneer dit is geconfigureerd in meta.references.

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

Bij pull worden lokale ID’s op die paden draagbare UID’s. Bij push worden de UID’s teruggezet naar lokale ID’s in de huidige database.

Berichtouders, termouders en bericht-termrelaties zijn structurele verwijzingen die door Content Sync worden beheerd en automatisch als UID’s worden opgeslagen. Geconfigureerde taxonomieën worden in berichtbestanden geschreven, ook als ze leeg zijn; een lege array wist de relaties voor die taxonomie bij push.

Bijlagereferenties worden gevalideerd, niet geïmporteerd. Met media: "manifest" worden verwezen bijlagen vermeld in content/media/manifest.json; bij push moet de UID van de verwezen bijlage lokaal bestaan. Met media: "none" worden gedeclareerde bijlagereferenties weggelaten uit draagbare bestanden. Omdat een weggelaten sleutel niet wordt toegepast bij push, behoudt een bestaand doelbericht de huidige bijlagemetadata.

Workflow voor overdraagbaarheid

  1. Registreer het doelberichttype in elke omgeving.
  2. Configureer content.postTypes, meta.include en eventuele gedeclareerde verwijzingen.
  3. Voer wp bs content pull uit in de bronomgeving.
  4. Commit de gegenereerde bestanden.
  5. Voer wp bs content push uit in de doelomgeving.
  6. Voer wp bs content status uit om te controleren of de database overeenkomt met de bestanden.

Bestanden zijn de bron van waarheid voor push. De database wordt met pull teruggezet naar bestanden.

Bereik

Content Sync ondersteunt:

  • berichten van toegestane berichttypen
  • toegestane berichtmetadata
  • termen van toegestane geregistreerde taxonomieën
  • toegestane termmetadata
  • bericht-termrelaties
  • gedeclareerde verwijzingen naar post, attachment en term
  • draagbare bericht- en term-UID’s en eigenaarschap van inhoudssets
  • standaard uitsluiting door Page Sync
  • bijlagemanifest en preflightvalidatie
  • afhandeling van pull, push, status, --dry-run, --prune en vergrendelde entiteiten

Het vastleggen van taxonomiedefinities, het kopiëren van mediabestanden en het herschrijven van ID’s in blokmarkup worden niet ondersteund.