跳转到正文

PHPStan

blockstudio/phpstan 扩展为 Blockstudio 项目提供静态分析。它会在分析时验证区块模板、架构文件、设置路径和 hook 名称,在错误进入运行时之前将其捕获。

安装

命令行
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 本身赋值时,它会保留所赋予的类型。不要添加 /** @var array<string, mixed> $a */ docblock,因为它会将该数据结构替换为开放数组。

字段键遵循 Blockstudio 的运行时扁平化规则。tabs 和不带 id 的匿名 group 容器仅用于呈现,因此其子字段仍属于父级作用域。命名分组会在子字段键前加上分组 ID:

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

可复用的自定义字段

在检查模板键和数组结构之前,会先展开基于文件的 custom/* 引用。扩展会读取匹配的 field.json,并应用与 Blockstudio 相同的 idStructure、overrides、嵌套引用、分组、标签页和重复器规则:

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.enabled 后,也会识别捆绑的 UI 区块。

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

必填字段不可为空。可选字段为 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 过滤器和操作 hook 名称会经过验证。

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

像 blockstudio/settings/tailwind/enabled 这样的动态设置 hook 始终允许使用。非 blockstudio 的 hook 会被忽略。

架构验证

扩展会验证项目中的每个 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 在 repeater 上有效,但用于文本字段时会被报告。插件的运行时行为不会改变。如果项目有意为内置字段附加自定义元数据,可仅屏蔽这些发现,同时保留其他结构检查:

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

可复用 field.json 中的内置字段仍会接受检查,即使 custom/* 引用带有自己的包装器选项也是如此。扩展文件不在这些属性名称诊断的范围内;扩展专属的 set 规则仍然有效。

field.json(可复用的自定义字段):

  • 缺少 name
  • attributes 缺失或为空
  • 属性对象无效或缺少字段 type
  • 对于需要 id 的值字段,缺少该属性
  • 未知字段类型
  • 字段类型不接受的字段属性
  • repeater 中存在 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 分析。

规范命令在 blockstudio.json 中的 phpstan.excludePaths 设置(以及其 --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 会在开始分析前以“This file is included multiple times”错误退出。

该命令默认将 PHPStan 设为 1G 内存限制,因此由 Composer 管理的 WordPress 项目不会受典型 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"
  }
}

对于 base 和 theme 预设,请保留 level 行。若未包含项目配置,规范命令只会为这些预设设置级别 max;如果没有级别 PHPStan,命令会以“No rules detected”错误退出。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
  • PHPStan 报告诊断时返回 1
  • 用法、配置或进程执行无效时返回 2

托管提交钩子

若要将极致主题分析设为仓库提交门禁,请在 blockstudio.json 中启用由 Blockstudio 所管理的钩子:

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

安装依赖或更改设置后,请同步该钩子:

命令行
vendor/bin/blockstudio-githooks sync

该命令会将生成的提交前钩子和所有权记录写入 Git 的公共目录,将 core.hooksPath 设为托管钩子目录,并安全地串联先前配置的提交前钩子。重复同步只会刷新生成的文件,因此软件包升级具有幂等性。

将 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 .

该命令不经 shell 运行,并且必须输出一个 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 会报告脚本传递给 querySelector()、querySelectorAll()、closest() 或 matches() 的 [data-*] 属性选择器,前提是没有经过分析的标记包含该属性。标记包括每个 PHP、Twig、Blade 和 HTML 文件,以及分析根目录下未被排除路径排除的每个 React .tsx 和 .jsx 组件。组件会被解析:JSX 属性名称以及对象字面量的字符串键都会计入,因此,展开到元素上的属性对象可满足选择器;类名和其他属性值则不计入。

Interactivity API 检查会读取相同的 React 组件。JSX 元素上的 data-wp-interactive 命名空间会被视为 blockstudio.interactivity.orphan 的模板引用,其中的 data-wp-* 指令会根据最近的外层命名空间解析,或使用值中的 namespace:: 前缀解析。具有静态字符串值的指令,无论写作 JSX 属性还是属性对象的字符串键,都必须指向现有的存储处理程序和路径(blockstudio.interactivity.handler、blockstudio.interactivity.binding);存储代码不得修改它们绑定的属性和类(blockstudio.interactivity.derivedState)。React 会转义属性值,因此组件中的 data-wp-context 不会被报告,动态值也不会接受检查。bsui/ 下的命名空间属于捆绑的 UI 区块,其存储随 Blockstudio 一同提供,位于分析根目录之外,因此它们从来不会成为孤立项。

诊断标识符

新增预设诊断会保留稳定的 blockstudio.* ID:

  • 主题结构: 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,设置 githooks.commit 时会出现 vendor/bin/blockstudio-githooks sync,而项目实际包含 db.php 时会出现 wp bs db schemas。

选项 行为
--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;--check 发现约定已过期时为 1;用法、配置或文件系统错误时为 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 检查的主题。