قوالب مُتحقَّق منها باستخدام PHPStan وAGENTS.md مُنشأ
كتلة Blockstudio عبارة عن ملفين يجب أن يتوافقا. يعرّف block.json الحقول، ويقرأها القالب على هيئة $a['id']. لا يوجد ما يمنع القالب وقت التشغيل من قراءة مفتاح أُعيدت تسميته أو لم يُعرّف قط أو كُتب خطأً. بل يعرض سلسلة فارغة فحسب، ولا يظهر الخطأ إلا حين يلاحظ أحدهم عنوانًا فارغًا على صفحة منشورة. وينطبق الأمر نفسه على تهريب المخرجات: يعمل echo غير المُهرب كما ينبغي إلى أن تحتوي قيمة أحد الحقول على ترميز.
تنقل حزمة blockstudio/phpstan المشكلتين إلى مرحلة التحليل. فهي تقرأ ملفات block.json، وتستنتج أنواع $a منها، وتبلغ عن قراءات القوالب غير المطابقة. تضيف إعداداتها المسبقة الاختيارية قواعد بنية السمة والتهريب وفحوصات JavaScript وTailwind. وتأتي الحزمة نفسها مع أداتين مساعدتين: خطاف مُدار قبل الإيداع يشغّل التحليل، ومولّد يكتب AGENTS.md يصف مشروعك لوكلاء البرمجة.
يبني هذا الدليل سمة صغيرة، ويتعمّد إفساد أحد قوالبها، ويقرأ مخرجات التحليل، ثم يصلحه، وبعدها يضبط بوابة الإيداع وعقد الوكيل.
إعداد السمة
ابدأ بمجلد سمة يحتوي على رأس style.css وcomposer.json وكتلة واحدة:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
ثبّت الحزمة اعتمادًا للتطوير:
composer require --dev blockstudio/phpstan
تُثبّت معها PHPStan وتعريفات WordPress من szepeviktor/phpstan-wordpress، وتثبّت ثلاثة ملفات تنفيذية في vendor/bin: blockstudio-phpstan وblockstudio-githooks وblockstudio-agents.
بعد ذلك حدّد ما سيشغّله التحليل. توجد الإعدادات الافتراضية على مستوى المشروع في كائن phpstan ضمن blockstudio.json، بحيث تستخدم عمليات التشغيل التفاعلية وCI وخطاف الإيداع الإعدادات نفسها:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
يُعد extreme-theme الأكثر صرامة بين الإعدادات الثلاثة المسبقة الثابتة. يوضح الجدول أدناه ما يضيفه كل منها. يُبقي excludePaths ملفات Composer نفسها خارج فحص Blockstudio وخارج تحليل PHP.
إفساد قالب عمدًا
يعرّف قالب البطل حقلًا واحدًا:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
يقرأ القالب ذلك الحقل على نحو صحيح، ثم يقرأ subtitle لم تعرّفه الكتلة مطلقًا ويطبعه دون تهريب:
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
في المحرر والواجهة الأمامية، يعرض هذا فقرة فارغة ولا يظهر أي خطأ. شغّل التحليل بدلًا من ذلك:
vendor/bin/blockstudio-phpstan -- --no-progress
------ -------------------------------------------------------------------
Line blockstudio/hero/index.php
------ -------------------------------------------------------------------
2 Variable $a might not be defined.
🪪 variable.undefined
3 Dynamic Blockstudio attributes must be escaped before output.
🪪 blockstudio.output.unescaped
3 Field "subtitle" does not exist in block.json (block: acme/hero).
🪪 blockstudio.field
3 Offset 'subtitle' does not exist on array{heading: string}.
🪪 offsetAccess.notFound
3 Parameter #1 (mixed) of echo cannot be converted to string.
🪪 echo.nonString
3 Variable $a might not be defined.
🪪 variable.undefined
------ -------------------------------------------------------------------
[ERROR] Found 6 errors
ينتهي الأمر بخروج الأمر بالرمز 1. اقرأ التشخيصات بدءًا بالأكثر تحديدًا:
blockstudio.fieldهي قاعدة القالب. عثرت علىblock.jsonبجانب القالب، وحلّت حقوله، ووجدت أنsubtitleليس من بينها.- توصّل
offsetAccess.notFound، وهو PHPStan نفسه، إلى النتيجة ذاتها لأن الإضافة تمنح$aبنية محددة هيarray{heading: string}، مستنتجة منblock.json. يقابل كل نوع حقل نوعًا من PHP:textهوstring، وtoggleهوbool، والمكرّر مصفوفة من بُنى الصفوف. - يأتي
blockstudio.output.unescapedمن طبقةextreme-theme. يجب تمرير قيم السمات المطبوعة عبر دالة تهريب مثلesc_html()أوesc_attr()أوesc_url()أوwp_kses_post(). - ينتج
echo.nonStringعن المفتاح غير المعروف: فالإزاحة غير الموجودة ليس لها نوع سلسلة يمكن طباعته. - يظهر
variable.undefinedلأن PHPStan يرى ملف قالب لا دالة العرض التي تعرّف$aقبل تضمينه. يتناول قسم الإصلاح ذلك.
الإصلاح
قرّر ما إذا كان subtitle حقلًا فعليًا. هو كذلك هنا، لذا عرّفه مع default لأن طبقة السمة تتطلبه لكل حقل:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" },
{ "id": "subtitle", "type": "textarea", "label": "Subtitle", "default": "" }
]
}
}
اهرب المخرج، وعرّف $a بالبنية التي تستنتجها الإضافة:
<?php
/** @var array{heading: string, subtitle: string} $a */
?>
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo esc_html( $a['subtitle'] ); ?></p>
</section>
vendor/bin/blockstudio-phpstan -- --no-progress
[OK] No errors
اكتب التعليق التوضيحي بالبنية الدقيقة. يشغّل الأمر الأساسي PHPStan بالمستوى max، حيث يُرفض @var array<string, mixed> $a الأقل تحديدًا مع varTag.nativeType (“وسم PHPDoc @var بنوع array<string, mixed> ليس نوعًا فرعيًا من النوع الأصلي array{heading: string, subtitle: string}”). وفي الإصدار 7.6 يوسّع أيضًا كل حقل إلى mixed، لذا تُصدر كل استدعاءة لـ esc_html() تشخيص argument.type. تطبع رسالة varTag.nativeType البنية المستنتجة، لذا فهي أسرع طريقة لمعرفة التعليق التوضيحي المطلوب نسخه.
يتعامل Blockstudio 7.7 مع $a بوصفه معرّفًا داخل قوالب الكتل، لذا تختفي تشخيصات variable.undefined ويصبح التعليق التوضيحي اختياريًا. عند استخدام 7.7، يُصدر القالب المعطوب أعلاه أربعة أخطاء بدلًا من ستة، وينجح القالب المُصلح دون سطر @var.
اختيار إعداد مسبق
لا يؤدي تثبيت الحزمة إلا إلى تفعيل الإضافة الأساسية. يشغّل الأمر الأساسي base ما لم يختر المشروع إعدادًا مسبقًا آخر، لذا فإن إضافة الاعتماد لا تفعّل الطبقات الأشد صرامة بحد ذاتها.
| الإعداد المسبق | ما يضيفه |
|---|---|
base |
الوصول إلى حقول القوالب في PHP وTwig وBlade، وفحوصات وسوم الكتل، والتحقق من مخطط block.json وfield.json وpage.json وامتداد JSON وdb.php وrpc.php وcron.php ومسارات Settings::get() وأسماء خطافات blockstudio/*. |
theme |
الأساسي مع جذور السمات ورؤوس style.css، وأصول مُعرّفة في block.json بدلًا من إضافتها يدويًا، ونطاق %selector% في style.scss، والقيم الافتراضية للحقول، وحدود المكرّرات. |
extreme-theme |
السمة مع علامات PHPStan الصارمة، ورفض استدعاءات الصدفة وeval()، وعمليات كتابة $wpdb الخام، وتهريب المخرجات، وTailwind وJavaScript وفحوصات API التفاعلية. |
wordpress-render |
السمة القصوى مع فحص عرض مباشر توفّره على هيئة أمر. |
عندما لا يتضمن إعداد المشروع، يشغّل الأمر الأساسي base وtheme عند مستوى PHPStan max أيضًا؛ أما extreme-theme فيضبط max بنفسه. ولكل تشخيص في الإعدادات المسبقة معرّف ثابت من blockstudio.*، مدرج في مرجع PHPStan.
تتجاوز طبقتا السمة والقصوى ملفات PHP. عند وجود حقل يفتقد default وscript.js يسجل في وحدة التحكم، يُصدر الأمر نفسه:
------ -----------------------------------------------------------
Line blockstudio/hero/block.json
------ -----------------------------------------------------------
1 Blockstudio field "subtitle" must define a default value.
🪪 blockstudio.field.default
------ -----------------------------------------------------------
------ ------------------------------------------------------------
Line blockstudio/hero/script.js
------ ------------------------------------------------------------
2 Remove debug output "console.log" from shipped JavaScript.
🪪 blockstudio.javascript.debugOutput
------ ------------------------------------------------------------
تُعرض هذه الفحوصات عبر ذاكرة نتائج PHPStan المؤقتة. بعد تعديل block.json أو نص برمجي فقط، قد تعرض الذاكرة الدافئة نتيجة [OK] No errors للحالة القديمة. مرّر --debug بعد --، ما يتجاوز الذاكرة، قبل الوثوق بنتيجة خضراء للتغييرات التي لا تشمل PHP:
vendor/bin/blockstudio-phpstan -- --no-progress --debug
خيارات الأوامر ورموز الخروج
تحل قيم سطر الأوامر محل قيم blockstudio.json المطابقة لتشغيل واحد. وتعني كلمة «استبدال» الاستبدال فعلًا: يؤدي تمرير أي --exclude إلى إسقاط excludePaths المُعدّ، لذا أعد تمرير vendor/** عند إضافة واحد:
vendor/bin/blockstudio-phpstan \
--preset theme \
--root . \
--exclude 'vendor/**' \
--exclude 'fixtures/**' \
--error-format json \
-- --no-progress
{"totals":{"errors":0,"file_errors":0},"files":{},"errors":[]}
يُمرر كل ما يأتي بعد -- إلى PHPStan. يرفع الغلاف حد ذاكرة PHPStan إلى 1G ما لم تمرر --memory-limit خاصًا بك، ويُنشئ إعداده في مجلد النظام المؤقت، لذلك لا يُنشأ أي ملف مولّد داخل المشروع. يخرج بالرمز 0 عند نجاح التحليل، و1 عند إصدار PHPStan تشخيصات، و2 عند أخطاء الاستخدام أو الإعداد أو التنفيذ.
شغّله عبر الأمر الأساسي بدلًا من إضافة phpstan/extension-installer. تتضمن الإعدادات المسبقة الإضافة أصلًا، ومع وجود المُثبّت يُحمّل extension.neon نفسه مرتين: يتوقف PHPStan برسالة “This file is included multiple times” قبل تحليل أي شيء.
اعتماده في مشروع قائم
غالبًا ما تظهر نتائج عند تحليل مشروع للمرة الأولى. بدلًا من تخفيف الإعداد المسبق، سجّلها في خط أساس لتُطبّق القواعد كاملة على الشيفرة الجديدة:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
ضمّن خط الأساس من إعدادات المشروع وأشِر إليه باستخدام phpstan.configuration:
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
يعرض التشغيل التالي [OK] No errors مع وجود النتائج المسجلة، وسيظل كل ما هو جديد يؤدي إلى الفشل. مع الإعداد المسبق base أو theme، عيّن أيضًا level: max تحت parameters في phpstan.neon: فالأمر الأساسي لا يضبط ذلك المستوى بنفسه إلا عند عدم تضمين إعداد للمشروع.
جعل التحليل شرطًا للإيداع
مع وجود "githooks": { "commit": true } في blockstudio.json، زامن الخطاف المُدار مرة واحدة بعد تثبيت الاعتمادات:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
يكتب الأمر الخطاف داخل مجلد Git نفسه، ويشير core.hooksPath إليه، ويربطه بأي خطاف قبل الإيداع كان مُعدًا من قبل. لا يشغّل الخطاف سوى vendor/bin/blockstudio-phpstan -- --no-progress من جذر المشروع: بلا أداة تنسيق أو إعادة كتابة. يتوقف إيداع القالب المعطوب سابقًا عند التحليل:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
عيّن commit إلى false ثم شغّل sync مجددًا، أو شغّل vendor/bin/blockstudio-githooks remove لاستعادة مسار الخطاف السابق. لا تُحذف إلا الملفات التي كتبها Blockstudio.
إنشاء عقد المشروع
يخبر التحليل الوكيل بما أخطأ فيه بعد وقوعه. أما AGENTS.md فيطلعه مسبقًا: أين توجد الكتل والصفحات، وكيف تصل الحقول إلى القوالب، وما الميزات المفعّلة، وما الذي سيرفضه الإعداد المسبق المحدد. ينشئ blockstudio-agents هذا المستند من المشروع نفسه:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
بالنسبة إلى السمة الواردة في هذا الدليل، يبدأ الملف المُنشأ كما يلي:
# Blockstudio contract for Acme
## Project
- Kind: WordPress theme `Acme`.
- Analysed root: `.`.
- Configuration: `blockstudio.json`.
- Analysis preset: `extreme-theme`.
- Excluded from discovery and analysis: `vendor/**`.
## What this project contains
- Blocks: 1 in `blockstudio`.
- Block namespaces: `acme`.
- Block templates are written in PHP.
يأتي كل سطر من أحد ثلاثة مصادر. توفر ملفات المشروع نوعه وأعداده ومجلداته ونطاقاته الاسمية ولغات القوالب. يوفر blockstudio.json الميزات المفعّلة، لذا يظهر خطاف الإيداع تحت «الميزات المفعّلة» ويظهر vendor/bin/blockstudio-githooks sync تحت «الأوامر» فقط بسبب تعيين githooks.commit. ويوفر الإعداد المسبق المحدد قسم الصحة، المقروء من ملفات الإعداد طبقةً تلو الأخرى:
The `theme` layer adds:
- Every analysed root must exist and carry a `style.css` with a `Theme Name` header.
- Block assets are declared in `block.json`; block code must not call `wp_enqueue_script()` or `wp_enqueue_style()`.
- A block `style.scss` must scope its rules through `%selector%`, and assets referenced by `block.json` must exist.
- Every field must define a `default`, and repeaters must declare non-negative `min` and `max` bounds.
إبقاؤه محدّثًا
يصبح العقد قديمًا عند تغيير الإعدادات. بعد تفعيل Tailwind في blockstudio.json، يكتشف وضع الفحص ذلك:
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
يخرج بالرمز 1، ما يجعله مناسبًا لخطوة CI إلى جانب التحليل. وتضيف إعادة الإنشاء إدخال ميزة «Tailwind CSS» وأمر wp bs tailwind compile.
ملاحظات تبقى بعد إعادة الإنشاء
ينتهي الملف بمنطقة للملاحظات. يُحافَظ على كل ما بين علامتيها حرفيًا في كل مرة يُعاد فيها الإنشاء، لذا ضع فيها معرفة المشروع التي لا يمكن استنتاجها من الملفات:
## Project notes
Everything above is generated. Text between the markers below is preserved when this file is regenerated.
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
لا يستبدل المولّد أبدًا ملفًا لم يكتبه. وإذا شُغّل على AGENTS.md مكتوب يدويًا، فسيرفض ذلك ويخرج بالرمز 2:
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
للاحتفاظ بالنص المكتوب يدويًا، انسخه إلى مكان آخر، وشغّل باستخدام --force، ثم الصقه في منطقة الملاحظات. الخيارات الأخرى هي --root و--config و--output و--stdout، الذي يطبع العقد بدلًا من كتابته.
ما الذي يتغير في Blockstudio 7.7
تحافظ حزمة 7.7 على الأوامر والإعدادات المسبقة ورموز الخروج الموضحة هنا. وظهر اختلافان أثناء إعداد هذا الدليل عليها: لم يعد $a بحاجة إلى تعليق توضيحي، كما ورد في قسم الإصلاح، وأصبح العقد المُنشأ يصف التحقق من وسوم الكتل على نحو أوسع، ليشمل عناصر HTML المرتبطة بكتل في مصادر الصفحات والسمات العامة التي يمكن للوسم تمريرها.
الخطوات التالية
- مرجع PHPStan: كل قاعدة ومعلمة إعداد مسبق وبنية نوع حقل وفحص عرض مباشر ومعرّف تشخيص.
- تكامل الذكاء الاصطناعي: فهرس الوثائق لوكلاء البرمجة، مكملًا لعقد مشروعك.
- البرمجة الإبداعية بمساعدة Blockstudio: العمل مع وكلاء البرمجة على مشروع Blockstudio.
- كتاب أنماط الحقول: بُنى الحقول التي يفهم التحليل مفاتيح قوالبها، بما فيها المجموعات والمكرّرات.