Проверяемые шаблоны с 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. Выводимые значения атрибутов должны проходить через функцию экранирования, например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() blockstudio/*. |
theme |
Базовый уровень, а также корневые каталоги темы и заголовки style.css, ресурсы, объявленные в block.json вместо ручной постановки в очередь, область действия %selector% в style.scss, значения полей по умолчанию и ограничения для повторителей. |
extreme-theme |
Уровень темы, строгие флаги PHPStan, отклонение вызовов shell и eval(), прямые записи $wpdb, экранирование вывода, Tailwind, JavaScript и проверки API Interactivity. |
wordpress-render |
Уровень Extreme Theme, дополненный предоставленной вами командой для проверки реального рендеринга. |
Если конфигурация проекта не подключена, каноническая команда также запускает base и theme с уровнем PHPStan max; extreme-theme задаёт max самостоятельно. Для каждой диагностической проверки предустановки предусмотрен стабильный идентификатор blockstudio.*; их список приведён в PHPStanсправочнике.
Уровни темы и Extreme анализируют файлы 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 для прежнего состояния. Перед тем как доверять успешной проверке при изменениях, не связанных с PHP, передайте --debug после --: это обходит кэш.
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, при сообщении PHPStan об ошибках диагностики — с кодом 1, а при ошибках использования, конфигурации или выполнения — с кодом 2.
Запускайте её канонической командой, а не добавляйте phpstan/extension-installer. Предустановки уже включают расширение, а при наличии установщика одна и та же extension.neon загружается дважды: PHPStan останавливается с сообщением «Этот файл подключён несколько раз» ещё до начала анализа.
Добавление к существующему проекту
При первом анализе проекта обычно обнаруживаются проблемы. Вместо перехода на менее строгую предустановку занесите их в базовый отчёт, чтобы для нового кода продолжали действовать все правила:
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 задаёт включённые функции, поэтому хук перед коммитом появляется в разделе «Включённые функции», а 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.
- Сборник примеров структур полей: структуры полей, ключи шаблонов которых понимает анализатор, включая группы и повторители.