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

PHPStan

Розширення blockstudio/phpstan додає статичний аналіз до проєктів Blockstudio. Під час аналізу воно перевіряє шаблони блоків, файли схем, шляхи налаштувань і назви хуків, виявляючи помилки до запуску.

Встановлення

Командна оболонка
composer require --dev blockstudio/phpstan

Для типізації шаблонів у версії 7.7 і розширених перевірок тегів блоків потрібні blockstudio/phpstan 0.1.9 або новіша версія та PHPStan 2.1.47 або новіша версія. Оновіть пакет окремо від плагіна:

Командна оболонка
composer require --dev blockstudio/phpstan:^0.1.9

Розширення автоматично виявляється за допомогою інсталятора розширень PHPStan. Ручне налаштування не потрібне.

Що перевіряється

Доступ до полів шаблону

Якщо файл PHP розташований поруч із block.json, розширення перевіряє кожне звернення $a['key'] відповідно до оголошених атрибутів блоку.

PHP
<?php

echo $a['title'];     // OK
echo $a['subtitle'];  // OK
echo $a['typo'];      // Error: Field "typo" does not exist in block.json

Розширення знає, що Blockstudio визначає $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview і змінні острова до підключення шаблону, тому прямі звернення, як-от $a['title'], не позначаються як потенційно невизначені, а тип $a визначається за block.json поруч із шаблоном. Ця структура зберігається під час звуження типів, тому $a['label'] ?? '', isset( $a['cta']['target'] ) і $a['cta']['title'] !== null зберігають оголошені типи полів; шаблон, який присвоює значення самій $a, зберігає призначений їй тип. Не додавайте docblock /** @var array<string, mixed> $a */: він замінює цю структуру на масив без заданої форми.

Ключі полів відповідають правилам розгортання під час виконання в Blockstudio. Контейнери tabs і анонімні group без id призначені лише для представлення, тому їхні дочірні поля залишаються в батьківській області видимості. Група з назвою додає свій ідентифікатор до ключів дочірніх полів як префікс:

PHP
echo $a['heading'];  // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.

Повторно використовувані користувацькі поля

Посилання custom/* на файли розгортаються до перевірки ключів шаблону та структур масивів. Розширення зчитує відповідний field.json і застосовує ті самі правила idStructure, overrides, вкладених посилань, груп, вкладок і повторювачів, що й Blockstudio:

JSON
{
  "name": "mytheme/hero",
  "attributes": [
    { "id": "heading", "type": "text" },
    { "id": "description", "type": "textarea" }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/mytheme/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "id": "title" }
        }
      }
    ]
  }
}

У результаті отримуємо ключі шаблону title і hero_description. Вони розпізнаються у PHP, Twig, Blade, тегах блоків і виведених формах атрибутів.

Відсутні, неоднозначні, недійсні або циклічні визначення на основі файлів спричиняють окрему помилку blockstudio.customField.*. Для цього блоку пропускаються залежні перевірки ключів, щоб одне невирішене визначення не спричинило нову хвилю хибних помилок про невідомі поля.

Визначення, зареєстровані лише під час виконання через фільтр blockstudio/fields PHP, неможливо вивести статичним аналізом. Якщо поле має додавати ключі шаблону, які перевіряються статично, використовуйте визначення field.json.

Доступ до шаблонів Twig

Шаблони Twig скануються автоматично. Анотація не потрібна.

Twig
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p>    {# Error: Field "typo" does not exist in block.json #}

Доступ до шаблонів Blade

Шаблони Blade скануються так само.

Blade
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p>    {{-- Error --}}

Перевірка тегів блоків

Теги блоків перевіряються в місцях, де їх зчитує Blockstudio: теги <bs:> і <block>, теги з префіксами, налаштованими в blockTags.prefixes (наприклад, <acme-card>, які розпізнаються у порядку просторів імен, як під час виконання), а також теги-псевдоніми — у шаблонах блоків PHP, Twig і Blade, а також у макетах сторінок. Також перевіряються джерела сторінок нижче pages/ (index.php, index.html, index.twig, index.blade.php), зокрема елементи HTML, які проєкт зіставляє з блоками. Вбудовані блоки UI розпізнаються, якщо ввімкнено ui.enabled.

HTML
<bs:mytheme-hero title="Hello" />
<!-- OK -->
<bs:mytheme-nonexistent />
<!-- Error: unknown block -->
<bs:mytheme-hero title="Hi" badattr="" />
<!-- Error: unknown attribute -->
<bs:mytheme-hero class="wide" />
<!-- Error: class is dropped unless the block declares a class field -->
<bs:mytheme-hero id="intro" aria-label="Intro" data-x="1" />
<!-- OK: forwarded to the root element -->
<block name="core/separator" />
<!-- OK (core blocks always valid) -->

Атрибут приймається, якщо блок оголошує його як поле (зокрема користувацьке поле або поле типу block, яке передає атрибути під idStructure), або якщо Blockstudio передає його кореневому елементу блоку: data-*, aria-*, id, style, role, title, lang, dir, hidden і tabindex. У шаблонах передається кожен атрибут html-*; у джерелах сторінок префікс html- може позначати лише один із переданих атрибутів. Усе інше, особливо неоголошений class, позначається як помилка, оскільки Blockstudio його зберігає, але ніколи не відображає.

Під час виконання зіставлення елементів і псевдоніми тегів реєструються у фільтрах PHP, які статичний аналіз не може обчислити, тому аналіз зчитує їх із blockstudio.json. scanPhp також перевіряє теги в інших PHP проєкту, наприклад розмітку компонентів у модулях, не позначаючи там невідомі блоки:

JSON
{
  "phpstan": {
    "blockTags": {
      "elements": {
        "section": "theme/section",
        "h2": "theme/heading",
        "div": [
          { "attribute": "width", "block": "theme/row" },
          "theme/div"
        ]
      },
      "aliases": { "theme-button": "bsui/button" },
      "scanPhp": true
    }
  }
}

Елемент зіставляється з назвою блоку або з набором правил, які перевіряються по черзі: перемагає перше правило, атрибут якого має елемент, а звичайна назва блоку збігається завжди. Елементи, які проєкт не зіставляє, залишаються основними блоками й не перевіряються. У діагностиці використовуються blockstudio.blockTag.unknown, blockstudio.blockTag.attribute і blockstudio.blockTag.class.

Типізація записів бази даних

Db::get() повертає типізований екземпляр на основі схеми db.php. Структури записів виводяться автоматично.

PHP
return [
    'storage' => 'table',
    'fields' => [
        'email' => ['type' => 'string', 'required' => true],
        'name'  => ['type' => 'string'],
    ],
];
PHP
$db = Db::get('mytheme/subscribers');
$record = $db->create(['email' => 'a@b.com']);

echo $record['email']; // string
echo $record['name'];  // string|null (optional field)
echo $record['typo'];  // Error: Offset 'typo' does not exist

Обов’язкові поля не можуть мати значення null. Необов’язкові поля мають тип type|null. Поле id (int) присутнє завжди. Така сама типізація працює для синтаксису конструктора PHP-native Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.

Перевірка шляхів налаштувань

Шляхи Settings::get() перевіряються відповідно до відомої схеми налаштувань.

PHP
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // Error: Did you mean "tailwind/enabled"?

Перевірка назв хуків

Назви хуків фільтрів і дій Blockstudio перевіряються.

PHP
add_filter('blockstudio/render', $cb);   // OK
add_filter('blockstudio/rendrr', $cb);   // Error: Did you mean "blockstudio/render"?

Динамічні хуки налаштувань, як-от blockstudio/settings/tailwind/enabled, завжди дозволені. Хуки, що не належать до blockstudio, ігноруються.

Перевірка схеми

Розширення перевіряє кожен файл схеми Blockstudio у проєкті.

block.json:

  • Відсутнє поле name
  • Відсутнє поле type
  • Відсутній id для полів значень, де він обов’язковий
  • Невідомі типи полів
  • Властивості поля, які не підтримуються його типом, наприклад "translat" замість "translate"; як підказку наведено найближчу відому властивість
  • select/radio/checkbox без options або populate
  • Дублікати ID полів
  • Поле tabs у повторювачі — безпосередньо або в групі без id
  • Некоректні декларації pluginDependencies

Поля-контейнери, як-от group і tabs, а також посилання на поля custom/* можуть не містити id, якщо вони лише розгортають або обгортають інші поля.

Властивості полів перевіряються на відповідність властивостям, які schemas/block.json визначає для кожного вбудованого типу поля, а також властивостям, які приймають усі поля. Властивості, специфічні для обгортки, у посиланнях custom/* та типи полів із просторами імен, визначені проєктом, не входять до цієї перевірки. Перевірка наявних типів полів і користувацьких посилань працює й надалі. Ідентифікатори: blockstudio.blockJson.property і blockstudio.fieldJson.property.

Перевіряються назви властивостей, а не лише їхні значення: minimized допустима для повторювача, але для текстового поля буде позначена як помилка. Поведінка плагіна під час виконання не змінюється. Якщо проєкт навмисно додає власні метадані до вбудованих полів, вимкніть лише ці зауваження, не вимикаючи інші перевірки структури:

Neon
parameters:
    ignoreErrors:
        - identifier: blockstudio.blockJson.property
        - identifier: blockstudio.fieldJson.property

Вбудовані поля всередині багаторазово використовуваного field.json усе одно перевіряються, навіть якщо посилання custom/* має власні параметри обгортки. Файли розширень не входять до сфери дії цієї діагностики назв властивостей; спеціальні правила set для розширень залишаються чинними.

field.json (повторно використовувані користувацькі поля):

  • Відсутній name
  • Відсутній або порожній attributes
  • Некоректні об’єкти атрибутів або відсутній type поля
  • Відсутній id у полях значень, для яких він обов’язковий
  • Невідомі типи полів
  • Властивості, які тип поля не підтримує
  • Поле tabs у повторювачі — безпосередньо або в групі без id
  • Відсутні, неоднозначні, некоректні або циклічні вкладені посилання custom/*

Розширення JSON (розширення блоків у extensions/):

  • Відсутнє name (цільовий блок)
  • Відсутній ключ blockstudio
  • Відсутній ключ blockstudio.extend

page.json (сторінки на основі файлів):

  • Відсутнє title
  • Відсутнє slug
  • Недійсні значення postStatus

db.php:

  • Відсутній масив fields
  • Недійсні типи полів
  • Підтримуються як застарілі масиви, так і Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field

rpc.php:

  • Недійсні методи HTTP
  • Неправильне значення public (має бути true, false або 'open')
  • Підтримуються як застарілі масиви, так і повернення об’єктів з атрибутами

cron.php:

  • Відсутній schedule у налаштованих завданнях
  • Відсутній callback у налаштованих завданнях
  • Підтримуються як застарілі масиви, так і повернення об’єктів з атрибутами

blockstudio.json:

  • Скорочені логічні значення, як-от "tailwind": true (потрібно використовувати вкладений формат об’єкта {"enabled": true, "config": ""})

Конфігурація

За замовчуванням розширення знаходить файли Blockstudio в аналізованому проєкті. Якщо проєкт використовує блоки або повторно використовувані поля з бібліотеки поза кореневим каталогом проєкту, додайте шлях до бібліотеки в blockstudioScanRoots. Шлях сканується для визначень block.json та field.json, тож зовнішні теги блоків і їхні власні поля можна перевірити разом.

YAML
parameters:
  blockstudioScanRoots:
    - vendor/acme/block-library/blockstudio

Щоб ігнорувати файли, скористайтеся стандартною конфігурацією excludePaths для PHPStan.

Попередні налаштування аналізу

Автоматично виявлене розширення залишається безпечною для сумісності базою. Blockstudio 7.6 додає опційні рівні, не змінюючи наявні проєкти:

Попереднє налаштування Поведінка
base.neon Аналіз наявної схеми, шаблонів, хуків, налаштувань і API.
theme.neon Базовий рівень плюс корені тем WordPress, заголовки стилів, ресурси Blockstudio, обмеження селекторів, значення полів за замовчуванням і межі повторювачів.
extreme-theme.neon Тема плюс PHPStan max, небезпечні PHP, екранування виводу, Tailwind, JavaScript та перевірки Interactivity API.
wordpress-render.neon Екстремальна тема плюс жива проба рендерингу WordPress, надана викликачем.

Встановлення blockstudio/phpstan вмикає лише базове розширення. Додайте опційний рівень до наявної конфігурації PHPStan:

YAML
includes:
  - vendor/blockstudio/phpstan/extreme-theme.neon

parameters:
  blockstudioThemeRoots:
    - .
  blockstudioThemeExcludePaths:
    - fixtures/**
  blockstudioThemeMaxFiles: 10000
  blockstudioExtremeJavaScript: true
  blockstudioExtremeTailwind: true

blockstudioThemeExcludePaths керує сканером тем. Стандартний excludePaths від PHPStan окремо керує аналізом PHP.

Параметр phpstan.excludePaths канонічної команди в blockstudio.json (і її параметр --exclude) налаштовує обидва рівні. Відносні шаблони обчислюються відносно кожного налаштованого кореня, тож записи на кшталт vendor/** обмежують аналіз PHPStan, а також сканування проєкту Blockstudio.

Шаблон із назвою одного каталогу, як-от _dist/** або node_modules/**, виключає цей каталог у будь-якому місці, а не лише поруч із коренем теми. Шаблон зі скісною рискою, як-от assets/*/docs/**, залишається прив’язаним до кореня. Згенеровані ресурси блоків розташовані в каталозі _dist усередині кожного блоку, тому саме форма з назвою одного каталогу не дає скомпільованому виводу потрапити до аналізу.

Канонічна команда

Пакет встановлює vendor/bin/blockstudio-phpstan як виконуваний файл для аналізу. За замовчуванням він запускає попереднє налаштування base, якщо проєкт не вибере інше, тож саме встановлення пакета не вмикає рівні теми або екстремальної теми:

Командна оболонка
vendor/bin/blockstudio-phpstan --root . -- --no-progress

Попередні налаштування вже містять саме розширення. Не додавайте phpstan/extension-installer до проєкту, який запускає канонічну команду: за наявності інсталятора extension.neon завантажується двічі, і PHPStan зупиняється з повідомленням «Цей файл включено кілька разів» ще до початку аналізу.

За замовчуванням команда встановлює для PHPStan ліміт пам’яті 1G, щоб проєкти WordPress, керовані через Composer, не мали типового обмеження CLI 128M. Щоб перевизначити його, передайте явний параметр PHPStan після --, наприклад -- --memory-limit=512M --no-progress.

Додавання аналізу до наявного проєкту

Перший запуск зазвичай виявляє проблеми в проєкті, який ще не аналізували. Замість того щоб знижувати рівень попереднього налаштування, створіть базовий файл PHPStan і вкажіть phpstan.configuration на конфігурацію проєкту, яка його містить. Тоді до нового коду застосовуватиметься повний набір перевірок, а вже зафіксовані проблеми не заважатимуть:

Командна оболонка
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
Neon
includes:
    - phpstan-baseline.neon

parameters:
    level: max
JSON
{
  "phpstan": {
    "configuration": "phpstan.neon"
  }
}

Залиште рядок level для попередніх налаштувань base і theme. Канонічна команда встановлює для них рівень max лише за відсутності конфігурації проєкту; без рівня PHPStan зупиняється з повідомленням «Правил не виявлено». Попереднє налаштування extreme-theme встановлює рівень max самостійно.

Відносні шляхи обчислюються від blockstudio.json. Канонічна команда та керований хук коміту знаходять цей файл, тож хук блокує нові проблеми, не вимагаючи спершу усувати весь накопичений борг.

Зберігайте загальні для проєкту параметри команди в blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": ["fixtures/**"],
    "maxFiles": 10000
  }
}

Відносні корені обчислюються відносно файлу, у якому їх оголошено. Явні значення CLI замінюють відповідні значення JSON. Передайте --blockstudio-json path/to/project.json, щоб указати альтернативне джерело конфігурації. Помилковий JSON, непідтримувані ключі phpstan, недійсні значення та відсутність явно заданого джерела призводять до передбачуваної помилки з кодом виходу 2.

Виберіть інше попереднє налаштування, додайте конфігурацію проєкту, задайте повторювані корені й виключення або попросіть PHPStan надати JSON:

Командна оболонка
vendor/bin/blockstudio-phpstan \
  --preset theme \
  --configuration phpstan.neon \
  --root . \
  --exclude 'fixtures/**' \
  --max-files 10000 \
  --error-format json \
  -- --no-progress

Оболонка формує конфігурацію в системному тимчасовому каталозі й видаляє її після завершення. Вона ніколи не записує згенеровану конфігурацію, базові файли, хуки чи кеші до аналізованого проєкту. Викликачі все одно можуть явно налаштувати стандартний кеш PHPStan.

Умови щодо кодів завершення:

  • 0, якщо аналіз пройшов успішно
  • 1, якщо PHPStan повідомляє про діагностичні повідомлення
  • 2 у разі неправильного використання, помилки конфігурації або виконання процесу

Керований хук коміту

Щоб увімкнути аналіз екстремальної теми як перевірку під час коміту в репозиторії, увімкніть хук, яким керує Blockstudio, у blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": [],
    "maxFiles": 10000
  },
  "githooks": {
    "commit": true
  }
}

Синхронізуйте його після встановлення залежностей або зміни параметра:

Командна оболонка
vendor/bin/blockstudio-githooks sync

Команда записує згенерований хук pre-commit і запис про його належність у спільний каталог Git, встановлює core.hooksPath на каталог керованих хуків і безпечно додає до нього раніше налаштований хук pre-commit. Повторна синхронізація оновлює лише згенерований файл, тому оновлення пакета є ідемпотентними.

Установіть commit у значення false, вилучіть його або вилучіть blockstudio.json, а потім запустіть sync, щоб відновити збережений шлях до хука й видалити лише файли, якими керує Blockstudio. Також можна запустити:

Командна оболонка
vendor/bin/blockstudio-githooks remove

Файли, якими керує користувач, ніколи не перезаписуються й не видаляються. Якщо після ввімкнення Blockstudio хтось змінить core.hooksPath, під час видалення це нове значення збережеться. Згенерований хук підтримує пов’язані копії Git і шляхи з пробілами, визначаючи активний репозиторій і корінь проєкту під час коміту. Він запускає канонічну команду з цього кореня, тож той самий об’єкт phpstan керує інтерактивними запусками й комітами без дублювання згенерованих аргументів.

Хук запускає лише vendor/bin/blockstudio-phpstan. Blockstudio не запускає форматувальник, і хук ніколи не переписує файли проєкту. Відсутні залежності та помилки аналізу блокують коміт із чітким поясненням.

Живе рендерення WordPress

Живий рівень навмисно вмикається явно. Викликач відповідає за середовище WordPress і передає масив argv:

Командна оболонка
vendor/bin/blockstudio-phpstan \
  --preset wordpress-render \
  --render-command='["wp","eval-file","tools/render-probe.php"]' \
  --render-working-directory=. \
  --render-timeout=60 \
  --root .

Команда запускається без оболонки й має вивести один об’єкт JSON:

JSON
{"ok":true}

Проба може повідомити про конкретну помилку:

JSON
{
  "ok": false,
  "message": "Rendered block failed.",
  "file": "/absolute/path/to/block.json",
  "line": 12
}

Ненульові коди завершення, перевищення часу очікування, некоректний JSON і ok: false призводять до blockstudio.wordpress.render.

blockstudio.javascript.domContract повідомляє про селектор атрибута [data-*], який скрипт передає в querySelector(), querySelectorAll(), closest() або matches(), якщо в жодній проаналізованій розмітці немає цього атрибута. До розмітки належать усі файли PHP, Twig, Blade і HTML, а також усі компоненти React .tsx і .jsx у межах проаналізованих кореневих каталогів, за винятком виключених шляхів. Компоненти розбираються: враховуються назви атрибутів JSX і рядкові ключі об’єктних літералів, тому об’єкт атрибутів, розгорнутий в елемент, задовольняє селектор, а назви класів та інші значення атрибутів — ні.

Перевірки Interactivity API аналізують ті самі компоненти React. Простір імен data-wp-interactive на елементі JSX вважається посиланням на шаблон для blockstudio.interactivity.orphan, а директиви data-wp-* усередині нього визначаються за найближчим зовнішнім простором імен або за префіксом namespace:: у значенні. Директиви зі статичним рядковим значенням, записані як атрибут JSX або як рядковий ключ об’єкта атрибутів, мають указувати на наявні обробники та шляхи сховища (blockstudio.interactivity.handler, blockstudio.interactivity.binding), а код сховища не повинен змінювати прив’язані атрибути й класи (blockstudio.interactivity.derivedState). React екранує значення атрибутів, тому data-wp-context у компоненті не позначається, а динамічні значення не перевіряються. Простори імен у bsui/ належать вбудованим блокам UI, чиї сховища постачаються з Blockstudio за межами проаналізованих кореневих каталогів, тож вони ніколи не вважаються осиротілими.

Ідентифікатори діагностичних повідомлень

Нові діагностичні повідомлення попередніх налаштувань мають стабільні ідентифікатори blockstudio.*:

  • Структура теми: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Ресурси й поля: blockstudio.theme.asset.manualEnqueue, blockstudio.theme.asset.selectorScope, blockstudio.theme.asset.missing, blockstudio.field.default, blockstudio.field.repeaterBounds
  • PHP: blockstudio.php.forbiddenFunction, blockstudio.wordpress.rawDatabaseWrite, blockstudio.output.unescaped
  • Tailwind: blockstudio.tailwind.compilerMissing, blockstudio.tailwind.compile, blockstudio.tailwind.unknownUtility, blockstudio.tailwind.semanticToken
  • JavaScript: blockstudio.javascript.syntax, blockstudio.javascript.debugOutput, blockstudio.javascript.bannedApi, blockstudio.javascript.leakedGlobal, blockstudio.javascript.importSpecifier, blockstudio.javascript.rootGuard, blockstudio.javascript.initShape, blockstudio.javascript.domContract, blockstudio.javascript.listenerCleanup, blockstudio.javascript.reducedMotion
  • Інтерактивність: blockstudio.interactivity.import, blockstudio.interactivity.moduleImport, blockstudio.interactivity.namespace, blockstudio.interactivity.scopedDom, blockstudio.interactivity.derivedState, blockstudio.interactivity.handler, blockstudio.interactivity.binding, blockstudio.interactivity.context, blockstudio.interactivity.orphan

Продуктивність

Сканер приймає звичайні каталоги на диску, усуває дублікати коренів, пропускає каталоги залежностей, збірок і кешу, кешує читання файлів у пам’яті та впорядковує діагностичні повідомлення передбачувано. Вибирайте вузькі корені, виключайте тестові й згенеровані каталоги та задавайте обмеження кількості файлів для великих репозиторіїв. JavaScript та Tailwind можна вимикати незалежно. Живе рендерення запускається лише тоді, коли вибрано відповідне попереднє налаштування.

Діагностичні повідомлення від теми, JavaScript і Tailwind передаються через кеш результатів PHPStan. Якщо змінити лише block.json або скрипт, теплий кеш може повернути попередній результат. Щоб обійти кеш і перевірити такі зміни, передайте --debug після --.

Вимоги до проєкту для агентів програмування

Пакет встановлює третій виконуваний файл — vendor/bin/blockstudio-agents. Він створює AGENTS.md з описом проєкту, у якому його запущено. Такий опис потрібен агенту програмування, перш ніж він щось змінюватиме: що створюють у проєкті, які функції Blockstudio увімкнено, що відхилить аналіз і які команди застосовуються.

Командна оболонка
vendor/bin/blockstudio-agents
Text
Blockstudio contract created: /path/to/project/AGENTS.md

Вивід не формується за фіксованим шаблоном. Кожен рядок походить з одного з трьох джерел:

  • Власні файли проєкту. Тема із заголовком style.css, блоками й файлами сторінок дає інший документ, ніж плагін, який лише реєструє блоки. Сканер фактично знаходить кількість і каталоги, простори назв блоків і мови шаблонів, використовуючи ті самі корені та виключення, що й аналіз.
  • blockstudio.json. Описуються лише ввімкнені функції та їхні налаштовані значення: префікси тегів блоків і простори назв, за якими вони визначаються, Tailwind, вбудований UI, скидання ресурсів редактора, шлях до кешу, профіль продуктивності, статичне попереднє рендерення та його динамічні шляхи, параметри теми за замовчуванням, Content Sync і хук коміту.
  • Вибране phpstan.preset. Розділ про коректність читається безпосередньо з файлів попередніх налаштувань, рівень за рівнем, і містить точно ті правила, які реєструє вибране налаштування. Для base описуються правила схеми, шаблонів, хуків і налаштувань. Для extreme-theme також описуються правила структури теми, суворі прапорці PHPStan, небезпечні PHP, екранування виводу, Tailwind і JavaScript. Якщо до попереднього налаштування додається правило, воно з’являється і в згенерованому документі.

У розділі команд діє той самий принцип. wp bs prerender status з’являється, коли ввімкнено статичне попереднє рендерення, vendor/bin/blockstudio-githooks sync — коли задано githooks.commit, а wp bs db schemas — коли в проєкті дійсно є db.php.

Параметр Поведінка
--root <path> Корінь проєкту (за замовчуванням: поточний каталог)
--config <path> Шлях blockstudio.json (за замовчуванням: <root>/blockstudio.json)
--output <path> Шлях до контракту (за замовчуванням: <root>/AGENTS.md)
--stdout Вивести контракт замість запису у файл
--check Завершити з кодом 1, якщо контракт на диску застарів
--force Замінити файл, яким не керує Blockstudio

--check перетворює контракт на перевірку в CI, так само як хук коміту перетворює аналіз на перевірку:

Командна оболонка
vendor/bin/blockstudio-agents --check

Керування файлами

Згенерований файл має такий самий маркер, як і керований хук коміту, і діє те саме правило: Blockstudio ніколи не замінює файл, якого не створював. Якщо AGENTS.md існував ще до появи команди або його створив автор вручну, команда відмовляється його змінювати, повертає код виходу 2 і залишає файл недоторканим, доки не передано --force.

Повторна генерація безпечна. Наприкінці файла є розділ для приміток, і байти між його маркерами зберігаються під час кожної генерації:

Markdown
## Project notes

<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->

Коди виходу: 0, якщо контракт записано, він актуальний або його виведено; 1, якщо --check виявляє застарілий контракт; 2 у разі помилок використання, конфігурації або файлової системи.

Форми типів полів

Розширення зіставляє кожен тип поля Blockstudio із конкретним типом PHP:

Тип поля Тип PHP
text, textarea, richtext, wysiwyg, code string
date, datetime, classes, html-tag, unit, gradient string
number, range int|float
toggle bool
select, radio, checkbox (одиночне) string|int
select, checkbox (множинне) list<string|int>
color array{value: string, opacity: float|null}
link array{url: string, title: string|null, target: string|null, opensInNewTab: bool|null}
icon array{set: string, subSet: string, icon: string}
files (одиночне) array{id: int, url: string, alt: string|null, mime_type: string|null}
files (множинне) list<array{id: int, url: string, ...}>
group Іменовані групи використовують префікси підкреслення; анонімні групи розгортаються в батьківську область видимості
repeater list<array{...child fields...}>
tabs Розгортається в батьківську область видимості

Заготовки API

Розширення містить заготовки для всього публічного API Blockstudio:

  • bs_render_block(), bs_block_values(), bs_get_group(), bs_get_scoped_class(), bs_db_form(), bs_is_editor(), bs_is_preview(), bs_is_buffering(), bs_strip_render_markers()
  • Db::get(), Db::create(), Db::list(), Db::get_record(), Db::update(), Db::delete()
  • Settings::get(), Settings::get_all()
  • Field_Registry::instance(), Field_Registry::all(), Field_Registry::get()
  • Build::blocks(), Build::extensions(), Build::get_build_dir()

Вони забезпечують автодоповнення та перевірку типів без потреби мати на комп’ютері вихідний код плагіна Blockstudio.

Вимоги

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (рекомендовано для автоматичного виявлення)

Пакет автоматично встановлює провайдер сумісності з BC Math. Тому нативний ext-bcmath необов’язковий, зокрема для щойно згенерованих тем, у яких перевірки JavaScript увімкнені через попереднє налаштування теми або екстремальної теми.