CLI
يسجّل Blockstudio أوامر WP-CLI لإدارة الكتل والصفحات المدعومة بالملفات وسجلات قاعدة البيانات ودوال RPC ومهام cron والإعدادات وتهيئة اللغة WPML من الطرفية.
الكتل
سرد جميع الكتل
wp bs blocks list
+----------------------------+---------------------+-----------+------------------------+
| name | title | component | category |
+----------------------------+---------------------+-----------+------------------------+
| my-theme/hero | Hero | | my-theme |
| my-theme/card | Card | yes | my-theme |
| my-theme/newsletter | Newsletter | | my-theme |
+----------------------------+---------------------+-----------+------------------------+
التصفية لعرض المكوّنات فقط
wp bs blocks list --components
الإخراج بصيغة JSON
wp bs blocks list --format=json
التحقق من الحقول المخزنة
wp bs blocks validate 42
wp bs blocks validate 42 57 --format=json
يتحقق من المحتوى المخزن لمعرّفات المنشورات المحددة، بما في ذلك innerBlocks المتداخلة، باستخدام bs_validate_block().
لا يعرض الكتل، أو يوسّع مراجع الأنماط المتزامنة، أو يعدّل المنشورات.
يتم تخطي الكتل غير المعروفة التي لا تتضمن امتدادات Blockstudio.
يعرض الجدول الافتراضي معرّف المنشور ومسار الكتلة ذي الفهرسة الصفرية واسم الكتلة ورمز النتيجة ومسار الحقل والمصدر والرسالة. ويتضمن JSON أيضًا القيمتين الأصليتين value وexpected. قد يكون مسار الكتلة المتداخلة 0/1 ومسار الحقل cards/2/style؛ وهذان مساران منفصلان.
يخرج الأمر بالرمز 0 عند عدم وجود نتائج، وبالرمز 1 عند وجودها. يكون إخراج JSON قائمة نصية بسيطة، تشمل [] عند النجاح، كي تتمكن الأتمتة من قراءتها حتى عندما يخرج الأمر بالرمز 1. تُعد المنشورات المفقودة والمعرّفات المفقودة والتنسيقات غير table أو json أخطاءً. يتم التحقق من جميع المعرّفات قبل بدء التحقق.
عرض الكتل
wp bs blocks render
wp bs blocks render my-theme/hero my-theme/card
wp bs blocks render my-theme/card --attributes='{"variant":"wide"}'
wp bs blocks render my-theme/card --attributes=@card.json --format=json
يعرض الكتل المسجلة كما تفعل الصفحة، ويبلغ عن كل إشعار PHP وتحذير وإيقاف دعم وخطأ مُلقى تثيره قوالبها. يمكن للنسق تشغيل الأمر في CI لاختبار كتلِه سريعًا مقابل Blockstudio المثبت. عند عدم تحديد أسماء، تُعرض كل الكتل المسجلة، بما فيها المكونات.
يُعرض كل بلوك عبر do_blocks() انطلاقًا من تعليق بلوك يتضمن blockstudio.attributes، وهو الشكل الذي يخزنه المحرر، ضمن سياق الواجهة الأمامية لـ WP-CLI بدلًا من معاينة أداة الإدراج. لا يتم إعداد أي منشور مستعلم عنه للعرض. تعرض الجزر الديناميكية متن قالبها الفعلي بدلًا من العنصر النائب فقط، ولا يُدرج إخراج القالب العارض في التقرير.
لا يحفظ الأمر المنشورات أو قيم الحقول بنفسه، لكنه ينفذ قوالبك وخطافات العرض كما يفعل PHP عادي. وقد تكتب هذه القوالب والخطافات بيانات، أو تستدعي خدمات خارجية، أو تُحدث آثارًا جانبية أخرى. شغّله على شيفرة موثوقة في موقع اختبار مخصص؛ فهو ليس بيئة معزولة للقراءة فقط.
تُختار سمات العرض لكل بلوك على حدة:
| الحالة | السمات |
|---|---|
example |
example.attributes الخاص بـ block.json للبلوك، أي القيم التي تستخدمها معاينة أداة الإدراج. |
defaults |
default لكل حقل. تُستخدم للكتل التي لا تحتوي على example.attributes؛ ويطبع الأمر سطرًا لكل منها. |
attributes |
قيم --attributes، لتحل محل المثال. |
يقبل --attributes كائن JSON لقيم الحقول المفهرسة بمفتاح التخزين، أو @ ومسار ملف يحتوي عليه، ويتطلب اسم بلوك واحدًا بالضبط. استخدمه للوصول إلى فروع القالب التي لا يغطيها المثال، مثل أحد المتغيرات. يتم تخطي قيم المثال التي لا تُنتج سوى صور عناصر نائبة في معاينة أداة الإدراج، ولا تُعرض innerBlocks الخاصة بالمثال.
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
| block | case | level | message | file | line |
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
| smoke/deprecated | defaults | Deprecated | strlen(): Passing null to parameter #1 ($string) of type string is deprecated | /wordpress/wp-content/themes/smoke-theme/blockstudio/deprecated/index.php | 1 |
| smoke/undefined-key | example | Warning | Undefined array key "subtitle" | /wordpress/wp-content/themes/smoke-theme/blockstudio/undefined-key/index.php | 2 |
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
يعرض الجدول صفًا واحدًا لكل مشكلة. أما إخراج JSON فهو قائمة تضم عنصرًا لكل بلوك معروض، بما في ذلك الكتل التي لا مشكلات فيها، كي تتمكن الأتمتة من معرفة الحالة المستخدمة:
[
{
"block": "smoke/branch",
"case": "attributes",
"problems": [
{
"level": "Warning",
"message": "Undefined array key \"width\"",
"file": "/wordpress/wp-content/themes/smoke-theme/blockstudio/branch/index.php",
"line": 2
}
]
}
]
تكون level هي Notice أو Warning أو Deprecated أو Error. تُبلَّغ المشكلة التي تتكرر في الملف والسطر نفسيهما، مثلًا داخل حلقة، مرة واحدة لكل بلوك. لا يُبلّغ عن المشكلات التي تم إسكاتها باستخدام @. يُصدر WordPress إشعارات إيقاف الدعم الخاصة به، مثل إشعارات _deprecated_function()، فقط عند تفعيل WP_DEBUG.
يخرج الأمر بالرمز 0 عند عدم العثور على مشكلات، وبالرمز 1 خلاف ذلك. تُعد أسماء الكتل غير المعروفة وملفات --attributes التي يتعذر قراءتها أو غير الصالحة والتنسيقات غير table أو json أخطاءً، ويتم التحقق من جميع الأسماء قبل عرض أول بلوك.
الصفحات
مزامنة الصفحات القائمة على الملفات صريحة. لا تنفّذ طلبات WordPress العادية اكتشافًا كاملًا للصفحات أو تكتب منشورات الصفحات. وقد يقرأ وقت التشغيل البارد بيانات المجموعات مرة واحدة لاستعادة المسارات، دون مزامنة المحتوى.
wp bs pages sync
يوفّق الأمر بين الجرد المطلوب كاملًا وما هو موجود، ويبلّغ عن الصفحات المكتشفة والمنشأة والمحدّثة وغير المتغيرة والمقفلة والمحفوظة والمزالة والفاشلة. لا تؤدي بصمات التطابق إلى أي كتابة للمنشور أو بياناته الوصفية.
يسمي إخراج الجدول الصفحات التي تغيّرت أو قُفلت أو حُفظ محتواها أو أُزيلت، مع معرّفات منشوراتها. يتضمن JSON أيضًا إدخالات pages.<name>.preserved وpages.<name>.overwritten وremovedPages مع اسم الصفحة والمفتاح ومعرّف المنشور وإجراء التنظيف. ويُبلّغ عن المنشور المطابق بعد الدمج حسب المفتاح على أنه لم يتغير، دون إنشاء مراجعة أو تحديث الطابع الزمني للتعديل.
تُحفظ حالات النشر الحالية؛ وتُطبع استبدالات العنوان والاسم اللطيف المملوكة للملف على هيئة تحذيرات. راجع ملكية حقول المنشور.
استخدم --authoritative لاستبدال المحتوى المُدار بدلًا من الاحتفاظ بمحتوى المحرر ذي المفاتيح، واستخدم --full للإبلاغ عن العملية كتسوية كاملة بصرف النظر عن هوية المصدر المخزنة. وفي كلتا الحالتين، تقارن كل عملية الجرد بالكامل:
wp bs pages sync --authoritative --full
لبرامج النشر التي تحتاج إلى التقرير الكامل:
wp bs pages sync --format=json
يُفحص كل ما يحلله الأمر من صفحات بحثًا عن سمات تخزنها كتلها لكنها لا تعرضها مطلقًا: سمات لا تعرّفها كتلة Blockstudio كحقل ولا تمررها إلى عنصرها الجذر، مثل class غير المعرّف. يعرض الجدول تحذيرًا لكل صفحة وكتلة، ويحصيها عمود dropped، ويسردها تقرير JSON ضمن pages.<name>.droppedAttributes. ولا تُحلل الصفحات التي لم يتغير مصدرها مجددًا؛ لذا سيُبلغ عنها عند تغيرها لاحقًا، أو في أول مزامنة بعد ترقية تغيّر المحلل.
ينتهي الأمر بفشل عند الإبلاغ عن خطأ أثناء الاكتشاف أو التسوية. راجع الصفحات للاطلاع على عقد PHP API وهوية النشر.
قاعدة البيانات
سرد المخططات
wp bs db schemas
+-------------------+-------------+---------+---------------------+
| block | schema | storage | fields |
+-------------------+-------------+---------+---------------------+
| my-theme/app | subscribers | table | email, name, plan |
| my-theme/app | logs | jsonc | action, details |
| my-theme/app | events | storh | title, status |
+-------------------+-------------+---------+---------------------+
عمليات CRUD
# List records
wp bs db list my-theme/app subscribers
# List with filters
wp bs db list my-theme/app subscribers --plan=pro --limit=10
# Get a single record
wp bs db get my-theme/app subscribers 1
# Create a record
wp bs db create my-theme/app subscribers --email=a@b.com --plan=pro
# Update a record
wp bs db update my-theme/app subscribers 1 --plan=enterprise
# Delete a record
wp bs db delete my-theme/app subscribers 1
بالنسبة إلى الكتل ذات المخطط الواحد، يكون اسم المخطط افتراضيًا default:
wp bs db list my-theme/leads
ترحيل سجلات JSONC إلى Storh
استخدم migrate عندما يكون للمخطط ملف db/{schema}.jsonc بالفعل وتريد نقل سجلاته إلى خلفية الملفات Storh:
wp bs db migrate my-theme/app subscribers --to=storh
للكتل ذات المخطط الواحد:
wp bs db migrate my-theme/app --to=storh
يحافظ الأمر على معرّفات السجلات الصحيحة، ويكتب إلى uploads/blockstudio/db/{block-scope}/{schema}/، ويعيد إنشاء فهارس Storh، ويتحقق من مخزن الهدف، ويُبقي ملف المصدر .jsonc في مكانه.
تنسيقات الإخراج
تدعم جميع أوامر السرد التنسيقات التالية: --format=table (الافتراضي) و--format=json و--format=csv:
wp bs db list my-theme/app subscribers --format=json
RPC
سرد جميع الدوال
wp bs rpc list
+-------------------+-------------+--------+----------------+---------+
| block | function | public | capability | methods |
+-------------------+-------------+--------+----------------+---------+
| my-theme/app | subscribe | yes | | POST |
| my-theme/app | stats | | edit_posts | POST |
| my-theme/app | get_status | | | GET,POST|
+-------------------+-------------+--------+----------------+---------+
استدعاء دالة
wp bs rpc call my-theme/app subscribe --email=user@example.com
الإخراج بصيغة JSON:
{
"success": true
}
تُمرر المعلمات كخيارات --key=value:
wp bs rpc call my-theme/app load_more --offset=10 --limit=5
Cron
سرد جميع المهام
wp bs cron list
+-------------------+----------+----------+---------------------+
| block | job | schedule | next_run |
+-------------------+----------+----------+---------------------+
| my-theme/app | cleanup | daily | 2026-03-17 00:00:00 |
| my-theme/app | sync | hourly | 2026-03-16 15:00:00 |
+-------------------+----------+----------+---------------------+
تشغيل مهمة يدويًا
wp bs cron run my-theme/app cleanup
ينفّذ هذا استدعاء الدالة فورًا، بصرف النظر عن الجدول. وهو مفيد للاختبار وتصحيح الأخطاء.
الإعدادات
عرض جميع الإعدادات
wp bs settings list
الحصول على إعداد محدد
wp bs settings get tailwind/enabled
wp bs settings get assets/enqueue
Tailwind
تجميع HTML إلى CSS
wp bs tailwind compile '<div class="flex items-center p-4">'
التجميع من ملف
wp bs tailwind compile --file=template.html
إدارة ذاكرة التخزين المؤقت
wp bs tailwind cache path # show cache directory
wp bs tailwind cache clear # clear compiled cache
SCSS
تجميع SCSS إلى CSS
wp bs scss compile '$color: red; .test { color: $color; }'
التجميع من ملف
wp bs scss compile --file=styles.scss
الحقول المخصصة
سرد جميع الحقول المخصصة المسجّلة
wp bs fields list
+-------+----------------+---------------------------+
| name | title | fields |
+-------+----------------+---------------------------+
| hero | Hero Section | heading, description, cta |
| card | Card | title, image, link |
+-------+----------------+---------------------------+
الأصول
سرد جميع الأصول
wp bs assets list
التصفية حسب النوع
wp bs assets list --type=global
wp bs assets list --type=admin
wp bs assets list --type=editor
wp bs assets list --type=registered
البرمجة النصية
تدعم جميع الأوامر --format=json لتسهيل تمرير المخرجات:
# Export all subscribers as JSON
wp bs db list my-theme/app subscribers --format=json > subscribers.json
# Count records
wp bs db list my-theme/app subscribers --format=json | jq length
# Batch delete
wp bs db list my-theme/app logs --format=json | \
jq -r '.[].id' | \
xargs -I {} wp bs db delete my-theme/app logs {}
مزامنة المحتوى
تتيح مشاريع مزامنة المحتوى مزامنة محتوى WordPress المسموح به إلى الملفات، ثم تطبيق تلك الملفات على قاعدة البيانات. تتم العملية صراحةً وتحركها CLI؛ ولا تجري عند تحميل الصفحة أو تهيئة الإدارة.
راجع مزامنة المحتوى للاطلاع على الإعداد وتنسيق الملفات وإرشادات تحديد الحالات المناسبة للمحتوى في قاعدة البيانات القائم على الملفات.
سحب محتوى قاعدة البيانات إلى الملفات
wp bs content pull
حصر السحب بنوع محتوى أو تصنيف واحد مُعدّ:
wp bs content pull --post-type=team_member
wp bs content pull --taxonomy=category
معاينة العملية دون كتابة المعرّفات الفريدة أو الملفات:
wp bs content pull --dry-run
دفع الملفات إلى قاعدة البيانات
wp bs content push
معاينة خطة التطبيق دون الكتابة:
wp bs content push --dry-run
حذف المنشورات والمصطلحات في قاعدة البيانات التي تملكها مجموعة المحتوى ولم تعد موجودة في الملفات:
wp bs content push --prune --yes
مع --prune، يطبّق Blockstudio جميع تغييرات الملفات أولًا، ثم يحذف الكيانات التي تملكها مجموعة المحتوى ولم تعد موجودة في الملفات. ويرفض تنفيذ الحذف الإتلافي ما لم يكن --yes موجودًا.
التحقق من الحالة
wp bs content status
يعرض الجدول كل كيان مرتبط بملف بإحدى الحالات التالية: unchanged أو would-update أو missing-db أو conflict أو locked أو orphaned.
العرض المسبق الثابت
راجع العرض المسبق الثابت لذاكرة التخزين المؤقت نفسها؛ فهذه الأوامر تديرها.
تهيئة الإدخالات القديمة
wp bs prerender warm
يضيف عناوين URL العامة القديمة إلى قائمة الانتظار، ثم يعيد عرض ما يصل إلى warm.concurrency مهمة من قائمة الإحماء الدائمة، ويطبع ملخصًا يتضمن أعداد JSON وqueued وprocessed وwarmed وskipped وfailed. تُضاف المهام البديلة تلقائيًا عند تغيّر المحتوى أو الموقع. شغّل الأمر مجددًا، أو اترك أداة الإحماء المجدولة تعمل، لمعالجة عدد أكبر من المهام في قائمة الانتظار؛ فإذا تعذّر عرض URL، فسيظل قديمًا ويُضاف إلى القائمة مجددًا عند التشغيل التالي. في وضع graph، تكون أداة الإحماء لكل URL متوقفة ولا يضيف الأمر أي مهام إلى القائمة.
إعداد تقرير عن حالة ذاكرة التخزين المؤقت
wp bs prerender status
يعرض الهوية النشطة والملفات والبايتات وسجلات الرسم البياني وحالة قائمة الانتظار وتقرير خريطة التقديم المبكر، إضافةً إلى عدادات الإصابات والإخفاقات وعمليات الإنشاء لكل نطاق.
مسح ذاكرة التخزين المؤقت
wp bs prerender purge
يحذف المستندات المعروضة مسبقًا للموقع الحالي. يعيد الطلب المجهول التالي أو جولة التهيئة إنشاءها.
فحص خريطة التقديم المبكر وتنقيحها
wp bs prerender map status
wp bs prerender map prune --dry-run
wp bs prerender map prune
يعرض map status خريطة التقديم المبكر على مستوى التثبيت: إدخالاتها ومساراتها، ومستندات المسارات المفقودة، وإدخالات orphaned للمواقع التي لم تعد موجودة، وإدخالات dead التي اختفت أدلتها. يحذف map prune الإدخالات اليتيمة والميتة، ويطبع كل إدخال محذوف مع سبب حذفه؛ أما --dry-run فيطبع التقرير نفسه دون كتابة. لا يمس الخريطة التي تملكها أداة أخرى.
WPML
إنشاء تهيئة اللغة
wp bs wpml config
wp bs wpml config --file=wp-content/themes/my-theme/wpml-config.xml
يطبع wpml-config.xml يحدّد حقول النص لكل بلوك مسجل لترجمتها، وحقول ملفاته كمعرّفات مرفقات، أو يكتبها باستخدام --file. في ملف موجود، لا يُستبدل سوى القسم الواقع بين علامتي Blockstudio. راجع WPML لمعرفة ما الذي يتم تحديده وكيفية إبقاء الملف محدّثًا.
ترحيل وسوم الكتل
يعيد نص برمجي مستقل كتابة الاختصارات ذات البادئات والأسماء البديلة بالصيغة المعتمدة <bs:namespace-slug>. لا يحمّل WordPress ولا يكتب شيئًا ما لم يُمرر --apply صراحةً:
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
--root="$PWD" \
--prefix-map=/tmp/project-prefixes.json \
--known-blocks=/tmp/project-blocks.json \
--aliases=/tmp/project-aliases.json \
--report=/tmp/blockstudio-tag-migration.json \
--dry-run
يربط ملف البادئات البادئات التي يملكها المستدعي بمساحات أسماء مرتبة. وملف الكتل المعروفة هو قائمة JSON بأسماء الكتل المسجلة. الأسماء البديلة الدقيقة اختيارية. يتضمن التقرير تعيينات حتمية وتجزئات قبل التغيير وبعده ووسومًا غير معروفة وأسماء بديلة ملتبسة ووسومًا ديناميكية وأمثلةً عُثر عليها في التعليقات أو كتل الأكواد أو نطاقات <pre> أو <code>.
يتعامل الماسح مع الوسوم المقترنة والمتداخلة وذاتية الإغلاق، بما فيها الوسوم الحرفية داخل سلاسل PHP. ويحافظ على السمات ولا يغيّر سوى أسماء الوسوم. تُدرج التعليقات وعينات الأكواد في التقرير فقط. تُتجاهل العناصر المخصصة غير المرتبطة. يُمنع تطبيق الترحيل ما دامت هناك حالات غير معروفة أو ملتبسة أو ديناميكية، إلا إذا مرّر المستدعي --allow-unresolved عمدًا.
عند تشغيل الأمر مجددًا على المخرجات المعتمدة، لن يُجري أي تغييرات.
راجع الترحيل لمعرفة سبب اعتماد الصيغة المعتمدة وما الذي تحلّه.
إزالة التثبيت
wp bs teardown
يحذف أحداث cron وحالة العرض المسبق الثابت التي يملكها التثبيت: إدخال الموقع الحالي في خريطة التقديم المبكر، وإضافةً إلى إضافة advanced-cache.php المشتركة وتعريف WP_CACHE عند إزالة آخر إدخال مملوك. تُستخدم هذه الميزة لإزالة التثبيت بسلاسة في التثبيتات التي لا تتضمن خطافًا لإلغاء تنشيط الإضافة، مثل الإعدادات المجمعة عبر Composer. وتُترك ملفات الإعداد دون تغيير.