Проверени шаблони с PHPStan и генериран AGENTS.md
Блок на Blockstudio се състои от два файла, които трябва да съвпадат. block.json декларира полетата, а шаблонът ги чете като $a['id']. Нищо по време на изпълнение не спира шаблона да прочете ключ, който е преименуван, никога не е деклариран или е изписан грешно. Просто се визуализира празен низ и грешката се забелязва едва когато някой види празно заглавие на публикувана страница. Същото важи за ескейпирането на изхода: неескейпиран echo работи без проблем, докато стойността на дадено поле не съдържа маркировка.
Пакетът blockstudio/phpstan премества и двата проблема в етапа на анализа. Той чете файловете ви block.json, определя типовете на $a от тях и съобщава за несъответстващи обръщения към шаблони. Незадължителните предварително зададени конфигурации добавят правила за структурата на темата, ескейпиране и проверки на JavaScript и Tailwind. Пакетът включва и два допълващи инструмента: управляван hook за предварително потвърждение, който стартира анализа, и генератор, който създава 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 и hook-ът за комит четат едни и същи настройки:
{
"$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 tag @var with type array<string, mixed> is not subtype of native type 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(), както и имената на hook-ове blockstudio/*. |
theme |
Базовата конфигурация плюс корените на темата и заглавките style.css, ресурси, декларирани в block.json вместо добавени ръчно, ограничаване на %selector% в style.scss, стойности по подразбиране за полетата и ограничения за повтарящи се полета. |
extreme-theme |
Темата плюс строги флагове PHPStan, отхвърлени извиквания на shell и eval(), директни записи в $wpdb, ескейпиране на изхода, Tailwind, JavaScript и проверки на Interactivity 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, синхронизирайте управлявания hook веднъж след инсталирането на зависимостите:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
Командата записва hook-а в собствената директория на Git, насочва core.hooksPath към него и добавя след него всеки hook за предварително потвърждение, който е бил конфигуриран преди това. Hook-ът изпълнява vendor/bin/blockstudio-phpstan -- --no-progress от корена на проекта и нищо друго: без форматиране и без пренаписване. Комит с повредения по-рано шаблон спира на етапа на анализа:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Задайте commit на false и стартирайте sync отново или изпълнете vendor/bin/blockstudio-githooks remove, за да възстановите предишния път на hook-а. Изтриват се само файловете, записани от 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 предоставя включените функции, така че hook-ът за комит се показва под „Включени функции“, а 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 справочник: всяко правило, предварително зададен параметър, форма на типа на полето, проба за визуализация на живо и идентификатор за диагностика.
- Интеграция с AI: индексът на документацията за програмни агенти, който допълва договора на проекта.
- Вибекодиране с Blockstudio: работа с програмни агенти по проект с Blockstudio.
- Книга с рецепти за модели на полета: структури на полета, чиито шаблонни ключове анализът разбира, включително групи и повторители.