跳转到正文

使用 PHPStan 检查模板,并生成 AGENTS.md

一个 Blockstudio 区块由两个必须保持一致的文件组成。block.json 声明字段,模板将它们读取为 $a['id']。运行时不会阻止模板读取已重命名、从未声明或拼写错误的键。它只会渲染为空字符串,直到有人发现线上页面中的空白标题,错误才会显现。输出转义也是如此:未转义的 echo 看似完全正常,直到字段值包含标记语言。

blockstudio/phpstan 软件包会在分析阶段解决这两个问题。它会读取你的 block.json 文件,从中为 $a 添加类型,并报告与定义不符的模板读取。可选择启用的预设还会添加主题结构规则、转义规则,以及 JavaScript 和 Tailwind 检查。该软件包还附带两个配套工具:运行分析的托管式提交前钩子,以及生成器;后者会编写描述项目的 AGENTS.md,供编码代理使用。

本指南会构建一个小型主题,故意破坏其中一个模板,查看分析输出并修复问题,然后接入提交门禁和代理契约。

设置主题

先准备一个主题文件夹,其中包含带有 style.css 标头的文件、一个 composer.json 和一个区块:

代码
acme/
├── blockstudio/
│   └── hero/
│       ├── block.json
│       └── index.php
├── blockstudio.json
├── composer.json
└── style.css
CSS
/*
Theme Name: Acme
*/

将软件包安装为开发依赖项:

命令行
composer require --dev blockstudio/phpstan

它会引入 PHPStan 和来自 szepeviktor/phpstan-wordpress 的 WordPress 存根,并在 vendor/bin 中安装三个可执行文件:blockstudio-phpstan、blockstudio-githooks 和 blockstudio-agents。

然后指定分析要运行的内容。项目级默认设置位于 blockstudio.json 的 phpstan 对象中,因此交互式运行、CI 和提交钩子都会读取相同的设置:

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

extreme-theme 是三个静态预设中最严格的一个。下方的表格会说明每个预设添加的内容。excludePaths 会将 Composer 自身的文件排除在 Blockstudio 扫描和 PHP 分析之外。

故意破坏模板

Hero 区块只声明了一个字段:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading", "default": "" }
    ]
  }
}

模板正确读取了该字段,接着读取一个区块从未声明的 subtitle,并且未转义就输出它:

PHP
<section useBlockProps>
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
</section>

在编辑器和前端,这会渲染出一个空段落,且不会报错。改为运行分析:

命令行
vendor/bin/blockstudio-phpstan -- --no-progress
Text
 ------ -------------------------------------------------------------------
  Line   blockstudio/hero/index.php
 ------ -------------------------------------------------------------------
  2      Variable $a might not be defined.
         🪪  variable.undefined
  3      Dynamic Blockstudio attributes must be escaped before output.
         🪪  blockstudio.output.unescaped
  3      Field "subtitle" does not exist in block.json (block: acme/hero).
         🪪  blockstudio.field
  3      Offset 'subtitle' does not exist on array{heading: string}.
         🪪  offsetAccess.notFound
  3      Parameter #1 (mixed) of echo cannot be converted to string.
         🪪  echo.nonString
  3      Variable $a might not be defined.
         🪪  variable.undefined
 ------ -------------------------------------------------------------------

 [ERROR] Found 6 errors

该命令以 1 退出。以下按具体程度从高到低阅读诊断信息:

  • blockstudio.field 是模板规则。它在模板旁边找到了 block.json,解析了它的字段,而 subtitle 不在其中。
  • offsetAccess.notFound 是 PHPStan 本身得出的相同结论,因为扩展为 $a 提供了具体结构 array{heading: string},该结构源自 block.json。每种字段类型都对应一个 PHP 类型:text 是 string,toggle 是 bool,而重复字段则是由行结构组成的数组。
  • blockstudio.output.unescaped 来自 extreme-theme 层。输出的属性值必须经过转义函数处理,例如 esc_html()、esc_attr()、esc_url() 或 wp_kses_post()。
  • echo.nonString 是由未知键推导出的结果:不存在的偏移量没有可供输出的字符串类型。
  • variable.undefined 出现是因为 PHPStan 看到的是模板文件,而不是在引入模板之前定义 $a 的渲染函数。修复部分会介绍解决方法。

修复问题

判断 subtitle 是否为真实字段。这里确实是,因此要声明它,并添加 default,因为主题层要求每个字段都必须有一个:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading", "default": "" },
      { "id": "subtitle", "type": "textarea", "label": "Subtitle", "default": "" }
    ]
  }
}

转义输出,并按照扩展程序推断的结构声明 $a:

PHP
<?php
/** @var array{heading: string, subtitle: string} $a */
?>
<section useBlockProps>
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
  <p><?php echo esc_html( $a['subtitle'] ); ?></p>
</section>
命令行
vendor/bin/blockstudio-phpstan -- --no-progress
Text
 [OK] No errors

将注释写成精确的结构。规范命令会在级别 max 运行 PHPStan,此时较宽泛的 @var array<string, mixed> $a 会被 varTag.nativeType 拒绝(“PHPDoc tag @var with type array<string, mixed> is not subtype of native type array{heading: string, subtitle: string}”)。在 7.6 中,它还会将每个字段扩宽为 mixed,因此每次 esc_html() 调用都会报告 argument.type。varTag.nativeType 消息会打印推断出的结构,因此也可以用它快速找到要复制的注释。

Blockstudio 7.7 将 $a 视为在区块模板内部已定义,因此 variable.undefined 诊断会消失,注释也变为可选。使用 7.7 时,上方的损坏模板会报告四个错误,而不是六个;修复后的模板则无需 @var 行即可通过。

选择预设

安装软件包只会启用基础扩展。除非项目选择其他预设,否则规范命令会运行 base;因此,添加依赖项本身不会启用更严格的层。

预设 增加的检查
base 在 PHP、Twig 和 Blade 中检查模板字段访问、区块标签检查、block.json、field.json、page.json 的架构验证、扩展 JSON、db.php、rpc.php 和 cron.php、Settings::get() 路径,以及 blockstudio/* 钩子名称。
theme 在基础预设上增加主题根目录和 style.css 标头、在 block.json 中声明而非手动入队的资源、style.scss 中的 %selector% 作用域、字段默认值和重复字段边界。
extreme-theme 在主题预设上增加严格的 PHPStan 标记、拒绝 shell 和 eval() 调用、原始 $wpdb 写入、输出转义、Tailwind、JavaScript 和 Interactivity API 检查。
wordpress-render 在极限主题预设上增加由你提供命令的实时渲染探测。

未包含项目配置时,规范命令还会运行 base 和 theme,并使用 PHPStan 级别 max;extreme-theme 会自行设置 max。每个预设诊断都有稳定的 blockstudio.* 标识符,列于 PHPStan 参考 中。

主题和极限层会检查 PHP 文件。若缺失字段未设置 default,且 script.js 会向控制台记录日志,同一命令会报告:

Text
 ------ -----------------------------------------------------------
  Line   blockstudio/hero/block.json
 ------ -----------------------------------------------------------
  1      Blockstudio field "subtitle" must define a default value.
         🪪  blockstudio.field.default
 ------ -----------------------------------------------------------

 ------ ------------------------------------------------------------
  Line   blockstudio/hero/script.js
 ------ ------------------------------------------------------------
  2      Remove debug output "console.log" from shipped JavaScript.
         🪪  blockstudio.javascript.debugOutput
 ------ ------------------------------------------------------------

这些检查通过 PHPStan 的结果缓存报告。仅编辑 block.json 或脚本后,热缓存可能会针对旧状态报告 [OK] No errors。在 -- 后传入 --debug 可绕过缓存;对于非 PHP 更改,在确认运行结果为绿色之前请先这样做:

命令行
vendor/bin/blockstudio-phpstan -- --no-progress --debug

命令选项和退出代码

命令行值会在单次运行中替换对应的 blockstudio.json 值。替换就是替换:传入任意 --exclude 都会移除已配置的 excludePaths,因此添加一项时要重复传入 vendor/**:

命令行
vendor/bin/blockstudio-phpstan \
  --preset theme \
  --root . \
  --exclude 'vendor/**' \
  --exclude 'fixtures/**' \
  --error-format json \
  -- --no-progress
Text
{"totals":{"errors":0,"file_errors":0},"files":{},"errors":[]}

-- 之后的所有内容都会传给 PHPStan。除非你传入自己的 --memory-limit,否则包装器会将 PHPStan 的内存限制提高到 1G;配置文件会在系统临时目录中组合生成,因此项目中不会留下生成文件。分析通过时退出码为 0,PHPStan 报告诊断信息时为 1,用法、配置或执行错误时为 2。

通过规范命令运行,而不是添加 phpstan/extension-installer。预设已包含扩展程序,且安装器存在时,同一个 extension.neon 会被加载两次:PHPStan 会在分析开始前因“此文件被多次包含”而停止。

在现有项目中采用

项目首次接受分析时通常会有检查发现。不要降低预设级别,而是将这些发现记录到基线中,以便新代码遵守全部规则:

命令行
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
Text
 [OK] Baseline generated with 3 errors.

在项目配置中包含基线,并将 phpstan.configuration 指向它:

Neon
includes:
    - phpstan-baseline.neon
JSON
{
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": ["vendor/**"],
    "configuration": "phpstan.neon"
  }
}

下一次运行会报告 [OK] No errors,同时保留已记录的发现;任何新增问题仍会导致失败。使用 base 或 theme 预设时,还要在 phpstan.neon 的 parameters 下设置 level: max:仅当未包含项目配置时,规范命令才会自行设置该级别。

将分析设为提交门禁

在 blockstudio.json 中配置 "githooks": { "commit": true } 后,安装依赖项后同步一次托管钩子:

命令行
vendor/bin/blockstudio-githooks sync
Text
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit

该命令会在 Git 自身的目录中写入钩子,将 core.hooksPath 指向该钩子,并串接之前配置的任何提交前钩子。钩子只会从项目根目录运行 vendor/bin/blockstudio-phpstan -- --no-progress,不会运行其他内容:不执行格式化程序,也不重写文件。提交前文所述的损坏模板时,分析会阻止提交:

Text
 [ERROR] Found 3 errors

Blockstudio: commit blocked by theme analysis.

将 commit 设为 false 并再次运行 sync,或者运行 vendor/bin/blockstudio-githooks remove,以恢复先前的钩子路径。 只会删除由 Blockstudio 写入的文件。

生成项目契约

分析会在事后告诉代理哪里做错了。AGENTS.md 则会事先告诉它:区块和页面位于何处、字段如何传入模板、启用了哪些功能,以及所选预设会拒绝哪些内容。 blockstudio-agents 会根据项目本身生成该文档:

命令行
vendor/bin/blockstudio-agents
Text
Blockstudio contract created: /path/to/acme/AGENTS.md

对于本指南中的主题,生成的文件开头如下:

Markdown
# Blockstudio contract for Acme

## Project

- Kind: WordPress theme `Acme`.
- Analysed root: `.`.
- Configuration: `blockstudio.json`.
- Analysis preset: `extreme-theme`.
- Excluded from discovery and analysis: `vendor/**`.

## What this project contains

- Blocks: 1 in `blockstudio`.
- Block namespaces: `acme`.
- Block templates are written in PHP.

每一行都来自三个来源之一。项目文件提供项目类型、计数、目录、命名空间和模板语言。 blockstudio.json 提供已启用的功能,因此提交钩子会出现在“已启用功能”下,而 vendor/bin/blockstudio-githooks sync 只有在设置了 githooks.commit 时才会出现在“命令”下。所选预设提供正确性部分,其内容按层逐层从预设文件中读取:

Markdown
The `theme` layer adds:

- Every analysed root must exist and carry a `style.css` with a `Theme Name` header.
- Block assets are declared in `block.json`; block code must not call `wp_enqueue_script()` or `wp_enqueue_style()`.
- A block `style.scss` must scope its rules through `%selector%`, and assets referenced by `block.json` must exist.
- Every field must define a `default`, and repeaters must declare non-negative `min` and `max` bounds.

保持内容最新

配置发生变化时,契约就会过时。在 blockstudio.json 中启用 Tailwind 后,检查模式会发现这一点:

命令行
vendor/bin/blockstudio-agents --check
Text
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.

它会以 1 退出,因此可以作为 CI 步骤与分析并列运行。重新生成后会添加“Tailwind CSS”功能条目和 wp bs tailwind compile 命令。

重新生成后仍保留的备注

文件末尾有一个备注区域。每次重新生成时,标记之间的所有内容都会逐字节保留,因此无法从文件推导出的项目知识应写在这里:

Markdown
## Project notes

Everything above is generated. Text between the markers below is preserved when this file is regenerated.

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

生成器不会替换它未写入的文件。若目标是手写的 AGENTS.md,生成器会拒绝操作并以 2 退出:

Text
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.

要保留手写内容,请先将其复制到别处,使用 --force 运行,然后粘贴到备注区域。其他选项包括 --root、--config、--output 和 --stdout;最后一项会打印契约而不是写入文件。

Blockstudio 7.7 中的变化

7.7 版软件包保留了此处介绍的命令、预设和退出代码。编写本指南并针对该版本验证时,发现了两项差异:如修复一节所述,$a 不再需要注释;生成的契约对区块标签验证的描述也更为全面,涵盖页面来源中映射到区块的 HTML 元素,以及标签可能转发的全局属性。

后续步骤

  • PHPStan 参考:每条规则、预设参数、字段类型结构、实时渲染探针和诊断标识符。
  • AI 集成:面向编码代理的文档索引,可补充你的项目契约。
  • 与 Blockstudio协同编程:在 Blockstudio 项目中与编码代理协作。
  • 字段模式手册:分析器能够理解模板键的字段结构,包括组和重复器。