Lewati ke konten

Memindahkan Konten Database ke File dengan Sinkronisasi Konten

Blok, template, dan halaman berbasis file sudah tersimpan di repositori Anda. Sebagian konten tidak sesuai dengan model tersebut karena dibuat oleh editor di panel admin: anggota tim, lokasi kantor, studi kasus. Konten itu tetap penting bagi proyek. Situs staging memerlukan halaman tim yang sama dengan produksi, pengembang baru memerlukan data yang realistis, dan peninjau perlu melihat perubahan jabatan. Dump database tidak menyelesaikan masalah ini dengan baik. Dump membawa semuanya, ID berbeda di setiap lingkungan, dan tak seorang pun meninjau diff SQL.

Content Sync mengatasi kesenjangan itu. Sebuah perintah WP-CLI memproyeksikan daftar izin pos, term, relasi, dan metadata ke dalam berkas JSON dan HTML di tema Anda. Perintah lain menerapkan berkas tersebut ke basis data lain. Setiap entitas mendapat UID portabel, dan referensi antarentitas hanya ditulis ulang jika Anda menetapkannya.

Panduan ini membahas direktori tim: mengekspornya ke berkas, meninjaunya, mengedit berkas, memindahkannya ke lingkungan baru, dan memangkasnya dengan aman.

Contoh

Tema mendaftarkan jenis pos acme_member dan taksonomi acme_team di setiap lingkungan. Setiap pos anggota dapat memuat:

Kunci meta Isi
_acme_role Jabatan, berupa string biasa
_acme_mentor ID pos anggota lain
_thumbnail_id ID lampiran potret
_acme_api_token Token integrasi yang tidak boleh masuk ke git

Content Sync tidak pernah mendaftarkan jenis pos atau taksonomi. Keduanya harus tersedia di setiap tempat Anda melakukan push.

Langkah 1: Konfigurasikan Content Sync

Content Sync nonaktif sampai Anda mengaktifkannya di blockstudio.json. Sebelum itu, setiap perintah mengembalikan satu baris skipped:

Shell
wp bs content status
Kode
action   entity   id       uid  message
skipped  content  default       Content Sync is disabled. Set content.enabled to true to run this command.

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

Setiap kunci menetapkan batas:

  • postTypes dan taxonomies adalah daftar izin. Apa pun di luar daftar tersebut tidak dibaca, ditulis, atau dipangkas. postTypes yang kosong berarti tidak ada pos yang disentuh.
  • meta.include mengizinkan kunci meta, dengan wildcard *. meta.exclude selalu mengesampingkannya, sedangkan _edit_lock, _edit_last, dan _wp_old_slug dikecualikan secara default.
  • meta.references menyatakan nilai meta mana yang merupakan ID. Content Sync tidak pernah menebak bahwa bilangan bulat adalah ID.
  • id memberi nama pada kumpulan konten. Nama ini disimpan pada setiap entitas yang disinkronkan, dan pemangkasan hanya menyentuh entitas dari kumpulan yang sama.
  • path adalah folder keluaran, relatif terhadap direktori tema aktif.

Langkah 2: Tarik

Pratinjau proyeksi terlebih dahulu. Tidak ada yang ditulis, dan UID yang ditampilkan belum disimpan:

Shell
wp bs content pull --dry-run
Kode
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

Lalu lakukan penarikan sungguhan. Ini menetapkan _blockstudio_content_uid permanen pada setiap entitas yang belum memilikinya dan menulis berkas:

Shell
wp bs content pull
Kode
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

Hasilnya di tema:

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

Nama berkas menggabungkan slug dengan bagian awal UID. Pos JSON memuat bidang, relasi term, dan meta yang diizinkan:

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

Relasi term dan gambar mini menggunakan UID, bukan ID lokal. Isi pos berada di jane.5d4bf9b5.html sebagai markup blok mentah. Pos dengan konten kosong, seperti milik Sam, tidak mendapat berkas .html. _acme_mentor milik Sam disimpan sebagai UID Jane karena kunci tersebut ditetapkan sebagai referensi post.

Langkah 3: Tinjau Sebelum Melakukan Commit

Jalankan status sebelum melakukan commit. Perintah ini membandingkan berkas dan basis data, serta menandai data berisiko:

Shell
wp bs content status
Kode
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.

Wildcard _acme_* menangkap token tersebut. Perlakukan meta.include sebagai batas commit dan kecualikan kunci itu secara eksplisit:

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

Perintah pull berikutnya menulis ulang sam.208db72e.json tanpa token dan membiarkan berkas lainnya tetap utuh. status juga memperingatkan tentang ID numerik di dalam isi markup blok, karena Content Sync tidak menulis ulang ID dalam berkas .html.

Lakukan commit pada folder content/.

Langkah 4: Edit Berkas dan Lakukan Push

Berkas adalah sumber kebenaran untuk push. Ubah peran Jane di berkas JSON dari Design Lead menjadi Head of Design, lalu periksa dampaknya:

Shell
wp bs content status
Kode
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 menampilkan rencana yang sama dalam urutan push. Terapkan rencana itu:

Shell
wp bs content push
Kode
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 memvalidasi seluruh rencana sebelum menulis. Referensi yang ditetapkan tetapi belum terselesaikan, konflik slug, jenis pos yang tidak ada, dan berkas yang formatnya keliru akan menghentikan proses.

WordPress memberikan waktu modifikasi baru pada pos yang diperbarui, sementara berkas masih menyimpan nilai modified lama. Karena itu, proses status tepat setelah push ini melaporkan pos Jane sebagai conflict dengan pesan “Database changed since last sync.” Jalankan pull sekali setelah push untuk merekam waktu baru; kemudian status melaporkan unchanged.

Langkah 5: Pindahkan Konten ke Lingkungan Lain

Di lingkungan baru, berkas menjelaskan pos yang belum ada. Dalam contoh ini, term dan lampiran potret sudah tersedia di sana dengan UID yang sama, jadi hanya dua anggota yang belum ada:

Shell
wp bs content status
Kode
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
Kode
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

Pos-pos itu mendapat ID lokal baru, 536 dan 537. Referensinya ikut disesuaikan: _acme_mentor Sam kini memuat 536, Jane kembali berada di term leadership, dan _thumbnail_id miliknya menunjuk ke lampiran lokal dengan UID yang cocok. Induk pos, induk term, dan relasi term selalu disimpan sebagai UID; nilai meta hanya ditulis ulang untuk kunci dalam meta.references.

Memangkas dengan Aman

Menghapus berkas tidak akan menghapus apa pun saat push kecuali Anda memintanya. Hapus sam.208db72e.json dan coba pangkas:

Shell
wp bs content push --prune
Kode
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.

Simulasi menunjukkan apa yang akan dihapus:

Shell
wp bs content push --prune --dry-run
Kode
action             entity  id   uid          message
...
would-prune-trash  post    537  208db72e-...

push --prune --yes lalu memindahkan pos Sam ke tempat sampah dan melaporkan pruned-trash. Beberapa pengaman membatasi cakupannya:

  • Hanya entitas milik kumpulan konten ini (content.id) yang menjadi kandidat.
  • Hanya jenis pos dan taksonomi yang dikonfigurasi yang dipertimbangkan.
  • Seluruh rencana sumber diurai dan divalidasi sebelum apa pun ditulis atau dipangkas. Jika ada berkas JSON dengan format keliru di folder, push melaporkan baris error seperti could not be read: Syntax error dan tidak memangkas apa pun.

Tindakan default adalah trash. Filter blockstudio/content/orphan_action dapat mengembalikan trash, delete, atau keep untuk setiap entitas. Dengan begitu, term tetap dipertahankan sementara pos mengikuti default:

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

Dengan pengaturan ini, term yatim dilaporkan sebagai would-prune-keep, bukan would-prune-trash.

Media

Berkas media tidak pernah disalin. content.media menentukan apa yang terjadi pada referensi lampiran yang ditetapkan:

  • "manifest" (default) menyimpan UID lampiran dan mencantumkannya di content/media/manifest.json beserta jalur, jenis MIME, dan teks alternatif. Push mengharuskan setiap UID lampiran yang dirujuk tersedia di target, jadi pindahkan unggahan terlebih dahulu melalui alur kerja media yang biasa Anda gunakan.
  • "none" tidak menyertakan referensi lampiran yang ditetapkan dalam berkas. JSON milik Jane kemudian hanya memuat _acme_role. Karena kunci yang tidak disertakan tidak diterapkan saat push, pos target yang sudah ada akan mempertahankan gambar mininya saat ini.

Mengunci Entitas

Terkadang lingkungan target perlu mempertahankan versinya sendiri dari sebuah pos. Tetapkan nilai yang bernilai benar pada meta _blockstudio_content_locked pos tersebut, lalu push akan melewatinya dengan baris locked dan pesan “Locked entity skipped.” Hapus meta itu untuk menyertakannya kembali.

Aturan Kepemilikan

  • Post yang dikelola oleh halaman berbasis file dikecualikan secara default. Dengan includePageSyncManaged: true, Content Sync dapat menyinkronkan meta yang dikonfigurasi untuk post tersebut, tetapi Page Sync tetap mengelola post_content miliknya. Proyeksi JSON tersebut membawa bodyOwner: "page-sync", dan pull secara eksplisit melaporkan isi yang dilewati. Salinan tinjauan .html yang sudah ada dipertahankan dan diabaikan oleh push. Sinkronkan halaman di lingkungan target sebelum melakukan push proyeksi metadatanya.
  • Penulis diabaikan secara default karena pengguna tidak disinkronkan. Dengan authors: "login", file post menyimpan login penulis dan push mencocokkannya dengan pengguna yang sudah ada; pengguna yang tidak ditemukan menyebabkan kesalahan prapemeriksaan.
  • pull tidak pernah menghapus file. Jika entitas di database sudah tidak ada, pull melaporkan filenya sebagai kedaluwarsa dan menyerahkan pembersihannya kepada Anda.

Kapan Sebaiknya Tidak Digunakan

Content Sync cocok untuk konten terkurasi dengan sedikit perubahan: puluhan atau ratusan entri, hingga beberapa ribu jika datanya terstruktur dan dibagi ke dalam jenis pos yang terfokus. Fitur ini bukan pengganti pencadangan atau migrasi basis data. Pesanan, kiriman formulir, log, analitik, dan konten editorial bervolume tinggi sebaiknya ditangani oleh alat tersebut. Definisi taksonomi, berkas biner media, dan ID di dalam markup blok berada di luar cakupannya.

Langkah Berikutnya