Synchronisation du contenu
Blockstudio repose sur un flux de travail axé sur les fichiers : blocs, champs, modèles, ressources, compositions et pages basées sur des fichiers peuvent tous résider dans votre projet. La synchronisation du contenu étend ce modèle à certains contenus de base de données WordPress, pour les équipes qui souhaitent également gérer dans git des articles, des termes, des relations et des métadonnées déclarées sélectionnés.
Il s’agit d’un flux de travail WP-CLI, et non d’une réplication en direct de la base de données. Lors de l’extraction, la synchronisation du contenu projette les articles, postmeta, termes, termmeta et relations entre articles et termes autorisés dans des fichiers portables de votre thème. Lors de l’envoi, elle applique ces fichiers à un autre environnement, en utilisant des identifiants uniques stables et en réécrivant uniquement les références que vous déclarez explicitement.
Remarque
La synchronisation du contenu est à la demande. Elle ne s’exécute pas à chaque requête d’administration. Les commandes renvoient une ligne ignorée tant que
content.enabledn’est pastrue.
Quand utiliser la synchronisation du contenu
Utilisez la synchronisation du contenu pour les ensembles de contenu qu’il est important de versionner, de réviser et de déplacer entre les environnements :
- contenu structuré tel que les membres d’équipe, les lieux, les études de cas, les produits, les entrées de documentation ou les pages de campagne
- taxonomies et relations associées à ces ensembles de contenu
- métadonnées autorisées qu’il est sûr de valider et qui nécessitent des références stables
- ensembles de contenu petits ou moyens, pour lesquels la révision des fichiers dans git reste pratique
En règle générale, la synchronisation du contenu convient à des dizaines ou des centaines de lignes, et peut aller jusqu’à quelques milliers lorsque les données sont structurées, changent peu et sont réparties en types d’articles ciblés. Elle n’est pas destinée à répliquer une base de données de production entière, du contenu éditorial à fort trafic, des journaux, des commandes, des analyses, des envois de formulaires, des sessions ni d’autres données volumineuses ou très changeantes. Si les fichiers générés deviennent difficiles à réviser, si les envois sont trop longs à évaluer ou si la plupart des lignes changent en dehors de votre processus de déploiement, utilisez plutôt une sauvegarde, une migration ou un outil d’importation et d’exportation de base de données.
Les fichiers binaires des médias ne sont pas copiés. Les références aux pièces jointes peuvent être consignées dans un manifeste et validées, mais les fichiers eux-mêmes doivent exister dans l’environnement cible.
Configuration
Activez la synchronisation du contenu dans blockstudio.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 est une liste d’autorisation. Si elle est vide, la synchronisation du contenu ne touche pas aux articles. taxonomies est une liste d’autorisation des taxonomies déjà enregistrées dont les termes et les relations avec les articles doivent être synchronisés. Blockstudio n’enregistre pas les définitions de taxonomie à partir des fichiers de synchronisation du contenu. Les métadonnées des articles et des termes sont autorisées via meta.include ; meta.exclude prévaut toujours.
Avertissement
Considérez
meta.includecomme une limite de validation. Les fichiers synchronisés sont destinés à être stockés dans git ; n’y incluez donc aucune clé contenant des secrets, jetons, identifiants ou données personnelles.wp bs content statussignale les lignes d’avertissement lorsqu’une clé de métadonnées autorisée semble sensible.
content.id est stocké sur les entités synchronisées sous la forme _blockstudio_content_set. Les vérifications de nettoyage et de propriété se limitent à cette valeur, afin qu’un ensemble de contenu ne puisse pas supprimer le contenu d’un autre.
Les articles gérés par la synchronisation des pages sont exclus par défaut. Si includePageSyncManaged est activé, la synchronisation du contenu peut synchroniser leurs métadonnées configurées, mais la synchronisation des pages reste responsable de leur post_content.
Ces projections contiennent "bodyOwner": "page-sync". Pull signale l’écriture JSON comme contenant uniquement des métadonnées et ajoute une ligne de corps skipped, plutôt que de présenter l’article comme ayant un corps vide. Il ne crée ni ne supprime de fichier frère .html. Une copie de révision existante est conservée et ignorée par push. Les mêmes messages de propriété figurent dans la sortie de simulation.
Dans un autre environnement, exécutez d’abord Page Sync. Une projection avec bodyOwner: "page-sync" doit faire référence à un article existant géré par Page Sync ; push refuse de créer un substitut vide ou d’appliquer la copie de révision de ce corps. Les projections sans le marqueur des anciennes versions restent prises en charge.
Les auteurs sont ignorés par défaut, car les utilisateurs ne sont pas synchronisés. Définissez authors: "login" pour stocker l’identifiant de connexion de l’auteur dans les fichiers d’articles et retrouver un utilisateur existant à partir de cet identifiant lors de l’envoi. L’absence d’un utilisateur provoque une erreur lors de la vérification préalable ; la synchronisation du contenu ne crée pas d’utilisateurs.
Commandes
wp bs content pull [--post-type=<type>] [--taxonomy=<taxonomy>] [--dry-run]
wp bs content push [--dry-run] [--prune] [--yes]
wp bs content status
pull capture le contenu de la base de données dans des fichiers. Il attribue _blockstudio_content_uid aux articles concernés qui n’en ont pas encore et signale les fichiers obsolètes dont la source dans la base de données n’existe plus. Les fichiers obsolètes ne sont pas supprimés lors de l’extraction.
push applique les fichiers à la base de données actuelle. La commande valide le plan avant toute écriture et bloque les références déclarées non résolues, les conflits de slug, les entités verrouillées et les types d’articles manquants.
status compare les fichiers à la base de données et signale chaque entité comme unchanged, would-update, missing-db, conflict, locked ou orphaned. La commande avertit également des clés de métadonnées autorisées qui semblent contenir des secrets avant leur validation, ainsi que des identifiants numériques dans le corps du balisage des blocs, car la synchronisation du contenu ne réécrit pas les identifiants dans les fichiers .html.
Utilisez --dry-run pour examiner une extraction ou un envoi sans écrire. Utilisez push --prune --yes pour supprimer les entités de base de données appartenant à un ensemble de contenu qui n’existent plus dans les fichiers.
Sécurité en cas d’échec
push analyse et valide l’intégralité du plan source avant toute écriture ou suppression. Un JSON mal formé, des références déclarées non résolues, une propriété invalide ou tout autre échec du contrôle préalable bloque la phase destructive. L’élagage reste limité aux types de contenus, taxonomies et content.id configurés.
pull écrit chaque fichier projeté avant d’enregistrer l’entité comme synchronisée. Un échec d’écriture dans le système de fichiers est renvoyé sous forme de ligne d’erreur et ne met pas à jour l’état de synchronisation enregistré pour cette entité.
La gestion des pièces jointes suit content.media. Avec "manifest", les UID des pièces jointes référencées doivent exister dans l’environnement cible. Avec "none", les références déclarées aux pièces jointes sont intentionnellement supprimées de la sortie portable au lieu de conserver des ID propres à l’environnement.
Fichiers
Content Sync écrit les fichiers dans le content.path configuré :
content/
posts/
team_member/
jane.9b1c0e6e.json
jane.9b1c0e6e.html
terms/
category/
leadership.5e900000.json
media/
manifest.json
Les fichiers .json des articles contiennent leur identité, leurs champs, leurs relations avec les termes, les métadonnées déclarées et l’encodage des métadonnées. Le fichier .html associé contient post_content sous forme de balisage brut des blocs ; il est omis si le contenu est vide. Les fichiers .json des termes contiennent leur identité, leur taxonomie, leur slug, leur nom, leur description, l’UID du parent, les métadonnées de terme déclarées et l’encodage des métadonnées.
L’autre cas, sans fichier .html, est un corps géré par Page Sync, identifié ci-dessus par bodyOwner. Pour les articles ordinaires dont le corps devient vide, pull supprime l’ancien fichier du corps et le signale dans une ligne distincte de deleted.
{
"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"
}
}
L’état de synchronisation enregistré est :
| Clé de métadonnées | Fonction |
|---|---|
_blockstudio_content_uid |
Identité de contenu portable |
_blockstudio_content_set |
Espace de noms de l’ensemble de contenus provenant de content.id |
_blockstudio_content_source |
Chemin du fichier source relatif au thème |
_blockstudio_content_fingerprint |
Dernière empreinte synchronisée du fichier/de la base de données |
_blockstudio_content_locked |
Une valeur vraie empêche push d’écraser l’entité |
Références
Content Sync ne devine jamais qu’un entier est un ID. Les références ne sont réécrites que si elles sont configurées dans meta.references.
{
"meta": {
"references": {
"_related_posts": { "kind": "post", "path": "*" },
"_topic": { "kind": "term" },
"_hero": { "kind": "attachment", "path": "image.id" }
}
}
}
Lors d’un pull, les ID locaux aux chemins concernés deviennent des UID portables. Lors d’un push, les UID sont résolus en ID locaux dans la base de données actuelle.
Les parents des articles, les parents des termes et les relations entre articles et termes sont des références structurelles gérées par Content Sync et sont automatiquement stockées sous forme d’UID. Les taxonomies configurées sont inscrites dans les fichiers d’articles même lorsqu’elles sont vides ; un tableau vide efface les relations de cette taxonomie lors d’un push.
Les références aux pièces jointes sont validées, mais elles ne sont pas importées. Avec media: "manifest", les pièces jointes référencées sont répertoriées dans content/media/manifest.json ; le push exige que l’UID de la pièce jointe référencée existe localement. Avec media: "none", les références déclarées aux pièces jointes sont omises des fichiers portables. Comme une clé omise n’est pas appliquée lors du push, un article cible existant conserve ses métadonnées de pièces jointes actuelles.
Flux de travail de portabilité
- Enregistrez le type de contenu cible dans chaque environnement.
- Configurez
content.postTypes,meta.includeet toutes les références déclarées. - Exécutez
wp bs content pulldans l’environnement source. - Validez les fichiers générés.
- Exécutez
wp bs content pushdans l’environnement cible. - Exécutez
wp bs content statuspour vérifier que la base de données correspond aux fichiers.
Les fichiers font autorité pour push. La base de données est recopiée dans les fichiers avec pull.
Périmètre
Content Sync prend en charge :
- les articles issus de types de contenus autorisés
- les métadonnées d’article autorisées
- les termes issus de taxonomies enregistrées autorisées
- les métadonnées de terme autorisées
- les relations entre articles et termes
- les références
post,attachmentettermdéclarées - les UID portables des articles et des termes, ainsi que la propriété des ensembles de contenus
- l’exclusion de Page Sync par défaut
- le manifeste des pièces jointes et la validation préalable
pull,push,status,--dry-run,--pruneet la gestion des entités verrouillées
La capture des définitions de taxonomie, la copie des fichiers binaires multimédias et la réécriture des ID dans le balisage des blocs ne sont pas prises en charge.