PHPStan

概览

NextPDF Enterprise 发行一条自定义 PHPStan 规则 EditionBoundaryRule，用于标记跨越 Core → Pro → Enterprise 版本边界的 use 导入。它是一项面向开发者的静态检查，会报告违规；它分析的是导入语句，并不保证你代码的正确性。

可用性与授权

此能力发行于 NextPDF Enterprise（nextpdf/enterprise）中，并随 Enterprise 层级的授权信封激活。它是一条通过你的 PHPStan 配置注册的构建时 PHPStan 规则，因此它在静态分析期间运行，没有运行时路径；授权闸门就是 nextpdf/enterprise 软件包边界，没有单独的每功能能力代码。比较版本并获取授权。

安装

composer require nextpdf/enterprise:^3

在你的 PHPStan 配置中注册该规则：

rules:
    - NextPDF\Enterprise\PHPStan\EditionBoundaryRule

概念概述

该规则检查每条 use 语句，并将导入方的命名空间与被导入符号的命名空间前缀进行比较。它强制执行一种单向依赖顺序：

• Core 代码（NextPDF\，但不含 Pro 与 Enterprise 子命名空间）不得从 NextPDF\Pro\* 或 NextPDF\Enterprise\* 导入。
• Pro 代码（NextPDF\Pro\*）不得从 NextPDF\Enterprise\* 导入。
• Enterprise 代码（NextPDF\Enterprise\*）是最高层级，可以从其中任意一层导入。

当某次导入跨越边界时，该规则会报告一条错误，标识符为 nextpdf.editionBoundaryViolation，并附带一条消息，说明导入方的命名空间、被禁止的前缀，以及人类可读的版本标签。该检查纯粹是静态的：它在分析时读取导入图。

为何以这种方式工作

该规则在分析时对 use 语句进行推断，而非在运行时，因为版本边界是一项架构不变量，而不是运行时决策。Core、Pro 与 Enterprise 作为独立软件包发行，因此较低层级绝不应依赖在较小安装中不存在的符号。在静态分析期间捕获一次跨越边界的导入，会在这一错误出货之前让构建失败。另一种做法更糟：同一次导入随后会在仅含 Core 的部署中，表现为一个致命的缺失类错误。这种顺序刻意是单向的，Core → Pro → Enterprise，映射了 open-core 软件包如何层层叠加。Enterprise 保持不受约束，因为它是最高层级，可以引用其下的每一个版本。

设计背景：开放内核，无锁定。

API 表面

类	职责
EditionBoundaryRule	作用于 use 语句的 PHPStan 规则；报告版本边界违规。

该规则在 Use_ 节点类型上实现标准的 PHPStan Rule 契约，并在 nextpdf.editionBoundaryViolation 标识符下发出错误。

代码示例——快速开始

# phpstan.neon
includes:
    - vendor/nextpdf/enterprise/phpstan.neon.dist

代码示例——生产环境

# phpstan.neon
rules:
    - NextPDF\Enterprise\PHPStan\EditionBoundaryRule

parameters:
    level: 9
    paths:
        - src

举例来说，一次违规会在 PHPStan 输出中呈现为：Core 代码内部的一次 Enterprise 导入，会在违规的那条 use 行上，于 nextpdf.editionBoundaryViolation 下被报告为一次版本边界违规。

边界情况与陷阱

• 该规则推断被分析文件的命名空间与被导入符号的前缀。位于非 NextPDF\ 命名空间的代码不受此规则约束。
• 按设计，Enterprise 命名空间不受限制；该规则绝不会因为某个 Enterprise 文件导入了 Pro 或 Core 而标记它。
• 该规则分析的是 use 语句。一个内联写出、未使用 use 的全限定类引用不在此规则的范围内；请优先使用导入，以便边界得到强制执行。
• 该检查是静态且建议性的：它报告边界违规。它并不证明你的程序在其他方面是正确的。

性能

该规则在 PHPStan 分析期间对每条 use 语句运行，并执行字符串前缀比较。它的开销与导入语句的数量成正比，相对于整体分析时间可以忽略不计。

安全说明

这是一条静态分析规则。它在构建时于 PHPStan 内部执行，仅读取源码结构，对生成的 PDF 没有运行时影响。

数据驻留与 PII 缓解

该规则在分析时处理源代码，不处理任何文档数据或个人数据。

安全遥测与日志清洗

规则的输出是 PHPStan 诊断信息。它包含来自你自己代码的命名空间与符号名称；请像对待你的源码一样谨慎对待分析日志。

符合性

不声明任何标准符合性。这是一条开发者工具规则，用于在下游构建中强制执行一项内部架构约束（版本分层）。

FIPS 模式行为

不适用；该规则不执行任何密码学操作，也没有运行时路径。

威胁模型

并非运行时组件。该规则的目的是在出货前，通过让静态分析阶段失败，来捕获一类架构错误——一次版本边界导入。

行为契约

• 该规则检查每条 use 语句，并强制执行一种单向依赖顺序：Core 不得导入 Pro 或 Enterprise；Pro 不得导入 Enterprise；Enterprise 可以导入任意一层。
• 一次跨越边界的导入会在 nextpdf.editionBoundaryViolation 标识符下被报告，并附带导入方的命名空间与被禁止的前缀。
• 位于非 NextPDF\ 命名空间的代码不受此规则约束。
• 一个未使用 use 的内联全限定类引用不在此规则的范围内；请优先使用导入，以便边界得到强制执行。

发布边界

本页仅记录外部可观察的行为以及受支持的公共 API 表面。内部命名空间路径、辅助类、机制表、运行手册文件名以及工单前缀均不在范围内。

Core 回退

NextPDF Core 不发行版本边界 PHPStan 规则。一个仅使用 Core 的消费方若想在自己的构建中强制执行版本分层，必须自行编写或取得一条等效规则。

Pro 回退

NextPDF Pro 不发行版本边界 PHPStan 规则；它仅属于 nextpdf/enterprise 软件包。一个仅部署 Pro 的环境没有可用于注册此规则的 Enterprise 组件。Enterprise 表面请参阅 Enterprise 概述。

Enterprise 边界说明

内部机制细节留存于源码仓库的内部文档中，不在本手册的范围内。

部署边界

这是一条构建时的静态分析规则。它在分析期间于 PHPStan 内部执行，仅读取源码结构，对生成的 PDF 或任何已部署的服务没有运行时影响。注册它以及选择 PHPStan 级别是集成方的责任。

法律合规边界

本页描述的是一条开发者工具静态分析规则。它不对你的代码作出任何合规、认证或正确性保证；它仅报告版本边界导入违规，且是建议性的。它不构成法律意见。判断你的构建是否满足你自己的架构或合同义务是你的责任。

另请参阅

• PHPStan——深度参考
• Enterprise 概述
• Core、Pro 与 Enterprise 功能对照表