Перейти до вмісту

Перевірені шаблони з 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. Значення атрибутів, виведені через echo, потрібно пропускати через функцію екранування, наприклад esc_html(), esc_attr(), esc_url() або wp_kses_post().
  • echo.nonString виникає через невідомий ключ: для неіснуючого зміщення немає рядкового типу, який можна вивести.
  • variable.undefined з’являється, оскільки PHPStan бачить файл шаблону, а не функцію render, яка визначає $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 показує визначену структуру, тож це також найшвидший спосіб знайти анотацію для копіювання.

У версії 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 записує повідомлення в консоль, та сама команда повідомляє про такі проблеми:

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 на його використання та додає його до наявного хуку 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 надає дані про ввімкнені функції, тож хук коміту відображається в розділі “Enabled features”, а vendor/bin/blockstudio-githooks sync — у розділі “Commands” лише тому, що задано 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, зіставлені з блоками в джерелах сторінки, а також глобальні атрибути, які тег може передавати далі.

Наступні кроки