İçeriğe geç

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

Kabuk
wp bs content status
Kod
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:

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

Her anahtar bir sınır belirler:

  • postTypes ve taxonomies izin verilenler listeleridir. Bunların dışındaki hiçbir şey okunmaz, yazılmaz veya temizlenmez. Boş bir postTypes, hiçbir yazıya dokunulmayacağı anlamına gelir.
  • meta.include, meta anahtarları için izin verilenler listesini tanımlar; * joker karakterlerini kullanır. meta.exclude her zaman önceliklidir; _edit_lock, _edit_last ve _wp_old_slug ise 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:

Kabuk
wp bs content pull --dry-run
Kod
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:

Kabuk
wp bs content pull
Kod
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ç:

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

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

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:

Kabuk
wp bs content status
Kod
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:

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

Kabuk
wp bs content status
Kod
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:

Kabuk
wp bs content push
Kod
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:

Kabuk
wp bs content status
Kod
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
Kabuk
wp bs content push
Kod
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:

Kabuk
wp bs content push --prune
Kod
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:

Kabuk
wp bs content push --prune --dry-run
Kod
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 error gibi bir error satı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:

PHP
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 birlikte content/media/manifest.json iç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_role iç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: true ile Content Sync, yapılandırılmış meta verilerini eşitleyebilir; ancak Page Sync, bunların post_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 .html inceleme 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.
  • pull dosyaları 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