İçerik Eşitleme ile Veritabanı İçeriğini Dosyalara Taşıma
Bloklar, şablonlar ve dosya tabanlı sayfalar zaten deponuzda bulunur. Bazı içerikler bu yapıya uymaz; çünkü bunları yönetim panelinde editörler oluşturur: ekip üyeleri, ofis konumları, vaka incelemeleri. Bu içerikler de proje için önemlidir. Hazırlık sitesi üretimdekiyle aynı ekip sayfasına ihtiyaç duyar, yeni geliştiricinin gerçekçi verilere ihtiyacı vardır ve gözden geçiren kişi bir iş unvanı değiştirildiğinde bunu görebilmelidir. Veritabanı dökümleri bunların hiçbirini iyi çözmez. Her şeyi taşırlar, kimlikler ortama göre değişir ve hiç kimse SQL farkını gözden geçirmez.
Content Sync bu açığı kapatır. Bir WP-CLI komutu; yazıların, terimlerin, ilişkilerin ve meta verilerin izin verilenler listesini tema klasörünüzdeki JSON ve HTML dosyalarına aktarır. Başka bir komut bu dosyaları farklı bir veritabanına uygular. Her varlığa taşınabilir bir UID atanır ve varlıklar arasındaki referanslar yalnızca sizin belirttiğiniz yerlerde yeniden yazılır.
Bu kılavuzda bir ekip dizinini dosyalara aktarma, gözden geçirme, bir dosyayı düzenleme, yeni bir ortama taşıma ve güvenli biçimde temizleme adımları anlatılıyor.
Örnek
Tema, her ortamda bir acme_member yazı türü ve bir acme_team taksonomisi kaydeder. Her üye yazısında şunlar bulunabilir:
| Meta anahtarı | İçerik |
|---|---|
_acme_role |
İş unvanı, düz bir dize |
_acme_mentor |
Başka bir üyenin yazı kimliği |
_thumbnail_id |
Portre görselinin ek kimliği |
_acme_api_token |
git ortamına asla ulaşmaması gereken bir entegrasyon belirteci |
Content Sync, yazı türlerini veya taksonomileri kaydetmez. Bunlar, veriyi gönderdiğiniz her yerde mevcut olmalıdır.
1. Adım: Content Sync’i yapılandırın
Content Sync, blockstudio.json içinde etkinleştirene kadar kapalıdır. O zamana dek her komut tek bir skipped satırı döndürür:
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.
Bir content grubu ekleyin:
{
"$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"
}
}
Her anahtar bir sınır belirler:
postTypesvetaxonomiesizin verilenler listeleridir. Bunların dışındaki hiçbir şey okunmaz, yazılmaz veya temizlenmez. Boş birpostTypes, hiçbir yazıya dokunulmayacağı anlamına gelir.meta.include, meta anahtarları için izin verilenler listesini tanımlar;*joker karakterlerini kullanır.meta.excludeher zaman önceliklidir;_edit_lock,_edit_lastve_wp_old_slugise varsayılan olarak hariç tutulur.meta.references, hangi meta değerlerinin kimlik olduğunu belirtir. Content Sync, bir tam sayının kimlik olduğunu asla varsaymaz.id, içerik kümesini adlandırır. Bu ad her eşitlenen varlıkta saklanır ve temizleme işlemi yalnızca aynı kümeye ait varlıklara dokunur.path, etkin tema dizinine göreli çıktı klasörüdür.
2. Adım: Aktarın
Önce aktarımın önizlemesini görün. Hiçbir şey yazılmaz ve gösterilen UID’ler henüz saklanmaz:
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
Ardından gerçekten aktarın. Böylece UID’si olmayan her varlığa kalıcı bir _blockstudio_content_uid atanır ve dosyalar yazılır:
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
Tema içindeki sonuç:
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
Dosya adları, kısa adı UID’nin ilk bölümüyle birleştirir. JSON yazısı alanları, terim ilişkilerini ve izin verilen meta verileri içerir:
{
"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"
}
}
Terim ilişkisi ve küçük görsel, yerel kimlikler değil UID’lerdir. Yazı gövdesi, ham blok işaretlemesi olarak yanındaki jane.5d4bf9b5.html içinde yer alır. Sam’inki gibi içeriği boş bir yazı için .html dosyası oluşturulmaz. Anahtar bir post referansı olarak tanımlandığından Sam’in _acme_mentor değeri Jane’in UID’si olarak saklanır.
3. Adım: İşlemi kaydetmeden önce gözden geçirin
Kaydetmeden önce status komutunu çalıştırın. Dosyalarla veritabanını karşılaştırır ve riskli verileri de işaretler:
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_* joker karakteri belirteci yakaladı. meta.include öğesini kaydetme sınırı olarak değerlendirin ve anahtarı açıkça hariç tutun:
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
Sonraki pull, sam.208db72e.json öğesini belirteç olmadan yeniden yazar ve diğer dosyalara dokunmaz. status ayrıca blok işaretleme gövdelerindeki sayısal kimlikler konusunda uyarır; çünkü Content Sync, .html dosyalarındaki kimlikleri yeniden yazmaz.
content/ klasörünü kaydedin.
4. Adım: Bir dosyayı düzenleyip gönderin
push için asıl kaynak dosyalardır. JSON dosyasındaki Jane’in görevini Design Lead değerinden Head of Design değerine değiştirin, ardından neler olacağını kontrol edin:
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, gönderme sırasındaki planın aynısını yazdırır. Uygulayın:
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
Gönderme işlemi, yazma işleminden önce planın tamamını doğrular. Çözümlenmemiş tanımlı referanslar, kısa ad çakışmaları, eksik yazı türleri ve hatalı dosyalar işlemi durdurur.
WordPress, güncellenen bir yazıya yeni bir değiştirilme zamanı verir; dosyada ise eski modified değeri kalır. Bu nedenle gönderme işleminden hemen sonra yapılan status çalıştırması, Jane’in yazısını “Veritabanı son eşitlemeden bu yana değişti.” mesajıyla birlikte conflict olarak bildirir. Yeni zamanı kaydetmek için gönderdikten sonra pull komutunu bir kez çalıştırın; ardından status, unchanged sonucunu bildirir.
5. Adım: İçeriği başka bir ortama taşıyın
Yeni bir ortamda dosyalar, henüz mevcut olmayan yazıları tanımlar. Bu örnekte terim ve portre eki aynı UID’lerle orada zaten bulunduğundan yalnızca iki üye eksiktir:
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
Yazılara 536 ve 537 olmak üzere yeni yerel kimlikler verildi. Referanslar da bunlara göre güncellendi: Sam’in _acme_mentor değeri artık 536 içeriyor, Jane yeniden leadership teriminde yer alıyor ve Jane’in _thumbnail_id değeri, eşleşen UID’ye sahip yerel eke işaret ediyor. Yazı üst öğeleri, terim üst öğeleri ve terim ilişkileri her zaman UID olarak saklanır; meta değerleri ise yalnızca meta.references içindeki anahtarlar için yeniden yazılır.
Güvenli temizleme
Bir dosyayı silmek, siz istemediğiniz sürece gönderme sırasında hiçbir şeyi silmez. sam.208db72e.json öğesini kaldırın ve temizlemeyi deneyin:
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
Deneme çalıştırması, silinecekleri gösterir:
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
Ardından push --prune --yes, Sam’in yazısını çöp kutusuna taşır ve pruned-trash bildirir. Birkaç koruma bu işlemin kapsamını dar tutar:
- Yalnızca bu içerik kümesinin (
content.id) sahip olduğu varlıklar adaydır. - Yalnızca yapılandırılmış yazı türleri ve taksonomiler dikkate alınır.
- Yazma veya temizleme öncesinde kaynak planının tamamı ayrıştırılır ve doğrulanır. Klasörde hatalı bir JSON dosyası varsa gönderme işlemi
could not be read: Syntax errorgibi birerrorsatırı bildirir ve hiçbir şeyi temizlemez.
Varsayılan eylem trash olur. blockstudio/content/orphan_action filtresi her varlık için trash, delete veya keep döndürebilir. Böylece yazılar varsayılan eylemde kalırken terimler korunur:
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
Bu ayarla, sahipsiz bir terim would-prune-keep yerine would-prune-trash olarak bildirilir.
Medya
Medya dosyaları hiçbir zaman kopyalanmaz. content.media, tanımlı ek referanslarına ne olacağını belirler:
"manifest"(varsayılan), ek UID’lerini saklar ve bunları yol, MIME türü ve alternatif metinle birliktecontent/media/manifest.jsoniçinde listeler. Gönderme işlemi, referans verilen her ek UID’sinin hedefte bulunmasını gerektirir; bu nedenle önce yüklemeleri olağan medya iş akışınızla taşıyın."none", tanımlı ek referanslarını dosyalara eklemez. Jane’in JSON öğesi bu durumda yalnızca_acme_roleiçerir. Atlanmış bir anahtar gönderme sırasında uygulanmadığından, hedefteki mevcut yazı küçük görselini korur.
Bir varlığı kilitleme
Bazen hedef ortamda bir yazının kendi sürümünün korunması gerekir. O yazının _blockstudio_content_locked metasını doğru bir değere ayarlayın; gönderme işlemi yazıyı bir locked satırı ve “Kilitli varlık atlandı.” mesajıyla atlar. Yazıyı yeniden dahil etmek için metayı silin.
Sahiplik kuralları
- Dosya tabanlı sayfalar tarafından yönetilen yazılar varsayılan olarak hariç tutulur.
includePageSyncManaged: trueile Content Sync, yapılandırılmış meta verilerini eşitleyebilir; ancak Page Sync, bunlarınpost_contentöğelerinin sahibi olmaya devam eder. Bu JSON projeksiyonlarıbodyOwner: "page-sync"taşır ve pull işlemi atlanan gövdeyi açıkça bildirir. Mevcut.htmlinceleme kopyaları korunur ve push işlemi tarafından yok sayılır. Meta veri projeksiyonlarını push etmeden önce sayfaları hedef ortamda eşitleyin. - Kullanıcılar eşitlenmediği için yazarlar varsayılan olarak yok sayılır.
authors: "login"ile yazı dosyaları yazarın giriş adını saklar ve push işlemi bunu mevcut bir kullanıcıyla eşleştirir; kullanıcı bulunamazsa ön denetim hatası oluşur. pulldosyaları hiçbir zaman silmez. Bir veritabanı öğesi silindiğinde pull işlemi dosyasını güncelliğini yitirmiş olarak bildirir ve temizliği size bırakır.
Ne zaman kullanmamalı
Content Sync; seçilmiş, nadiren değişen içerikler için uygundur: onlarca veya yüzlerce kayıt, veriler yapılandırılmış ve odaklı yazı türlerine ayrılmışsa birkaç bine kadar çıkabilir. Veritabanı yedeklerinin veya geçişlerinin yerini tutmaz. Siparişler, form gönderimleri, günlükler, analiz verileri ve yüksek hacimli editoryal içerikler bu amaçlara yönelik araçlarda tutulmalıdır. Taksonomi tanımları, medya ikili dosyaları ve blok işaretlemesinin içindeki kimlikler kapsam dışındadır.
Sonraki Adımlar
- Content Sync başvurusu: tüm yapılandırma anahtarları, dosya biçimleri ve saklanan eşitleme durumu.
- Dokümantasyon sitesi oluşturma: dosyalarda başlayıp WordPress içine eşitlenen içerik; diğer yönde.
- Dosya tabanlı sayfalar oluşturma: yapısı temadaki şablonların sahibi olduğu sayfalar.