Перевірені шаблони з PHPStan і згенерованим AGENTS.md
Блок Blockstudio — це два файли, які мають узгоджуватися. У block.json оголошені поля, а шаблон читає їх як $a['id']. Під час виконання ніщо не заважає шаблону прочитати ключ, який перейменували, не оголосили або написали з помилкою. Він просто виводить порожній рядок, і помилку помічають лише тоді, коли хтось бачить порожній заголовок на робочій сторінці. Те саме стосується екранування виводу: незахищений echo працює бездоганно, доки значення поля не містить розмітки.
Пакет blockstudio/phpstan переносить обидві проблеми на етап аналізу. Він читає файли block.json, визначає з них типи $a і повідомляє про звернення шаблонів, що не відповідають визначенням. Додаткові пресети вмикають правила структури теми, екранування та перевірки JavaScript і Tailwind. У пакеті також є два допоміжні інструменти: керований хук pre-commit, що запускає аналіз, і генератор, який створює 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.
Навмисно зламайте шаблон
У блоці hero оголошено одне поле:
{
"$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. Значення атрибутів, виведені через echo, потрібно пропускати через функцію екранування, наприкладesc_html(),esc_attr(),esc_url()абоwp_kses_post().echo.nonStringвиникає через невідомий ключ: для неіснуючого зміщення немає рядкового типу, який можна вивести.variable.undefinedз’являється, оскільки PHPStan бачить файл шаблону, а не функцію render, яка визначає$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 показує визначену структуру, тож це також найшвидший спосіб знайти анотацію для копіювання.
У версії 7.7 Blockstudio вважає $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 Interactivity. |
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 на його використання та додає його до наявного хуку pre-commit. Хук запускає 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 надає дані про ввімкнені функції, тож хук коміту відображається в розділі “Enabled features”, а vendor/bin/blockstudio-githooks sync — у розділі “Commands” лише тому, що задано 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.
- Збірник шаблонів полів: структури полів, ключі шаблонів яких розуміє аналізатор, зокрема групи та повторювачі.