Перейти к содержимому

Проверяемые шаблоны с 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
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.

Намеренно нарушим шаблон

В блоке hero объявлено одно поле:

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 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 выводит сообщение в консоль, та же команда сообщает:

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 для прежнего состояния. Перед тем как доверять успешной проверке при изменениях, не связанных с 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
Text
{"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
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 и добавляет его после ранее настроенного хука pre-commit. Хук запускает из корневого каталога проекта только 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, сопоставленные блокам в источниках страниц, и глобальные атрибуты, которые тег может передавать дальше.

Следующие шаги

  • PHPStan справочник: каждое правило, параметр пресета, форма типа поля, пробник живого рендеринга и идентификатор диагностики.
  • Интеграция с ИИ: указатель документации для агентов программирования, дополняющий контракт вашего проекта.
  • Вайб-кодинг с Blockstudio: работа с агентами программирования над проектом на Blockstudio.
  • Сборник примеров структур полей: структуры полей, ключи шаблонов которых понимает анализатор, включая группы и повторители.