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
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, сохраняется назначенный ему тип. Не добавляйте блок документации /** @var array<string, mixed> $a */: он заменяет эту структуру открытым массивом.
Ключи полей следуют правилам разворачивания среды выполнения Blockstudio. Элементы tabs и анонимные контейнеры group без id служат только для представления, поэтому их дочерние поля остаются в родительской области видимости. Ключи дочерних полей именованной группы получают префикс с её идентификатором:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
Повторно используемые пользовательские поля
Ссылки на файловые определения custom/* раскрываются до проверки ключей шаблона и структуры массивов. Расширение считывает соответствующий field.json и применяет те же правила для idStructure, overrides, вложенных ссылок, групп, вкладок и повторителей, что и Blockstudio:
{
"name": "mytheme/hero",
"attributes": [
{ "id": "heading", "type": "text" },
{ "id": "description", "type": "textarea" }
]
}
{
"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 сканируются автоматически. Аннотации не нужны.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
Доступ к шаблонам 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.
<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) -->
Атрибут принимается, если блок объявляет его как поле (включая пользовательские поля и поля, передаваемые полем с типом «блок» под его idStructure), или если Blockstudio передаёт его корневому элементу блока: data-*, aria-*, id, style, role, title, lang, dir, hidden и tabindex. В шаблонах передаётся каждый атрибут html-*; в исходных файлах страниц префикс html- обозначает только один из передаваемых атрибутов. Все остальные атрибуты, особенно необъявленный class, вызывают сообщение об ошибке, поскольку Blockstudio сохраняет его, но никогда не отображает.
Среда выполнения регистрирует сопоставления элементов и псевдонимы тегов в фильтрах PHP, которые невозможно обработать статическим анализом. Поэтому анализ считывает их из blockstudio.json. scanPhp также проверяет теги в других PHP проекта, например в разметке компонентов в модулях, не сообщая там о неизвестных блоках:
{
"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. Структура записей определяется автоматически.
return [
'storage' => 'table',
'fields' => [
'email' => ['type' => 'string', 'required' => true],
'name' => ['type' => 'string'],
],
];
$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, встроенному в Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.
Проверка путей настроек
Пути Settings::get() проверяются по известной схеме настроек.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
Проверка имён хуков
Проверяются имена хуков-фильтров и хуков-действий Blockstudio.
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 допустимо для повторителя, но будет отмечено в текстовом поле. Поведение плагина во время выполнения не меняется. Если проект намеренно добавляет собственные метаданные к встроенным полям, отключайте только эти замечания, не отключая остальные проверки структуры:
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, поэтому внешние теги блоков и их пользовательские поля можно проверять вместе.
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:
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
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
Оставьте строку level для предустановок base и theme. Каноническая команда задаёт для них уровень max, только если конфигурация проекта не включена. Без уровня PHPStan останавливается с ошибкой «Правила не обнаружены». Предустановка extreme-theme задаёт уровень max самостоятельно.
Относительные пути разрешаются относительно blockstudio.json. Каноническая команда и управляемый хук коммита оба находят этот файл, поэтому хук блокирует появление новых проблем, не требуя сначала устранить накопленные.
Храните общие для проекта значения по умолчанию для команды в blockstudio.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:
{
"$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:
{"ok":true}
Проба может сообщить о конкретной ошибке:
{
"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 и строковые ключи объектных литералов. Поэтому объект атрибутов, добавленный к элементу через spread, удовлетворяет селектору, а имена классов и другие значения атрибутов — нет.
Проверки 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 - Interactivity:
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
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.
Повторная генерация безопасна. В конце файла находится область для примечаний, и байты между её маркерами сохраняются при каждой повторной генерации:
## 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
Расширение поставляется со стабами для всего публичного Blockstudio API:
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 включены через предустановку темы или максимальной темы.