نقل محتوى قاعدة البيانات إلى ملفات باستخدام مزامنة المحتوى
توجد الكتل والقوالب والصفحات المعتمدة على الملفات بالفعل في مستودعك. لكن بعض المحتوى لا يناسب هذا النموذج لأن المحررين ينشئونه في لوحة الإدارة، مثل أعضاء الفريق ومواقع المكاتب ودراسات الحالة. يظل هذا المحتوى مهمًا للمشروع. يحتاج موقع التجهيز إلى صفحة الفريق نفسها الموجودة في الإنتاج، ويحتاج المطور الجديد إلى بيانات واقعية، وينبغي للمراجع أن يرى عند تغيير المسمى الوظيفي. لا تحل تفريغات قاعدة البيانات أيًا من ذلك جيدًا؛ فهي تنقل كل شيء، وتختلف المعرّفات بين البيئات، ولا يراجع أحد فروق 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:
{
"$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 على الحقول وعلاقات المصطلحات والبيانات الوصفية المسموح بها:
{
"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 كحدّ للالتزام واستبعد المفتاح صراحةً:
"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 لكل كيان. يحافظ هذا على المصطلحات، مع إبقاء المنشورات على الإجراء الافتراضي:
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 المحتوى المنسّق قليل التغيير: عشرات أو مئات الإدخالات، وقد تصل إلى بضعة آلاف إذا كانت البيانات منظّمة ومقسّمة إلى أنواع منشورات محددة. وهي ليست بديلًا عن النسخ الاحتياطية لقواعد البيانات أو عمليات الترحيل. مكان الطلبات، وإرسالات النماذج، والسجلات، والتحليلات، والمحتوى التحريري ذي الحجم الكبير هو تلك الأدوات. وتقع تعريفات التصنيفات، والملفات الثنائية للوسائط، والمعرّفات داخل ترميز الكتل خارج نطاقها.
الخطوات التالية
- مرجع Content Sync: جميع مفاتيح الإعداد، وتنسيقات الملفات، وحالة المزامنة المخزّنة.
- إنشاء موقع للتوثيق: محتوى يبدأ في الملفات ثم تتم مزامنته إلى WordPress، لا العكس.
- إنشاء صفحات معتمدة على الملفات: صفحات تتولى القوالب في القالب تنسيق بنيتها.