Aller au contenu

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 :

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.

Ajoutez un groupe content :

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

Chaque clé définit une limite :

  • postTypes et taxonomies sont des listes d’autorisation. Rien en dehors de celles-ci n’est lu, écrit ou nettoyé. Un postTypes vide signifie qu’aucune publication n’est touchée.
  • meta.include définit les clés méta autorisées, avec les jokers *. meta.exclude a toujours la priorité, et _edit_lock, _edit_last et _wp_old_slug sont exclus par défaut.
  • meta.references déclare quelles valeurs méta sont des ID. Content Sync ne suppose jamais qu’un entier est un ID.
  • id nomme 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.
  • path est 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 :

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

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 :

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

Voici le résultat dans le thème :

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

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

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 :

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.

Le joker _acme_* a détecté le jeton. Considérez meta.include comme une limite de validation et excluez explicitement la clé :

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

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 affiche le même plan dans l’ordre du push. Appliquez-le :

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

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

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 :

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.

L’exécution à blanc montre ce qui serait supprimé :

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

PHP
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 dans content/media/manifest.json avec 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 leur post_content. Ces projections JSON contiennent bodyOwner: "page-sync", et pull indique explicitement que le corps a été ignoré. Les copies de révision .html existantes 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.
  • pull ne 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