انتقل إلى المحتوى

نقل محتوى قاعدة البيانات إلى ملفات باستخدام مزامنة المحتوى

توجد الكتل والقوالب والصفحات المعتمدة على الملفات بالفعل في مستودعك. لكن بعض المحتوى لا يناسب هذا النموذج لأن المحررين ينشئونه في لوحة الإدارة، مثل أعضاء الفريق ومواقع المكاتب ودراسات الحالة. يظل هذا المحتوى مهمًا للمشروع. يحتاج موقع التجهيز إلى صفحة الفريق نفسها الموجودة في الإنتاج، ويحتاج المطور الجديد إلى بيانات واقعية، وينبغي للمراجع أن يرى عند تغيير المسمى الوظيفي. لا تحل تفريغات قاعدة البيانات أيًا من ذلك جيدًا؛ فهي تنقل كل شيء، وتختلف المعرّفات بين البيئات، ولا يراجع أحد فروق SQL.

تسد مزامنة المحتوى هذه الفجوة. يُسقط أمر WP-CLI قائمة سماح من المنشورات والمصطلحات والعلاقات والبيانات الوصفية في ملفات JSON وHTML داخل قالبك. ويطبّق أمر آخر هذه الملفات على قاعدة بيانات مختلفة. يحصل كل كيان على UID قابل للنقل، ولا يعادَت كتابة المراجع بين الكيانات إلا عند التصريح بها.

يعرض هذا الدليل مثال دليل فريق: سحب محتواه إلى ملفات ومراجعته وتحرير ملف ونقله إلى بيئة جديدة ثم تنظيفه بأمان.

المثال

يسجل القالب نوع منشور acme_member وتصنيفًا acme_team في كل بيئة. ويمكن أن يحتوي منشور كل عضو على:

مفتاح البيانات الوصفية المحتوى
_acme_role المسمى الوظيفي، سلسلة نصية عادية
_acme_mentor معرّف منشور عضو آخر
_thumbnail_id معرّف مرفق الصورة الشخصية
_acme_api_token رمز تكامل يجب ألا يصل إلى git مطلقًا

لا تسجل مزامنة المحتوى أنواع المنشورات أو التصنيفات مطلقًا. يجب أن تكون موجودة في كل موضع تدفع إليه المحتوى.

الخطوة 1: إعداد مزامنة المحتوى

تكون مزامنة المحتوى متوقفة حتى تفعّلها في 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 مجموعة المحتوى. ويُخزّن في كل كيان تتم مزامنته، ولا يشمل التنظيف إلا كيانات المجموعة نفسها.
  • يحدد 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

ثم اسحب التغييرات فعليًا. يعيّن هذا معرّفًا دائمًا _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

تجمع أسماء الملفات بين المعرّف المختصر وأول جزء من 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 لا بمعرّفات محلية. ويُخزّن متن المنشور بجواره في 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 من المعرّفات الرقمية داخل محتوى أجسام الكتل، لأن Content Sync لا تعيد كتابة المعرّفات في الملفات .html.

أدرج مجلد content/ في الالتزام.

الخطوة 4: عدّل ملفًا وادفع التغييرات

الملفات هي مصدر الحقيقة لـ push. غيّر دور Jane في الملف 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

يتحقق الدفع من الخطة كاملةً قبل الكتابة. تؤدي المراجع المعلنة التي لم تُحل، وتعارضات الأسماء المختصرة، وأنواع المنشورات المفقودة، والملفات غير السليمة إلى إيقافه.

تمنح WordPress المنشور المحدّث وقت تعديل جديدًا، بينما يظل الملف محتفظًا بقيمة modified القديمة. لذلك، فإن تشغيل status مباشرةً بعد هذا الدفع يعرض منشور Jane بالحالة 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

حصل المنشوران على معرّفات محلية جديدة، 536 و537. وانتقلت المراجع معهما: يحتوي _acme_mentor الخاص بـ Sam الآن على 536، وعاد المنشور الخاص بـ Jane إلى المصطلح 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 بعد ذلك منشور Sam إلى سلة المهملات، وتعرض pruned-trash. وتحافظ عدة ضوابط على نطاق العملية:

  • لا تُعدّ مرشحةً إلا الكيانات التي تملكها مجموعة المحتوى هذه (content.id).
  • لا تُؤخذ في الاعتبار إلا أنواع المنشورات والتصنيفات المُعدّة.
  • تُحلَّل خطة المصدر كاملةً وتُتحقَّق قبل إجراء أي كتابة أو تنقية. إذا وُجد ملف JSON غير سليم في المجلد، يعرض الدفع صفًا بالحالة 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 والنص البديل. يتطلب الدفع وجود معرّف UID لكل مرفق مشار إليه في البيئة المستهدفة، لذا انقل الملفات المرفوعة أولًا عبر سير عمل الوسائط المعتاد.
  • يُبقي "none" مراجع المرفقات المعلنة خارج الملفات. عندئذٍ لا يحتوي JSON الخاص بـ Jane إلا على _acme_role. وبما أن المفتاح المحذوف لا يُطبّق عند الدفع، يحتفظ أي منشور موجود في البيئة المستهدفة بصورته المصغرة الحالية.

قفل كيان

قد تحتاج البيئة المستهدفة أحيانًا إلى الاحتفاظ بنسختها من منشور واحد. عيّن قيمة صادقة للبيانات الوصفية _blockstudio_content_locked لذلك المنشور، وسيتخطاه الدفع مع صف بالحالة locked والرسالة “تم تخطي الكيان المقفل.” احذف البيانات الوصفية لإدراجه مجددًا.

قواعد الملكية

  • تُستبعد افتراضيًا المقالات التي تديرها الصفحات المعتمدة على الملفات. باستخدام includePageSyncManaged: true، يمكن لـ Content Sync مزامنة البيانات الوصفية المضبوطة لها، لكن تظل Page Sync مسؤولة عن post_content الخاص بها. وتحمل إسقاطات JSON هذه bodyOwner: "page-sync"، ويُبلغ السحب صراحةً عن المتن المتخطى. تُحفظ نسخ المراجعة الحالية من .html ويتجاهلها الدفع. زامن الصفحات في البيئة المستهدفة قبل دفع إسقاطات بياناتها الوصفية.
  • يُتجاهل المؤلفون افتراضيًا لأن مزامنة المستخدمين غير مفعّلة. باستخدام authors: "login"، تخزّن ملفات المقالات اسم دخول المؤلف، ويحل الدفع الاسم إلى مستخدم موجود؛ ويؤدي غياب المستخدم إلى خطأ في الفحص المسبق.
  • لا يحذف pull الملفات مطلقًا. عندما يُحذف كيان من قاعدة البيانات، يُبلغ السحب عن ملفه بوصفه قديمًا ويترك لك تنظيفه.

متى لا تستخدمها

تلائم Content Sync المحتوى المنسّق قليل التغيير: عشرات أو مئات الإدخالات، وقد تصل إلى بضعة آلاف إذا كانت البيانات منظّمة ومقسّمة إلى أنواع منشورات محددة. وهي ليست بديلًا عن النسخ الاحتياطية لقواعد البيانات أو عمليات الترحيل. مكان الطلبات، وإرسالات النماذج، والسجلات، والتحليلات، والمحتوى التحريري ذي الحجم الكبير هو تلك الأدوات. وتقع تعريفات التصنيفات، والملفات الثنائية للوسائط، والمعرّفات داخل ترميز الكتل خارج نطاقها.

الخطوات التالية