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

قوالب مُتحقَّق منها باستخدام 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
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 وخطاف الإيداع الإعدادات نفسها:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": ["vendor/**"]
  },
  "githooks": {
    "commit": true
  }
}

يُعد extreme-theme الأكثر صرامة بين الإعدادات الثلاثة المسبقة الثابتة. يوضح الجدول أدناه ما يضيفه كل منها. يُبقي excludePaths ملفات Composer نفسها خارج فحص Blockstudio وخارج تحليل PHP.

إفساد قالب عمدًا

يعرّف قالب البطل حقلًا واحدًا:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading", "default": "" }
    ]
  }
}

يقرأ القالب ذلك الحقل على نحو صحيح، ثم يقرأ subtitle لم تعرّفه الكتلة مطلقًا ويطبعه دون تهريب:

PHP
<section useBlockProps>
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
</section>

في المحرر والواجهة الأمامية، يعرض هذا فقرة فارغة ولا يظهر أي خطأ. شغّل التحليل بدلًا من ذلك:

سطر الأوامر
vendor/bin/blockstudio-phpstan -- --no-progress
Text
 ------ -------------------------------------------------------------------
  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 لأن طبقة السمة تتطلبه لكل حقل:

JSON
{
  "$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
<?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
Text
 [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 يسجل في وحدة التحكم، يُصدر الأمر نفسه:

Text
 ------ -----------------------------------------------------------
  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
Text
{"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
Text
 [OK] Baseline generated with 3 errors.

ضمّن خط الأساس من إعدادات المشروع وأشِر إليه باستخدام phpstan.configuration:

Neon
includes:
    - phpstan-baseline.neon
JSON
{
  "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
Text
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit

يكتب الأمر الخطاف داخل مجلد Git نفسه، ويشير core.hooksPath إليه، ويربطه بأي خطاف قبل الإيداع كان مُعدًا من قبل. لا يشغّل الخطاف سوى vendor/bin/blockstudio-phpstan -- --no-progress من جذر المشروع: بلا أداة تنسيق أو إعادة كتابة. يتوقف إيداع القالب المعطوب سابقًا عند التحليل:

Text
 [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
Text
Blockstudio contract created: /path/to/acme/AGENTS.md

بالنسبة إلى السمة الواردة في هذا الدليل، يبدأ الملف المُنشأ كما يلي:

Markdown
# 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. ويوفر الإعداد المسبق المحدد قسم الصحة، المقروء من ملفات الإعداد طبقةً تلو الأخرى:

Markdown
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
Text
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.

ملاحظات تبقى بعد إعادة الإنشاء

ينتهي الملف بمنطقة للملاحظات. يُحافَظ على كل ما بين علامتيها حرفيًا في كل مرة يُعاد فيها الإنشاء، لذا ضع فيها معرفة المشروع التي لا يمكن استنتاجها من الملفات:

Markdown
## 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:

Text
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 المرتبطة بكتل في مصادر الصفحات والسمات العامة التي يمكن للوسم تمريرها.

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