Transférer le contenu de la base de données vers des fichiers avec Content Sync
Les blocs, les modèles et les pages fondées sur des fichiers se trouvent déjà dans votre dépôt. Certains contenus ne suivent pas ce modèle, car les éditeurs les créent dans l’interface d’administration : membres de l’équipe, bureaux, études de cas. Ils restent essentiels au projet. Un site de préproduction doit avoir la même page d’équipe que le site de production, les nouveaux développeurs ont besoin de données réalistes et les réviseurs doivent pouvoir voir les changements apportés à un intitulé de poste. Les sauvegardes de base de données ne règlent rien de tout cela efficacement. Elles contiennent tout, les identifiants diffèrent selon l’environnement et personne ne révise un diff SQL.
Content Sync comble cette lacune. Une commande WP-CLI projette une liste d’autorisation de publications, de termes, de relations et de métadonnées dans des fichiers JSON et HTML dans votre thème. Une autre commande applique ces fichiers à une autre base de données. Chaque entité reçoit un UID portable, et les références entre entités sont réécrites uniquement là où vous le déclarez.
Ce guide suit un annuaire d’équipe : l’exporter dans des fichiers, les examiner, modifier un fichier, le déplacer vers un nouvel environnement et le nettoyer en toute sécurité.
L’exemple
Le thème enregistre un type de publication acme_member et une taxonomie acme_team dans
chaque environnement. Chaque publication de membre peut contenir :
| Clé méta | Contient |
|---|---|
_acme_role |
Le titre du poste, une chaîne simple |
_acme_mentor |
L’identifiant de publication d’un autre membre |
_thumbnail_id |
L’identifiant de la pièce jointe du portrait |
_acme_api_token |
Un jeton d’intégration qui ne doit jamais parvenir à git |
Content Sync n’enregistre jamais les types de publication ni les taxonomies. Ils doivent exister partout où vous effectuez un push.
Étape 1 : configurer Content Sync
Content Sync est désactivé tant que vous ne l’activez pas dans blockstudio.json. D’ici là, chaque
commande renvoie une seule ligne skipped :
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.
Ajoutez un groupe content :
{
"$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"
}
}
Chaque clé définit une limite :
postTypesettaxonomiessont des listes d’autorisation. Rien en dehors de celles-ci n’est lu, écrit ou nettoyé. UnpostTypesvide signifie qu’aucune publication n’est touchée.meta.includedéfinit les clés méta autorisées, avec les jokers*.meta.excludea toujours la priorité, et_edit_lock,_edit_lastet_wp_old_slugsont exclus par défaut.meta.referencesdéclare quelles valeurs méta sont des ID. Content Sync ne suppose jamais qu’un entier est un ID.idnomme l’ensemble de contenu. Il est enregistré sur chaque entité synchronisée, et le nettoyage ne concerne que les entités du même ensemble.pathest le dossier de sortie, relatif au répertoire du thème actif.
Étape 2 : extraire
Prévisualisez d’abord la projection. Rien n’est écrit, et les UID affichés ne sont pas encore enregistrés :
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
Lancez ensuite l’extraction pour de vrai. Cela attribue un _blockstudio_content_uid permanent à chaque
entité qui n’en possède pas et écrit les fichiers :
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
Voici le résultat dans le thème :
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
Les noms de fichiers combinent le slug et le début de l’UID. La publication JSON contient les champs, les relations de termes et les métadonnées autorisées :
{
"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"
}
}
La relation de terme et l’image miniature sont des UID, et non des ID locaux. Le corps de la publication
se trouve à côté dans jane.5d4bf9b5.html sous forme de balisage brut de bloc. Une publication dont le contenu est vide,
comme celle de Sam, ne reçoit aucun fichier .html. Le champ _acme_mentor de Sam contient l’UID de Jane,
car cette clé est déclarée comme une référence post.
Étape 3 : vérifier avant de valider
Exécutez status avant de valider. Cette commande compare les fichiers et la base de données, et signale aussi
les données à risque :
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.
Le joker _acme_* a détecté le jeton. Considérez meta.include comme une limite de validation
et excluez explicitement la clé :
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
Le prochain pull réécrit sam.208db72e.json sans le jeton et laisse les autres fichiers intacts. status avertit également de la présence d’ID numériques dans les corps de balisage de bloc, car Content Sync ne réécrit pas les ID dans les fichiers .html.
Validez le dossier content/.
Étape 4 : modifier un fichier et envoyer les changements
Les fichiers font autorité pour push. Dans le fichier JSON, remplacez le rôle de Jane par Head of Design au lieu de Design Lead, puis vérifiez le résultat :
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 affiche le même plan dans l’ordre du push. Appliquez-le :
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 valide le plan complet avant toute écriture. Les références déclarées non résolues, les conflits de slug, les types de publication manquants et les fichiers mal formés interrompent l’opération.
WordPress attribue une nouvelle date de modification à une publication mise à jour, alors que le fichier contient toujours
l’ancienne valeur modified. Un lancement de status juste après ce push signale donc
la publication de Jane comme conflict avec le message « La base de données a changé depuis la dernière synchronisation. » Exécutez pull
une fois après le push pour enregistrer la nouvelle date ; status signale alors unchanged.
Étape 5 : transférer le contenu vers un autre environnement
Dans un environnement vierge, les fichiers décrivent des publications qui n’existent pas encore. Dans cet exemple, le terme et la pièce jointe du portrait y existent déjà avec les mêmes UID ; seuls les deux membres manquent :
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
Les publications ont reçu de nouveaux ID locaux, 536 et 537. Les références ont suivi : le champ
_acme_mentor de Sam contient maintenant 536, Jane figure à nouveau dans le terme leadership, et son
_thumbnail_id pointe vers la pièce jointe locale ayant l’UID correspondant. Les parents de publication, les parents de terme et les relations de termes sont toujours enregistrés sous forme d’UID ; les valeurs méta ne sont réécrites que pour les clés de meta.references.
Nettoyer en toute sécurité
Supprimer un fichier ne supprime rien lors du push, sauf si vous le demandez. Supprimez
sam.208db72e.json et essayez de nettoyer :
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
L’exécution à blanc montre ce qui serait supprimé :
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
push --prune --yes place ensuite la publication de Sam dans la corbeille et signale
pruned-trash. Plusieurs garde-fous limitent la portée de l’opération :
- Seules les entités appartenant à cet ensemble de contenu (
content.id) peuvent être traitées. - Seuls les types de publication et les taxonomies configurés sont pris en compte.
- Le plan source complet est analysé et validé avant toute écriture ou suppression.
Si le dossier contient un fichier JSON mal formé, le push signale une ligne
errortelle quecould not be read: Syntax erroret ne supprime rien.
L’action par défaut est trash. Le filtre blockstudio/content/orphan_action
peut renvoyer trash, delete ou keep pour chaque entité. Ainsi, les termes sont conservés tandis que les publications gardent l’action par défaut :
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
Avec ce réglage, un terme orphelin est signalé comme would-prune-keep au lieu de
would-prune-trash.
Médias
Les fichiers média ne sont jamais copiés. content.media détermine ce qui se passe avec les références de pièces jointes déclarées :
"manifest"(par défaut) enregistre les UID des pièces jointes et les répertorie danscontent/media/manifest.jsonavec leur chemin, leur type MIME et leur texte alternatif. Le push exige que chaque UID de pièce jointe référencée existe dans la cible ; transférez donc d’abord les fichiers téléversés selon votre processus habituel de gestion des médias."none"exclut des fichiers les références de pièces jointes déclarées. Le champ JSON de Jane ne contient alors que_acme_role. Comme une clé omise n’est pas appliquée lors du push, la publication déjà présente dans la cible conserve son image miniature actuelle.
Verrouiller une entité
Il arrive qu’un environnement cible doive conserver sa propre version d’une publication. Définissez une valeur vraie
pour la métadonnée _blockstudio_content_locked de cette publication ; le push l’ignore alors, renvoie une ligne locked et le message « Entité verrouillée ignorée. » Supprimez la métadonnée pour l’inclure à nouveau.
Règles de propriété
- Les articles gérés par des pages basées sur des fichiers sont exclus par défaut. Avec
includePageSyncManaged: true, Content Sync peut synchroniser leurs métadonnées configurées, mais Page Sync reste responsable de leurpost_content. Ces projections JSON contiennentbodyOwner: "page-sync", et pull indique explicitement que le corps a été ignoré. Les copies de révision.htmlexistantes sont conservées et ignorées par push. Synchronisez les pages sur un environnement cible avant d’y pousser leurs projections de métadonnées. - Les auteurs sont ignorés par défaut, car les utilisateurs ne sont pas synchronisés. Avec
authors: "login", les fichiers d’articles enregistrent l’identifiant de connexion de l’auteur et push le résout en utilisateur existant ; l’absence de cet utilisateur provoque une erreur lors du contrôle préalable. pullne supprime jamais de fichiers. Lorsqu’une entité de la base de données disparaît, pull signale son fichier comme obsolète et vous laisse le nettoyer.
Quand ne pas l’utiliser
Content Sync convient aux contenus sélectionnés et peu changeants : des dizaines ou des centaines d’entrées, jusqu’à quelques milliers si les données sont structurées et réparties entre des types de publication spécialisés. Il ne remplace pas les sauvegardes ni les migrations de bases de données. Les commandes, les soumissions de formulaires, les journaux, les analyses et les contenus éditoriaux à fort volume relèvent de ces outils. Les définitions de taxonomies, les fichiers binaires des médias et les ID dans le balisage de bloc ne sont pas pris en charge.
Étapes suivantes
- Référence de Content Sync : toutes les clés de configuration, les formats de fichiers et l’état de synchronisation enregistré.
- Créer un site de documentation : contenu créé dans des fichiers et synchronisé vers WordPress dans l’autre sens.
- Créer des pages basées sur des fichiers : pages dont la structure est définie par les modèles du thème.