
Blockstudio 7.2 沿着两个方向同时扩展了框架。

第一个方向是**单个项目中的可见性和工作流**：新增管理员概览、数据库浏览器、管理员注册表浏览器，以及用于共享 Sass 配置的 SCSS 前置代码。

第二个方向是**围绕 Blockstudio 的生态系统**：提供用于分发区块的注册表 CLI（类似于为 WordPress 打造的 shadcn），以及 PHPStan 扩展，为模板、区块标签、`db.php`、`rpc.php`、`cron.php` 和相关架构文件带来 TypeScript 风格的类型安全。

这两个方向都旨在解决同一件事：让大型 Blockstudio 项目更易于理解、扩展和共享。

## 管理体验

两项新增功能让你更容易在 wp-admin 中浏览大型项目。

### 管理员概览

Blockstudio 现在在 **工具 > Blockstudio** 下新增了一个管理页面。你可以在此统一查看系统从文件系统中注册的内容。

概览包含以下专用标签页：

- 区块
- 扩展
- 字段
- 页面
- 架构

除了概览之外，管理区域现在还设有专门的**数据库**板块。它会列出所有已注册的 `Blockstudio\Db` 架构，并允许你直接在 wp-admin 中查看实际记录。

该页面使用原生 WordPress DataViews 表格，而不是自定义面板网格。这样可以使 UI 与 wp-admin 保持一致，并在项目中有几十或上百个注册项时依然实用。

在小型安装中，你可以把运行时状态记在脑中。但在较大的代码库中，这就行不通了。你会开始提出这样的问题：

- 当前实际注册了哪些区块？
- 哪些扩展针对 `core/*`，哪些针对单独的区块？
- 哪些页面已同步？它们属于哪些文章类型？
- 项目中有哪些可复用字段？
- 注册了哪些架构？它们使用什么存储后端？

此前，你只能通过查看目录、打开 JSON 文件和逐步检查 PHP 来综合寻找答案。现在，概览将这些信息集中呈现在管理界面中。

每个标签页都旨在解答不同的问题：

- **区块**显示已注册的区块类型、渲染模式、API 版本和属性数量
- **扩展**显示其目标区块，以及优先级和渲染详情
- **字段**快速列出可复用的自定义字段定义
- **页面**显示基于文件且已同步的页面，包括文章类型、状态、模板引擎和同步状态
- **架构**显示已注册的存储架构，包括后端、字段数量和权限范围

数据库浏览器特意与初始概览负载分开。页面加载时不会序列化每一行数据，而是只预先本地化可用的架构，并在你打开数据库标签页时按需获取记录。这样，即使项目的数据集较大，管理界面也依然实用，数据集位于 `db.php` 后面。

此首个版本特意聚焦于由架构支持的注册项。它不是设置页面，而是检查页面。

如果你完全不需要它，可以彻底禁用：

```php
add_filter('blockstudio/admin/enabled', '__return_false');
```

### 管理后台注册表浏览器

概览旁边还有第二个标签页：**注册表**。它可以浏览主题的 `blocks.json` 中配置的远程区块注册表，并让你直接从 WordPress 管理后台导入区块，无需接触 CLI。

```json title="blocks.json"
{
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.example.com/registry.json",
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}
```

浏览器会获取每个已配置的注册表，列出所有可用区块，并显示这些区块是否已在本地安装或可供导入。每一行都有一个“导入”按钮，可将区块文件下载到主题中配置的目录。已安装的区块则会显示“重新导入”按钮。

支持经过身份验证的注册表，使用包含 `headers` 的对象格式，其中还支持 `${ENV_VAR}` 插值，因此令牌不会进入版本控制。

这样一来，浏览和使用注册表就成为管理后台的一等体验，而不只是 CLI 工作流。

## 注册表 CLI

注册表功能的另一部分是一个独立的 CLI：`blockstudio/registry`。

这是一个面向 WordPress 区块的 shadcn 风格工具。不需要 npm 包，也不需要构建步骤。运行命令后，区块源代码会复制到你的项目中，完全由你掌控。

```bash
npx blockstudio init
npx blockstudio add ui/tabs
```

CLI 适用于任何区块类型：Blockstudio 区块、`@wordpress/create-block` 输出、普通 PHP 区块。注册表不关心文件夹里有什么，只会读取 `registry.json` 中的文件清单，并准确复制其中列出的文件。

区块作者可以在任意 URL 发布一个 `registry.json`（GitHub 原始内容、S3 或自定义服务器），列出可用区块及其元数据、依赖项和文件清单。用户将 URL 添加到自己的 `blocks.json`，即可按名称拉取区块。

CLI 支持：

- **依赖解析**：区块可以声明对其他区块的依赖，系统会自动解析并检测循环依赖
- **多注册表冲突处理**：如果多个注册表中存在同名区块，CLI 会提示你选择其中一个
- **经过身份验证的注册表**：支持 bearer 令牌、基本身份验证和自定义标头，并支持环境变量插值
- **交互式 TUI**：使用 Ink 构建，包含旋转指示器、选择提示和进度指示器
- **非交互模式**：`--yes` 标志，以及 CI 和管道输入时的自动回退
- **搜索与列表**：从命令行浏览注册表

该包附带 130 个测试，涵盖架构、依赖解析、HTTP 获取、文件写入、所有命令流程以及交互式 Ink UI。

完整文档请参阅 [注册表blockstudio.dev/registry](https://blockstudio.dev/zh/registry/)。

## PHPStan 扩展

另一项重要新增内容是 `blockstudio/phpstan`：一个 PHPStan 扩展，为 Blockstudio 用户带来开发者所期待的类型安全 TypeScript。

```bash
composer require --dev blockstudio/phpstan
```

该扩展会在分析时读取项目的实际架构，并将生成的类型反馈给 PHPStan。现在涵盖 PHP 模板、Twig、Blade、区块标签、类型化数据库记录、设置路径、钩子名称，以及跨 `block.json`、`field.json`、扩展 JSON、`page.json`、`db.php`、`rpc.php`、`cron.php` 和 `blockstudio.json` 的架构验证。

### 类型安全的区块模板

对 `$a` 的字段访问会根据同级的 `block.json` 进行验证：

```php title="blockstudio/hero/index.php"
<?php
/** @var array<string, mixed> $a */

echo $a['title'];     // OK
echo $a['cta']['href']; // OK
echo $a['typo'];      // ERROR: Field "typo" does not exist in block.json (block: hero). Did you mean "title"?
```

### 类型安全的数据库记录

`Db::get()` 会根据你的 `db.php` 架构返回类型化实例。记录结构根据实际字段构建：

```php title="db.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']; // PHPStan: string
echo $record['name'];  // PHPStan: string|null
echo $record['typo'];  // ERROR: Offset 'typo' does not exist on array{id: int, email: string, name: string|null}
```

### 架构验证

无效的架构文件会在分析时被捕获：`block.json`、`field.json`、扩展 JSON、`page.json`、`db.php`、`rpc.php`、`cron.php` 和 `blockstudio.json`。缺少名称、字段类型错误、定义格式错误、已弃用的简写布尔值（`"tailwind": true`，而不是嵌套对象）都会报告源文件中的准确行号。

### 设置路径验证

`Settings::get()` 调用会根据已知的设置架构进行验证：

```php
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // ERROR: Settings path "tailwind/enabld" is not a known Blockstudio setting. Did you mean "tailwind/enabled"?
```

### 钩子名称验证

过滤器和操作钩子的名称也会进行同样的验证：

```php
add_filter('blockstudio/render', $cb);  // OK
add_filter('blockstudio/rendrr', $cb);  // ERROR: Unknown Blockstudio hook "blockstudio/rendrr". Did you mean "blockstudio/render"?
```

该扩展还为整个 Blockstudio 公共 API 提供存根：`Db`、`Settings`、`Field_Registry`、`Build` 以及全局辅助函数。无需在开发机器上安装插件源代码，即可获得所有 Blockstudio API 的自动补全和类型检查。

## 编写便利功能

另外还有两项较小的编写便利功能，为本次发布画上句号。

### 全局 SCSS 前置代码

Blockstudio 已支持 SCSS 编译，但有一个令人头疼的摩擦点：共享 Sass 设置。

如果你想使用一组通用变量、函数或混入，就必须在每个 SCSS 文件中导入它们。很快就会变得重复繁琐，尤其是在大型设计系统或像 Bootstrap 这样的 Sass 工具包中。

7.2 正好为此新增了一个前置代码钩子：

```php
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
  return '@import "functions";' . "\n"
    . '@import "variables";' . "\n"
    . '@import "mixins";';
}, 10, 3);
```

结合现有的 `blockstudio/assets/process/scss/import_paths` 过滤器，只需定义一次共享的 Sass 表面，就能让每个编译文件都使用它。

区块样式表可以专注于所需的实际样式：

```scss title="style.scss"
.hero {
  @include media-breakpoint-up(lg) {
    padding: 4rem;
  }
}
```

无需在每个区块资源中重复导入。这不是一种特殊的“Bootstrap 支持”模式，而是一个通用钩子，可在整个项目中共享 Sass，无论它来自 Bootstrap 还是你自己的内部工具包。

### PHP 原生区块 API 定义

7.2 还为全栈区块 API 新增了可选的 PHP 原生语法。数组仍是默认格式，并且完全受支持，没有任何内容被替换。不过，如果你更喜欢命名参数、枚举和属性，而不是嵌套配置数组，现在可以选择这种写法。

对于 `rpc.php`，返回一个包含带属性方法的对象：

```php title="rpc.php"
<?php
use Blockstudio\Attributes\Rpc;
use Blockstudio\Rpc\Access;
use Blockstudio\Rpc\Method;

return new class {
    #[Rpc(access: Access::Session)]
    public function subscribe(array $params): array {
        return ['success' => true];
    }

    #[Rpc(name: 'status', methods: [Method::Get, Method::Post])]
    public function getStatus(array $params): array {
        return ['status' => 'ok'];
    }
};
```

对于 `cron.php`，同样的思路也适用于 `#[Cron]`：

```php title="cron.php"
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

return new class {
    #[Cron(schedule: Schedule::Hourly)]
    public function heartbeat(): void {
    }
};
```

对于 `db.php`，现在还有一层简易构建器：

```php title="db.php"
<?php
use Blockstudio\Db\Field;
use Blockstudio\Db\Schema;
use Blockstudio\Db\Storage;

return Schema::make(
    storage: Storage::Table,
    fields: [
        'email' => Field::string(required: true, format: 'email'),
        'active' => Field::boolean(default: false),
    ],
);
```

这为较大的代码库带来了更好的平衡。你可以按需保留数组格式的简洁性；当区块的字段或端点超过几个时，也可以切换到更易于发现的 PHP 表面。

## 为何将这些内容一起发布

管理后台概览、注册表浏览器、注册表 CLI 和 PHPStan 扩展都在回答同一个问题：Blockstudio 项目不断扩展时，如何让它始终易于理解？

管理工具从项目层面回答这个问题：了解已注册的内容、从注册表引入区块，减少猜测。

CLI 从生态系统层面回答这个问题：让项目和团队能够共享区块，而不必将它们打包进 npm 包，也不必与构建系统周旋。

PHPStan 扩展从代码层面回答这个问题：在错误的字段访问、架构拼写错误和损坏的钩子回调进入运行时之前将其捕获。

这总体上就是 7.2 的方向：减少猜测和重复，提升可见性，并带来真正的类型安全。

## 错误修复

- **类字段**：用户输入的自定义类名在失去焦点时会被静默丢弃，因为验证器只接受预定义的 Tailwind/设置列表中的类名。现在任何非空字符串都可以通过。
- **属性字段**：移除一组属性后，保存的数据中仍残留 `null` 条目。已从 lodash `unset()`（会将数组元素置空）改为 `splice()`（会移除这些元素）。
- **CSS 压缩器**：TailwindPHP 压缩器会移除 `+` 周围的空白字符，涉及 `calc()` 和 `clamp()`，导致生成无效的 CSS，例如 `calc(1rem+0.5vw)`。已在上游 TailwindPHP v1.3.1 中修复：通过考虑嵌套深度的字符遍历，仅移除括号深度为 0 时选择器组合符周围的空白字符。
- **区块插入器预览**：在区块插入器预览中，`$isPreview` 始终为 `false`，因为渲染缓存的哈希键中未包含渲染模式。现在编辑器渲染和预览渲染会生成独立的缓存条目。
- **InnerBlocks 嵌套模板**：`<InnerBlocks template="..."/>` 组件会从类似 `['core/group', {}, [['core/paragraph']]]` 的模板元组中丢弃第三个元素（子项），导致容器区块为空。现在会保留嵌套子项。
