Към съдържанието

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 и променливите на island преди да включи шаблон, така че директните прочитания като $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) -->

Атрибут се приема, когато блокът го декларира като поле (включително потребителски полета и полетата, които поле с тип блок препраща под своя 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 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

За да игнорирате файлове, използвайте стандартната конфигурация на PHPStan за excludePaths.

Предварителни настройки за анализ

Автоматично откритото разширение остава безопасната за съвместимост основа. 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 управлява скенера на темата. Стандартната конфигурация на PHPStan за excludePaths независимо управлява анализа на 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, типичния лимит 128M CLI. Подайте изрична опция 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. Каноничната команда и управляваната кука за commit откриват файла, така че куката блокира новите проблеми, без да изисква първо да бъдат отстранени всички натрупани.

Запазете настройките по подразбиране за командите в целия проект в 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 при невалидна употреба, конфигурация или изпълнение на процес

Управляван hook за commit

За да превърнете анализа на изключителната тема във врата при commit в хранилището, активирайте куката, управлявана от 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

Файловете, притежавани от потребителя, никога не се презаписват или изтриват. Ако някой промени core.hooksPath след активирането на Blockstudio, премахването запазва по-новата настройка. Генерираната кука поддържа свързани работни копия на Git и пътища с интервали, като разрешава активното хранилище и корена на проекта по време на commit. Тя изпълнява каноничната команда от този корен, така че един и същ обект phpstan управлява интерактивните изпълнения и commit-ите без дублирани генерирани аргументи.

Куката изпълнява само vendor/bin/blockstudio-phpstan. Blockstudio не изпълнява формататор, а куката никога не променя файловете на проекта. Липсващи зависимости и неуспешен анализ блокират commit-а с ясна грешка и указания за действие.

Активно рендиране 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
  • 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
Text
Blockstudio contract created: /path/to/project/AGENTS.md

Нищо в изхода не следва фиксиран шаблон. Всеки ред се извежда от един от три източника:

  • Собствените файлове на проекта. Тема със заглавка style.css, блокове и страници от файлове създава документ, различен от този на разширение, което регистрира само блокове. Броят, директориите, пространствата от имена на блоковете и езиците на шаблоните са това, което скенерът действително е открил, като използва същите корени и изключвания като анализа.
  • blockstudio.json. Описват се само активираните функции и конфигурираните им стойности: префикси на етикетите на блоковете и пространствата от имена, през които се разрешават, Tailwind, включеният в комплекта UI, нулирането на ресурсите в редактора, пътят до кеша, профилът на производителност, статичното предварително рендиране и динамичните му пътища, настройките по подразбиране на темата, Content Sync и куката за commit.
  • Избраната 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, както куката за commit прави същото с анализа:

Обвивка
vendor/bin/blockstudio-agents --check

Собственост

Генерираният файл съдържа маркер от същия вид като управляваната кука за commit и важи същото правило: 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

Разширението включва шаблони за целия публичен интерфейс на 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 чрез предварителната настройка за тема или изключителна тема.