PHPStan
يضيف امتداد blockstudio/phpstan التحليل الثابت إلى مشاريع Blockstudio. ويتحقق أثناء التحليل من قوالب الكتل وملفات المخططات ومسارات الإعدادات وأسماء الخطافات، لاكتشاف الأخطاء قبل وصولها إلى وقت التشغيل.
التثبيت
composer require --dev blockstudio/phpstan
يتطلب فحص أنواع القوالب الموسّع والتحقق من وسوم الكتل في الإصدار 7.7 استخدام blockstudio/phpstan بالإصدار 0.1.9 أو أحدث وPHPStan بالإصدار 2.1.47 أو أحدث. حدّث الحزمة بصورة منفصلة عن الإضافة:
composer require --dev blockstudio/phpstan:^0.1.9
يكتشف PHPStan الامتداد تلقائيًا عبر أداة تثبيت الامتدادات. لا حاجة إلى إعداد يدوي.
ما الذي يفحصه
الوصول إلى حقول القالب
عندما يكون ملف PHP بجوار block.json، يتحقق الامتداد من كل عملية وصول إلى $a['key'] وفق السمات المعلنة للكتلة.
<?php
echo $a['title']; // OK
echo $a['subtitle']; // OK
echo $a['typo']; // Error: Field "typo" does not exist in block.json
يعرف الامتداد أن Blockstudio يعرّف $a و$attributes و$b و$block و$c و$context و$content و$isEditor و$isPreview ومتغيرات الجزيرة قبل تضمين قالب، لذا لا يُبلّغ عن قراءات مباشرة مثل $a['title'] على أنها قد تكون غير معرّفة، ويُستنتج نوع $a من block.json المجاور للقالب. ويحافظ الشكل على بنيته عند تضييق النوع، لذا تحتفظ $a['label'] ?? '' وisset( $a['cta']['target'] ) و$a['cta']['title'] !== null بأنواع الحقول المعلنة؛ أما القالب الذي يسند قيمة إلى $a نفسه فيحتفظ بالنوع الذي أسنده. لا تضف كتلة توثيق /** @var array<string, mixed> $a */، لأنها تستبدل ذلك الشكل بمصفوفة مفتوحة.
تتبع مفاتيح الحقول قواعد التسطيح وقت التشغيل في Blockstudio. تُعدّ حاويات tabs وgroup المجهولة الهوية التي لا تحتوي على id عناصر تنسيقية فقط، لذا تبقى حقولها الفرعية ضمن نطاق الحقل الأب. وتضيف المجموعة ذات الاسم معرّفها إلى بادئة مفاتيح الحقول الفرعية:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
الحقول المخصصة القابلة لإعادة الاستخدام
تُوسّع مراجع custom/* المستندة إلى ملفات قبل التحقق من مفاتيح القوالب وبُنى المصفوفات. يقرأ الامتداد field.json المطابق ويطبّق قواعد idStructure وoverrides والمراجع المتداخلة والمجموعات وعلامات التبويب والمكررات نفسها التي يطبقها Blockstudio:
{
"name": "mytheme/hero",
"attributes": [
{ "id": "heading", "type": "text" },
{ "id": "description", "type": "textarea" }
]
}
{
"blockstudio": {
"attributes": [
{
"type": "custom/mytheme/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "id": "title" }
}
}
]
}
}
مفاتيح القوالب الناتجة هي title وhero_description. ويُتعرّف عليها في PHP وTwig وBlade ووسوم الكتل وبُنى السمات المستنتجة.
تؤدي التعريفات المستندة إلى ملفات، إذا كانت مفقودة أو ملتبسة أو غير صالحة أو دائرية، إلى خطأ محدد في blockstudio.customField.*. وتُتخطى عمليات التحقق من المفاتيح التابعة لهذه الكتلة، كيلا يؤدي تعريف واحد لم يُحسم إلى سلسلة أخرى من أخطاء الحقول المجهولة الزائفة.
لا يمكن للتحليل الثابت استنتاج التعريفات المسجلة وقت التشغيل فقط عبر المرشح blockstudio/fields PHP. استخدم تعريف field.json عندما يلزم أن يضيف الحقل مفاتيح قوالب تخضع للتحقق الثابت.
الوصول إلى قوالب Twig
تُفحص قوالب Twig تلقائيًا. لا حاجة إلى تعليقات توضيحية.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
الوصول إلى قوالب Blade
تُفحص قوالب Blade بالطريقة نفسها.
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p> {{-- Error --}}
التحقق من وسوم الكتل
يُتحقق من وسوم الكتل في المواضع التي يقرأها فيها Blockstudio: وسوم <bs:> و<block>، ووسوم البادئة المُعدّة في blockTags.prefixes (مثل <acme-card>، التي تُحلّ وفق ترتيب النطاقات كما في وقت التشغيل)، والوسوم البديلة، في قوالب الكتل بـPHP وTwig وBlade وفي تخطيطات الصفحات. وتُفحص أيضًا مصادر الصفحات ضمن pages/ (index.php وindex.html وindex.twig وindex.blade.php)، بما فيها عناصر HTML التي يربطها المشروع بالكتل. وتكون كتل UI المضمنة معروفة عند تفعيل ui.enabled.
<bs:mytheme-hero title="Hello" />
<!-- OK -->
<bs:mytheme-nonexistent />
<!-- Error: unknown block -->
<bs:mytheme-hero title="Hi" badattr="" />
<!-- Error: unknown attribute -->
<bs:mytheme-hero class="wide" />
<!-- Error: class is dropped unless the block declares a class field -->
<bs:mytheme-hero id="intro" aria-label="Intro" data-x="1" />
<!-- OK: forwarded to the root element -->
<block name="core/separator" />
<!-- OK (core blocks always valid) -->
يُقبل الإسناد عندما تعلنه الكتلة كحقل (بما في ذلك الحقول المخصصة والحقول التي يمرّرها حقل ذو نوع كتلة ضمن idStructure)، أو عندما يمرّره Blockstudio إلى العنصر الجذر للكتلة: data-* وaria-* وid وstyle وrole وtitle وlang وdir وhidden وtabindex. وفي القوالب، يمرّ كل إسناد html-*؛ أما في مصادر الصفحات، فلا تسمّي بادئة html- سوى أحد الإسنادات التي يجري تمريرها. ويُبلّغ عن أي شيء آخر، ولا سيما class غير المعلن، لأن Blockstudio يخزّنه ولا يعرضه مطلقًا.
يسجل وقت التشغيل تعيينات العناصر والوسوم البديلة في مرشحات PHP، التي لا يستطيع التحليل الثابت تقييمها؛ لذلك يقرأها التحليل من blockstudio.json. ويفحص scanPhp أيضًا الوسوم في ملفات PHP الأخرى للمشروع، مثل ترميز المكونات في الوحدات، من دون الإبلاغ عن كتل مجهولة فيها:
{
"phpstan": {
"blockTags": {
"elements": {
"section": "theme/section",
"h2": "theme/heading",
"div": [
{ "attribute": "width", "block": "theme/row" },
"theme/div"
]
},
"aliases": { "theme-button": "bsui/button" },
"scanPhp": true
}
}
}
يُعيّن العنصر إلى اسم كتلة أو إلى قواعد تُجرّب بالترتيب: تفوز أول قاعدة تحمل صفتها على العنصر، أما اسم الكتلة المجرد فيطابق دائمًا. وتحتفظ العناصر التي لا يعيّنها المشروع بكتلتها الأساسية ولا تخضع للفحص. تستخدم التشخيصات blockstudio.blockTag.unknown وblockstudio.blockTag.attribute وblockstudio.blockTag.class.
تحديد أنواع سجلات قاعدة البيانات
يعيد Db::get() مثيلًا محدد النوع استنادًا إلى مخطط db.php. ويُستنتج شكل السجلات تلقائيًا.
return [
'storage' => 'table',
'fields' => [
'email' => ['type' => 'string', 'required' => true],
'name' => ['type' => 'string'],
],
];
$db = Db::get('mytheme/subscribers');
$record = $db->create(['email' => 'a@b.com']);
echo $record['email']; // string
echo $record['name']; // string|null (optional field)
echo $record['typo']; // Error: Offset 'typo' does not exist
الحقول المطلوبة لا تقبل القيمة الخالية. والحقول الاختيارية هي type|null. ويكون الحقل id (int) موجودًا دائمًا. وينطبق تحديد الأنواع نفسه على صياغة البناء الأصلية في PHP لكل من Blockstudio\\Db\\Schema وBlockstudio\\Db\\Field.
التحقق من مسارات الإعدادات
تُفحص مسارات Settings::get() وفق مخطط الإعدادات المعروف.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
التحقق من أسماء الخطافات
يُتحقق من أسماء مرشحات Blockstudio وخطافات الإجراءات.
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // Error: Did you mean "blockstudio/render"?
يُسمح دائمًا بخطافات الإعدادات الديناميكية مثل blockstudio/settings/tailwind/enabled. ويُتجاهل ما عدا ذلك من خطافات لا تخص blockstudio.
التحقق من المخططات
يتحقق الامتداد من كل ملف مخطط Blockstudio في المشروع.
block.json:
- حقل
nameمفقود - الحقل
typeمفقود idمفقود في حقول القيم التي تتطلبه- أنواع الحقول غير المعروفة
- خصائص حقول لا يقبلها نوع الحقل، مثل
"translat"بدلًا من"translate"، مع اقتراح أقرب خاصية معروفة select/radio/checkboxمن دونoptionsأوpopulate- معرّفات حقول مكررة
- حقل
tabsداخل مكرر، مباشرة أو داخل مجموعة لا تحتوي علىid - تعريفات
pluginDependenciesغير صالحة
يمكن للحقول الحاوية مثل group وtabs، وكذلك مراجع الحقول custom/*، إغفال id إذا كان دورها يقتصر على توسيع حقول أخرى أو إحاطتها.
تُفحَص خصائص الحقول بمقارنتها بالخصائص التي يعرّفها schemas/block.json لكل نوع حقل مضمّن، وبالخصائص التي يقبلها كل حقل. الخصائص الخاصة بالـ Wrapper في مراجع custom/* وأنواع الحقول ذات المساحات الاسمية المحددة في المشروع لا يشملها هذا الفحص. ويظل التحقق الحالي من أنواع الحقول والمراجع المخصصة ساريًا. المعرّفات هي blockstudio.blockJson.property وblockstudio.fieldJson.property.
يفحص هذا أسماء الخصائص، لا قيمها فحسب: الخاصية minimized صالحة في حقل مكرّر، لكن يُبلّغ عنها في حقل نصي. يظل سلوك الإضافة وقت التشغيل دون تغيير. إذا كان المشروع يضيف عمدًا بيانات وصفية خاصة به إلى الحقول المضمّنة، فاكتم هذه النتائج وحدها دون تعطيل فحوص البنية الأخرى:
parameters:
ignoreErrors:
- identifier: blockstudio.blockJson.property
- identifier: blockstudio.fieldJson.property
تظل الحقول المضمّنة داخل field.json القابل لإعادة الاستخدام خاضعة للفحص، حتى عندما يكون لمرجع custom/* خيارات Wrapper خاصة به. ملفات الامتدادات خارج نطاق تشخيصات أسماء الخصائص هذه؛ وتظل قواعد set الخاصة بالامتدادات صالحة.
field.json (حقول مخصصة قابلة لإعادة الاستخدام):
- غياب
name - غياب
attributesأو خلوّه - كائنات سمات غير صالحة أو غياب
typeللحقل - غياب
idفي حقول القيم التي تتطلبه - أنواع حقول غير معروفة
- خصائص لا يقبلها نوع الحقل
- حقل
tabsداخل حقل مكرّر، مباشرةً أو ضمن مجموعة لا تحتوي علىid - مراجع
custom/*متداخلة مفقودة أو ملتبسة أو غير صالحة أو دورية
امتداد JSON (امتدادات الكتل في extensions/):
nameمفقود (الكتلة المستهدفة)- مفتاح
blockstudioمفقود - مفتاح
blockstudio.extendمفقود
page.json (الصفحات القائمة على الملفات):
titleمفقودslugمفقود- قيم
postStatusغير صالحة
db.php:
- مصفوفة
fieldsمفقودة - أنواع حقول غير صالحة
- يدعم كلًا من المصفوفات القديمة و
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Field
rpc.php:
- طرق HTTP غير صالحة
- قيمة
publicخاطئة (يجب أن تكونtrueأوfalseأو'open') - يدعم كلًا من المصفوفات القديمة وإرجاع الكائنات ذات السمات
cron.php:
scheduleمفقود في المهام المُعدّةcallbackمفقود في المهام المُعدّة- يدعم كلًا من المصفوفات القديمة وإرجاع الكائنات ذات السمات
blockstudio.json:
- قيم منطقية مختصرة مثل
"tailwind": true(يجب استخدام تنسيق الكائن المتداخل{"enabled": true, "config": ""})
الإعداد
يكتشف الامتداد ملفات Blockstudio في المشروع الخاضع للتحليل افتراضيًا. إذا كان المشروع يستخدم كتلًا أو حقولًا قابلة لإعادة الاستخدام من مكتبة خارج جذر المشروع، فأضف مسار المكتبة إلى blockstudioScanRoots. ويُفحص المسار بحثًا عن تعريفات block.json وfield.json، ما يتيح التحقق من وسوم الكتل الخارجية وحقولها المخصصة معًا.
parameters:
blockstudioScanRoots:
- vendor/acme/block-library/blockstudio
لتجاهل الملفات، استخدم إعداد excludePaths القياسي في PHPStan.
إعدادات التحليل المسبقة
يظل الامتداد الذي يُكتشف تلقائيًا أساسًا آمنًا للتوافق. ويضيف Blockstudio 7.6 طبقات اختيارية دون تغيير المشاريع الحالية:
| الإعداد المسبق | السلوك |
|---|---|
base.neon |
تحليل المخططات والقوالب والخطافات والإعدادات وAPI الحالي. |
theme.neon |
الأساس، بالإضافة إلى جذور قوالب WordPress وعناوين الأنماط وأصول Blockstudio وحصر نطاق المحددات والقيم الافتراضية للحقول وحدود الحقول المكررة. |
extreme-theme.neon |
إعداد القالب، بالإضافة إلى max في PHPStan وPHP غير الآمن والتحقق من تهريب المخرجات وTailwind وJavaScript وفحوصات Interactivity API. |
wordpress-render.neon |
إعداد القالب الأقصى، بالإضافة إلى اختبار عرض مباشر لـWordPress يقدّمه المستدعي. |
لا يؤدي تثبيت blockstudio/phpstan إلا إلى تفعيل الامتداد الأساسي. أدرج طبقة اختيارية في إعداد PHPStan الحالي:
includes:
- vendor/blockstudio/phpstan/extreme-theme.neon
parameters:
blockstudioThemeRoots:
- .
blockstudioThemeExcludePaths:
- fixtures/**
blockstudioThemeMaxFiles: 10000
blockstudioExtremeJavaScript: true
blockstudioExtremeTailwind: true
يتحكم blockstudioThemeExcludePaths في ماسح القوالب. ويتحكم إعداد excludePaths القياسي في PHPStan بصورة مستقلة في تحليل PHP.
يضبط الإعداد phpstan.excludePaths للأمر القياسي في blockstudio.json (وخيار --exclude الخاص به) الطبقتين معًا. وتُحل الأنماط النسبية بالنسبة إلى كل جذر مُعدّ، لذا فإن إدخالات مثل vendor/** تقيّد تحليل PHPStan وكذلك فحص مشروع Blockstudio.
يستثني نمط يحدد دليلًا واحدًا، مثل _dist/** أو node_modules/**، ذلك الدليل أينما ظهر، لا بجوار جذر القالب فقط. أما النمط الذي يحتوي على شرطة مائلة، مثل assets/*/docs/**، فيظل مرتبطًا بالجذر. وتوجد أصول الكتل المُنشأة في دليل _dist داخل كل كتلة، لذا فإن صيغة الدليل الواحد هي التي تُبقي المخرجات المترجمة خارج نطاق التحليل.
الأمر القياسي
تثبّت الحزمة vendor/bin/blockstudio-phpstan بوصفه الملف التنفيذي للتحليل. ويشغّل إعداد base المسبق ما لم يختر المشروع إعدادًا آخر، لذا لا يؤدي تثبيت الحزمة وحده إلى تفعيل طبقتي القالب أو القالب الأقصى:
vendor/bin/blockstudio-phpstan --root . -- --no-progress
تتضمن الإعدادات المسبقة الامتداد بنفسها. لا تضف phpstan/extension-installer إلى مشروع يشغّل الأمر القياسي: عند وجود أداة التثبيت، يُحمّل extension.neon مرتين ويتوقف PHPStan مع الرسالة “This file is included multiple times” قبل تحليل أي شيء.
يضبط الأمر حد ذاكرة PHPStan افتراضيًا على 1G، كيلا ترث مشاريع WordPress التي يديرها Composer حدًا شائعًا قدره 128M CLI. مرّر خيار PHPStan صريحًا بعد -- لتجاوزه، مثل -- --memory-limit=512M --no-progress.
اعتماد التحليل في مشروع قائم
غالبًا ما يُظهر المشروع الذي لم يخضع للتحليل من قبل نتائج عند تشغيله أول مرة. بدلًا من خفض مستوى الإعداد المسبق، أنشئ خط أساس لـPHPStan ووجّه phpstan.configuration إلى إعداد المشروع الذي يتضمنه. عندئذٍ تخضع الشيفرة الجديدة للإعداد المسبق الكامل، بينما تظل النتائج المسجلة خارج الطريق:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
أبقِ السطر level لإعدادَي base وtheme المسبقين. لا يضبط الأمر المعتمد المستوى max لهما إلا عند عدم تضمين إعدادات المشروع، ومن دون تحديد مستوى يتوقف PHPStan مع الرسالة “No rules detected”. يضبط الإعداد المسبق extreme-theme المستوى max بنفسه.
تُحل المسارات النسبية انطلاقًا من blockstudio.json. يلتقط الأمر المعتمد وخطاف الالتزام المُدار الملفَ، لذا يمنع الخطاف ظهور نتائج جديدة من دون اشتراط معالجة النتائج المتراكمة أولًا.
احتفظ بالإعدادات الافتراضية العامة للأمر على مستوى المشروع في blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
تُحل الجذور النسبية انطلاقًا من الملف الذي يعرّفها. تستبدل قيم CLI الصريحة قيم JSON المقابلة. مرّر --blockstudio-json path/to/project.json لاستخدام مصدر إعدادات بديل. يؤدي وجود JSON غير صالح أو مفاتيح phpstan غير مدعومة أو قيم غير صالحة أو غياب مصدر صريح مطلوب إلى فشل حتمي برمز الخروج 2.
اختر إعدادًا مسبقًا آخر، أو أدرج إعدادات المشروع، أو أضف جذورًا واستثناءات قابلة للتكرار، أو اطلب من PHPStan JSON:
vendor/bin/blockstudio-phpstan \
--preset theme \
--configuration phpstan.neon \
--root . \
--exclude 'fixtures/**' \
--max-files 10000 \
--error-format json \
-- --no-progress
يجمع الغلاف الإعدادات في دليل النظام المؤقت ويحذفه عند الخروج. ولا يكتب أبدًا الإعدادات المُنشأة أو الخطوط الأساسية أو الخطافات أو ذاكرات التخزين المؤقت داخل المشروع الخاضع للتحليل. ومع ذلك، يمكن للجهات المستدعية ضبط ذاكرة PHPStan المؤقتة المعتادة صراحةً.
عقد رموز الخروج هو:
0عند اجتياز التحليل1عند إصدار PHPStan تشخيصات2عند استخدام غير صالح أو إعدادات غير صالحة أو فشل تنفيذ العملية
خطاف الالتزام المُدار
لجعل تحليل السمة القصوى شرطًا لالتزام المستودع، فعّل الخطاف الذي تديره Blockstudio في blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": [],
"maxFiles": 10000
},
"githooks": {
"commit": true
}
}
زامنه بعد تثبيت التبعيات أو تغيير الإعداد:
vendor/bin/blockstudio-githooks sync
يكتب الأمر خطاف ما قبل الالتزام المُنشأ وسجل الملكية داخل الدليل المشترك لـ Git، ويضبط core.hooksPath على دليل الخطافات المُدارة، ويربط بأمان الخطاف السابق المُعدّ لما قبل الالتزام. وتُحدّث عمليات المزامنة المتكررة الملف المُنشأ فقط، ما يجعل ترقيات الحزمة متكررة بأمان.
اضبط commit على false، أو أزله، أو أزل blockstudio.json، ثم شغّل sync لاستعادة مسار الخطاف المسجّل وحذف الملفات التي تملكها Blockstudio وحدها. ويمكنك أيضًا تشغيل:
vendor/bin/blockstudio-githooks remove
لا تُستبدل الملفات التي يملكها المستخدم ولا تُحذف أبدًا. إذا غيّر أحدهم core.hooksPath بعد تفعيل Blockstudio، فستحافظ عملية الإزالة على الإعداد الأحدث. يدعم الخطاف المُنشأ مستودعات Git المرتبطة والمسارات التي تحتوي على مسافات، إذ يحلّ المستودع النشط وجذر المشروع وقت الالتزام. ويشغّل الأمر المعتمد من ذلك الجذر، لذا يتحكم الكائن phpstan نفسه في التشغيل التفاعلي والالتزامات، من دون تكرار الوسائط المُنشأة.
يشغّل الخطاف vendor/bin/blockstudio-phpstan فقط. لا يشغّل Blockstudio أداة تنسيق، ولا يعيد الخطاف كتابة ملفات المشروع. وتمنع التبعيات المفقودة وإخفاقات التحليل الالتزام مع عرض خطأ يوضح الإجراء المطلوب.
عرض WordPress مباشر
طبقة العرض المباشر صريحة عمدًا. فالجهة المستدعية مسؤولة عن بيئة WordPress وتزوّدها بمصفوفة argv:
vendor/bin/blockstudio-phpstan \
--preset wordpress-render \
--render-command='["wp","eval-file","tools/render-probe.php"]' \
--render-working-directory=. \
--render-timeout=60 \
--root .
يعمل الأمر من دون غلاف، ويجب أن يطبع كائن JSON واحدًا:
{"ok":true}
يمكن للفحص الإبلاغ عن إخفاق محدد:
{
"ok": false,
"message": "Rendered block failed.",
"file": "/absolute/path/to/block.json",
"line": 12
}
تؤدي رموز الخروج غير الصفرية وانتهاء المهلة وJSON غير الصالح وok: false إلى blockstudio.wordpress.render.
يرصد blockstudio.javascript.domContract محدد سمة [data-*] يمرره نص برمجي إلى querySelector() أو querySelectorAll() أو closest() أو matches()، عندما لا تحتوي أي علامة ترميز خاضعة للتحليل على تلك السمة. تشمل العلامات كل ملف من نوع PHP وTwig وBlade وHTML، وكل مكوّن React و.tsx و.jsx ضمن الجذور الخاضعة للتحليل، بعد استبعاد المسارات المستثناة. تُحلّل المكونات: تُحتسب أسماء السمات JSX، وكذلك مفاتيح السلاسل النصية في الكائنات الحرفية، لذا فإن نشر كائن سمات على عنصر يفي بالمحدد، بينما لا تفعل أسماء الفئات وقيم السمات الأخرى ذلك.
تقرأ فحوص Interactivity API المكونات React نفسها. وتُعد مساحة الأسماء data-wp-interactive على العنصر JSX مرجعًا إلى قالب من أجل blockstudio.interactivity.orphan، كما تُحلّ توجيهات data-wp-* الموجودة داخلها باستخدام أقرب مساحة أسماء حاوية، أو باستخدام بادئة namespace:: في القيمة. يجب أن تشير التوجيهات ذات القيمة النصية الثابتة، المكتوبة كسمة JSX أو كمفتاح نصي في كائن سمات، إلى معالجات ومسارات مخزن موجودة (blockstudio.interactivity.handler، blockstudio.interactivity.binding)، ويجب ألا تعدّل شيفرة المخزن السمات والفئات التي تربطها (blockstudio.interactivity.derivedState). يقوم React بتهريب قيم السمات، لذا لا يُبلّغ عن data-wp-context في مكوّن، ولا تُفحص القيم الديناميكية. تنتمي مساحات الأسماء ضمن bsui/ إلى كتل UI المضمّنة، التي تأتي مخازنها مع Blockstudio خارج الجذور الخاضعة للتحليل، لذا فهي ليست يتيمة مطلقًا.
معرّفات التشخيص
تحتفظ تشخيصات الإعدادات المسبقة الجديدة بمعرّفات blockstudio.* ثابتة:
- بنية السمة:
blockstudio.theme.root.missing،blockstudio.theme.style.missing،blockstudio.theme.style.header،blockstudio.theme.scanLimit - الأصول والحقول:
blockstudio.theme.asset.manualEnqueue،blockstudio.theme.asset.selectorScope،blockstudio.theme.asset.missing،blockstudio.field.default،blockstudio.field.repeaterBounds - PHP:
blockstudio.php.forbiddenFunction،blockstudio.wordpress.rawDatabaseWrite،blockstudio.output.unescaped - Tailwind:
blockstudio.tailwind.compilerMissing،blockstudio.tailwind.compile،blockstudio.tailwind.unknownUtility،blockstudio.tailwind.semanticToken - JavaScript:
blockstudio.javascript.syntax،blockstudio.javascript.debugOutput،blockstudio.javascript.bannedApi،blockstudio.javascript.leakedGlobal،blockstudio.javascript.importSpecifier،blockstudio.javascript.rootGuard،blockstudio.javascript.initShape،blockstudio.javascript.domContract،blockstudio.javascript.listenerCleanup،blockstudio.javascript.reducedMotion - التفاعلية:
blockstudio.interactivity.import،blockstudio.interactivity.moduleImport،blockstudio.interactivity.namespace،blockstudio.interactivity.scopedDom،blockstudio.interactivity.derivedState،blockstudio.interactivity.handler،blockstudio.interactivity.binding،blockstudio.interactivity.context،blockstudio.interactivity.orphan
الأداء
يقبل الماسح الأدلة العادية الموجودة على القرص، ويزيل تكرار الجذور، ويتجاوز أشجار التبعيات والبناء وذاكرة التخزين المؤقت، ويخزّن قراءات الملفات في الذاكرة، ويرتب التشخيصات ترتيبًا حتميًا. اجعل الجذور محدودة النطاق، واستثنِ أشجار الاختبارات والملفات المُنشأة، وحدد حدًا لعدد الملفات في المستودعات الكبيرة. يمكن تعطيل JavaScript وTailwind كلٌّ على حدة. ولا يُشغّل العرض المباشر إلا عند اختيار إعداده المسبق.
تُبلّغ تشخيصات السمة وJavaScript وTailwind عبر ذاكرة نتائج PHPStan المؤقتة. بعد تغيير block.json فقط أو أحد البرامج النصية، قد تعرض الذاكرة الدافئة النتيجة السابقة. مرّر --debug بعد -- لتجاوز الذاكرة عند التحقق من هذه التغييرات.
عقد المشروع لوكلاء البرمجة
تثبّت الحزمة ملفًا تنفيذيًا ثالثًا هو vendor/bin/blockstudio-agents. وينشئ ملف AGENTS.md يصف المشروع الذي يعمل فيه، وهو ما يحتاج إليه وكيل البرمجة قبل أن يغيّر أي شيء: ما الذي ينشئه المشروع، وميزات Blockstudio المفعّلة، وما الذي سيرفضه التحليل، والأوامر المنطبقة.
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/project/AGENTS.md
لا يوجد في المخرجات ما يستند إلى قالب ثابت. فكل سطر مشتق من أحد ثلاثة مصادر:
- ملفات المشروع نفسه. ينتج عن سمة لها ترويسة
style.cssوكتل وصفحات مستندة إلى ملفات مستند مختلف عن الإضافة التي تسجّل كتلًا فقط. وتستند الأعداد والأدلة ومساحات أسماء الكتل ولغات القوالب إلى ما عثر عليه الماسح فعلًا، باستخدام الجذور والاستثناءات نفسها التي يستخدمها التحليل. blockstudio.json. لا تُوصف إلا الميزات المفعّلة، مع قيمها المضبوطة: بادئات وسوم الكتل ومساحات الأسماء التي تُحل من خلالها، وTailwind، وUI المضمّن، وإعادة ضبط أصول المحرر، ومسار ذاكرة التخزين المؤقت، وملف الأداء، والعرض المسبق الثابت ومساراته الديناميكية، والإعدادات الافتراضية للسمة، ومزامنة المحتوى، وخطاف الالتزام.phpstan.presetالمحدد. يُقرأ قسم الصحة من ملفات الإعداد المسبق نفسها، طبقةً بعد طبقة، ليعرض القواعد التي يسجلها ذلك الإعداد المسبق بالضبط. عندbase، يصف قواعد المخطط والقالب والخطاف والإعدادات. وعندextreme-theme، يصف أيضًا قواعد بنية السمة، ورايات PHPStan الصارمة، وPHP غير الآمن، وهروب المخرجات، وTailwind، وJavaScript. إذا أضيفت قاعدة إلى إعداد مسبق، يتغير المستند المُنشأ تبعًا لذلك.
يتبع قسم الأوامر المبدأ نفسه. يظهر wp bs prerender status عند تفعيل العرض المسبق الثابت، وvendor/bin/blockstudio-githooks sync عند ضبط githooks.commit، وwp bs db schemas عندما يحتوي المشروع فعليًا على db.php.
| الخيار | السلوك |
|---|---|
--root <path> |
جذر المشروع (الافتراضي: الدليل الحالي) |
--config <path> |
مسار blockstudio.json (الافتراضي: <root>/blockstudio.json) |
--output <path> |
مسار العقد (الافتراضي: <root>/AGENTS.md) |
--stdout |
طباعة العقد بدلًا من كتابته |
--check |
الخروج بالرمز 1 إذا لم يعد العقد الموجود على القرص حديثًا |
--force |
استبدال ملف لا يملكه Blockstudio |
يجعل --check العقد شرطًا في CI، كما يجعل خطاف الالتزام التحليل شرطًا:
vendor/bin/blockstudio-agents --check
الملكية
يحمل الملف المُنشأ نوع العلامة نفسه الموجود في خطاف الالتزام المُدار، وتسري القاعدة نفسها: لا يستبدل Blockstudio أبدًا ملفًا لم يكتبه. ويُرفض AGENTS.md الذي يسبق الأمر، أو الذي كتبه أحد المؤلفين يدويًا، برمز الخروج 2 ويُترك دون تغيير حتى تمرير --force.
إعادة الإنشاء آمنة. ينتهي الملف بمنطقة ملاحظات، وتُحفظ البايتات بين علامتيها في كل عملية إعادة إنشاء:
## Project notes
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
رمز الخروج هو 0 عند كتابة العقد أو كونه حديثًا أو طباعته، و1 عندما يعثر --check على عقد قديم، و2 عند أخطاء الاستخدام أو الإعداد أو نظام الملفات.
أشكال أنواع الحقول
تعيّن الإضافة كل نوع حقل من Blockstudio إلى نوع ملموس في PHP:
| نوع الحقل | نوع PHP |
|---|---|
text، textarea، richtext، wysiwyg، code |
string |
date، datetime، classes، html-tag، unit، gradient |
string |
number، range |
int|float |
toggle |
bool |
select، radio، checkbox (مفرد) |
string|int |
select، checkbox (متعدد) |
list<string|int> |
color |
array{value: string, opacity: float|null} |
link |
array{url: string, title: string|null, target: string|null, opensInNewTab: bool|null} |
icon |
array{set: string, subSet: string, icon: string} |
files (مفرد) |
array{id: int, url: string, alt: string|null, mime_type: string|null} |
files (متعدد) |
list<array{id: int, url: string, ...}> |
group |
تستخدم المجموعات المسماة بادئات underscore؛ وتُسطّح المجموعات مجهولة الاسم ضمن نطاق العنصر الأب |
repeater |
list<array{...child fields...}> |
tabs |
تُسطّح ضمن نطاق العنصر الأب |
ملفات التعريف البديلة لـ API
تتضمن الإضافة ملفات تعريف بديلة لواجهة API العامة كاملةً في Blockstudio:
bs_render_block(),bs_block_values(),bs_get_group(),bs_get_scoped_class(),bs_db_form(),bs_is_editor(),bs_is_preview(),bs_is_buffering(),bs_strip_render_markers()Db::get(),Db::create(),Db::list(),Db::get_record(),Db::update(),Db::delete()Settings::get(),Settings::get_all()Field_Registry::instance(),Field_Registry::all(),Field_Registry::get()Build::blocks(),Build::extensions(),Build::get_build_dir()
توفّر هذه الملفات الإكمال التلقائي وفحص الأنواع من دون الحاجة إلى وجود مصدر إضافة Blockstudio على جهازك.
المتطلبات
- PHP 8.2+
- PHPStan 2.1.47+
phpstan/extension-installer(موصى به للاكتشاف التلقائي)
تثبّت الحزمة موفّر التوافق مع BC Math تلقائيًا. لذا فإن ext-bcmath الأصلي اختياري، حتى عند إنشاء سمات جديدة تفعّل فحوص JavaScript عبر إعداد السمة المسبق أو الإعداد الأقصى.