Перейти до вмісту

Перенесення вмісту бази даних у файли за допомогою Content Sync

Блоки, шаблони й сторінки на основі файлів уже містяться у вашому репозиторії. Частина вмісту не вписується в цю модель, адже редактори створюють її в адмінпанелі: члени команди, офісні адреси, приклади робіт. Цей вміст усе одно важливий для проєкту. На проміжному сайті потрібна та сама сторінка команди, що й на робочому; новому розробнику потрібні реалістичні дані, а рецензент має бачити зміни в назві посади. Дампи бази даних не вирішують цих завдань: вони містять усе, ідентифікатори різняться в різних середовищах, а ніхто не перевіряє зміни SQL.

Content Sync закриває цю прогалину. Команда WP-CLI проєктує список дозволених записів, термінів, зв’язків і метаданих у файли JSON та HTML у вашій темі. Інша команда застосовує ці файли до іншої бази даних. Кожна сутність отримує переносний UID, а посилання між сутностями переписуються лише там, де ви це вкажете.

У цьому посібнику розглянуто каталог команди: як перенести його у файли, перевірити їх, відредагувати файл, перемістити його в нове середовище та безпечно очистити.

Приклад

Тема реєструє тип запису acme_member і таксономію acme_team у кожному середовищі. Кожен запис учасника може містити:

Ключ метаданих Містить
_acme_role Посаду, звичайний рядок
_acme_mentor ID запису іншого учасника
_thumbnail_id ID вкладення з портретом
_acme_api_token Токен інтеграції, який ніколи не має потрапити до git

Content Sync не реєструє типи записів або таксономії. Вони мають існувати в кожному середовищі, до якого ви надсилаєте дані.

Крок 1: налаштуйте Content Sync

Content Sync вимкнено, доки ви не ввімкнете його в blockstudio.json. До цього кожна команда повертає один рядок 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.

Додайте групу 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"
  }
}

Кожен ключ визначає межу:

  • postTypes і taxonomies — списки дозволеного. За їхні межами нічого не читається, не записується й не очищується. Порожнє значення postTypes означає, що жодні записи не обробляються.
  • meta.include визначає дозволені ключі метаданих за допомогою шаблонів *. meta.exclude завжди має вищий пріоритет, а _edit_lock, _edit_last і _wp_old_slug виключено за замовчуванням.
  • meta.references визначає, які значення метаданих є ID. Content Sync не вгадує, що ціле число є ID.
  • id задає назву набору контенту. Вона зберігається для кожної синхронізованої сутності, а під час очищення обробляються лише сутності з того самого набору.
  • path — це вихідна папка відносно каталогу активної теми.

Крок 2: перенесіть дані

Спершу перегляньте проєкцію. Нічого не записується, а показані UID ще не зберігаються:

Командна оболонка
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

Потім виконайте перенесення. Для кожної сутності без UID буде призначено постійний _blockstudio_content_uid, а файли буде записано:

Командна оболонка
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

Результат у темі:

Код
content/
├── media/
│   └── manifest.json
├── posts/
│   └── acme_member/
│       ├── jane.5d4bf9b5.html
│       ├── jane.5d4bf9b5.json
│       └── sam.208db72e.json
└── terms/
    └── acme_team/
        └── leadership.7491a6a1.json

Назви файлів утворюються зі slug і першої частини UID. Запис JSON містить поля, зв’язки з термінами та дозволені метадані:

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

Зв’язок із терміном і мініатюра зберігаються як UID, а не як локальні ID. Тіло запису зберігається поруч у jane.5d4bf9b5.html як необроблена розмітка блоків. Для запису з порожнім вмістом, як у Сема, файл .html не створюється. Значення _acme_mentor Сема зберігається як UID Джейн, оскільки цей ключ оголошено як посилання post.

Крок 3: перевірте перед комітом

Перед комітом виконайте status. Команда порівнює файли й базу даних, а також позначає ризиковані дані:

Командна оболонка
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.

Шаблон _acme_* виявив токен. Вважайте meta.include межею коміту й явно виключіть цей ключ:

JSON
"meta": {
  "include": ["_acme_*", "_thumbnail_id"],
  "exclude": ["_acme_api_token"],
  "references": {
    "_acme_mentor": { "kind": "post" },
    "_thumbnail_id": { "kind": "attachment" }
  }
}

Наступний pull переписує sam.208db72e.json без токена й не змінює інші файли. status також попереджає про числові ID у тілах розмітки блоків, оскільки Content Sync не переписує ID у файлах .html.

Закомітьте папку content/.

Крок 4: відредагуйте файл і надішліть зміни

Файли — джерело істини для push. Змініть посаду Джейн у файлі JSON з Design Lead на Head of Design, а потім перевірте, що станеться:

Командна оболонка
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 виводить той самий план у порядку надсилання. Застосуйте його:

Командна оболонка
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 перевіряє весь план. Невирішені оголошені посилання, конфлікти slug, відсутні типи записів і некоректні файли зупиняють виконання.

WordPress присвоює оновленому запису новий час зміни, тоді як у файлі досі зберігається старе значення modified. Тому запуск status одразу після цього надсилання повідомить, що запис Джейн має стан conflict із повідомленням «Базу даних змінено після останньої синхронізації». Один раз виконайте pull після надсилання, щоб зафіксувати новий час; тоді status повідомить про unchanged.

Крок 5: перенесіть контент в інше середовище

У новому середовищі файли описують записи, яких там ще немає. У цьому прикладі термін і вкладення з портретом уже є там із такими самими UID, тож бракує лише двох учасників:

Командна оболонка
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

Записи отримали нові локальні ID: 536 і 537. Посилання оновилися: у _acme_mentor Сема тепер міститься 536, Джейн знову належить до терміна leadership, а її _thumbnail_id вказує на локальне вкладення з відповідним UID. Батьківські записи, батьківські терміни та зв’язки між термінами завжди зберігаються як UID; значення метаданих переписуються лише для ключів у meta.references.

Безпечне очищення

Видалення файлу саме по собі не видаляє нічого під час надсилання, якщо ви цього не попросите. Видаліть sam.208db72e.json і спробуйте очистити дані:

Командна оболонка
wp bs content push --prune
Код
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.

Пробний запуск показує, що буде видалено:

Командна оболонка
wp bs content push --prune --dry-run
Код
action             entity  id   uid          message
...
would-prune-trash  post    537  208db72e-...

Потім push --prune --yes переміщує запис Сема до кошика й повідомляє про pruned-trash. Кілька запобіжників звужують межі операції:

  • Кандидатами можуть бути лише сутності, що належать цьому набору контенту (content.id).
  • Розглядаються лише налаштовані типи записів і таксономії.
  • Увесь вихідний план розбирається й перевіряється до будь-якого запису чи очищення. Якщо в папці є некоректний файл JSON, push повідомляє про рядок error, як-от could not be read: Syntax error, і нічого не очищує.

За замовчуванням виконується дія trash. Фільтр blockstudio/content/orphan_action може повертати trash, delete або keep для кожної сутності. Так можна зберегти терміни, залишивши для записів дію за замовчуванням:

PHP
add_filter(
	'blockstudio/content/orphan_action',
	function ( string $action, string $type ) {
		return 'term' === $type ? 'keep' : $action;
	},
	10,
	2
);

Завдяки цьому для осиротілого терміна повідомляється would-prune-keep замість would-prune-trash.

Медіафайли

Медіафайли ніколи не копіюються. content.media визначає, що робити з оголошеними посиланнями на вкладення:

  • "manifest" (за замовчуванням) зберігає UID вкладень і перелічує їх у content/media/manifest.json разом зі шляхом, типом MIME і альтернативним текстом. Push вимагає, щоб UID кожного вкладення, на яке є посилання, існував у цільовому середовищі, тож спершу перенесіть завантаження звичним для вас способом роботи з медіафайлами.
  • "none" не додає до файлів оголошені посилання на вкладення. У JSON Джейн тоді міститься лише _acme_role. Оскільки пропущений ключ не застосовується під час надсилання, наявна мініатюра запису в цільовому середовищі зберігається.

Блокування сутності

Іноді в цільовому середовищі потрібно зберегти власну версію певного запису. Установіть для метаданих _blockstudio_content_locked цього запису істинне значення, і push пропустить його, додавши рядок locked із повідомленням «Сутність заблоковано й пропущено». Видаліть метадані, щоб знову включити запис.

Правила керування

  • За замовчуванням публікації, якими керують сторінки на основі файлів, виключено. З includePageSyncManaged: true Content Sync може синхронізувати їхні налаштовані метадані, але Page Sync і далі керує їхнім post_content. Ці проєкції JSON містять bodyOwner: "page-sync", а під час отримання даних явно повідомляється про пропущений вміст. Наявні копії для перевірки .html зберігаються, а надсилання їх ігнорує. Синхронізуйте сторінки в цільовому середовищі, перш ніж надсилати проєкції їхніх метаданих.
  • Автори за замовчуванням ігноруються, оскільки користувачі не синхронізуються. З authors: "login" файли публікацій зберігають логін автора, а під час надсилання даних система знаходить відповідного наявного користувача; якщо його немає, попередня перевірка завершується помилкою.
  • pull ніколи не видаляє файли. Якщо об’єкт більше не існує в базі даних, під час отримання даних його файл позначається як застарілий, а очищення залишається за вами.

Коли не варто використовувати

Content Sync підходить для відібраного контенту, що рідко змінюється: десятків або сотень записів, а також кількох тисяч, якщо дані структуровано й розподілено між спеціалізованими типами записів. Він не замінює резервне копіювання баз даних або міграції. Замовлення, надсилання форм, журнали, аналітика й редакційний контент у великих обсягах належать до інших інструментів. Визначення таксономій, бінарні файли медіа та ID у розмітці блоків не входять до його сфери застосування.

Наступні кроки