Backport Builder API 参考

概览

Backport Builder 是构建工具，不是运行时函数库。它对外公开的接口包括：构建命令集（scripts/build.php 与其 composer build* 包装命令）、背后的四个脚本层类（Build、MergeSources、AdjustComposer、ValidateBuildContract）、三个 Rector 配置文件、三个自定义 Rector 规则，以及生成的包契约（nextpdf/backport 与 nextpdf/backport-pro）。你会在构建主机或 CI 主机上执行它，将现代 NextPDF 源代码转换为降版后的发行版。绝不要把它加入应用程序。

从这里开始：如果你是新手，先执行 composer build:dry（它会映射到 php scripts/build.php --dry-run）。它会以仅报告模式跑过每个阶段而不写入任何文件，因此你可以在真正构建前先确认源代码布局与标志。下面第一个「常见任务」示例展示的正是这一点。

常见任务

你使用这个包最常做的事，就是在构建主机上发起构建调用。下面每个示例都是单条命令，并已对照 scripts/build.php 与 composer.json 源代码验证过。

在不写入任何内容的情况下验证整条流程（适合作为安全的首次执行）：

composer build:dry

会映射到 php scripts/build.php --dry-run：它会以仅报告模式执行合并、Rector、composer 生成、资产复制与验证，且不会复制任何内容。

生成完整的 PHP 8.1 发行版（nextpdf/backport，以及在 Pro 源代码存在时的 nextpdf/backport-pro）：

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output

合并核心，加上 Framework（框架）适配器与 tcpdf 的 shim（兼容层），针对 PHP 8.1 目标执行单趟 Rector，并将生成的包树写入 ./output。加上 --no-pro 即可跳过 Pro 包。

生成仅核心的 PHP 7.4 发行版（两趟 enum 流程）：

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output-php74 \
  --target=php74

--target=php74 会强制只输出核心并停用 Pro，随后执行 enum 预处理、Rector 后修补，以及完整的 PHP 7.4 降版趟。

命令接口

当你需要构建入口点与驱动构建的脚本层类的确切签名、标志与退出行为时，请参考这张表。

符号	参数	默认行为	返回	抛出或失败条件	备注
`scripts/build.php`	目标、版本、源代码路径、输出路径，以及脚本记录的各项标志。	采用各分支特定的目标默认值。	生成的包树。	非零退出码与各阶段特定的错误输出。	主要构建入口点。在构建主机上执行，而不是在应用程序中执行。
`Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false)`	版本、源代码目录、输出目录、目标运行时通道、Pro 纳入标志、dry-run 标志。	PHP 8.1 目标，除 PHP 7.4 外均纳入 Pro，除非启用 dry-run，否则会写入。	`Build`	`InvalidArgumentException`：目标不支持时抛出；`run()` 执行期间发生阶段错误。	位于 `scripts/build.php` 背后的脚本层类。
`Build::run()`	无。	验证契约、合并源代码、调整 `composer.json` 元数据，并执行各趟 Rector。	`bool`	预期内的阶段失败会返回 `false`；非预期的 filesystem/runtime 错误则可能抛出异常。	CI 收到 `false` 时应视为失败。
`composer build:dry`	Composer 脚本包装命令。	Dry-run 构建验证。	退出状态与日志。	构建或验证失败时以非零退出码退出。	供 CI 把关使用。
`scripts/merge-sources.php`	源代码签出路径与合并目标。	为目标运行时合并选定的源代码包。	合并后的源代码树。	缺少源代码、目标不支持、文件系统失败。	让源代码引用与发布标签保持一致。
`MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false)`	源代码基目录、输出目录、Pro 纳入标志、dry-run 标志、仅核心标志。	合并所有已配置的仓库，或在 `coreOnly` 为 true 时只合并核心。	`MergeSources`	执行期间出现无效的源代码或输出路径。	位于 `scripts/merge-sources.php` 背后的脚本层类。
`MergeSources::run()`	无。	将选定的源代码树复制并规范化到构建目标。	`bool`	预期内的合并失败会返回 `false`。	日志可用 `getLog()` 读取。
`MergeSources::getLog()`	无。	返回累积的阶段日志项。	`array`	预期无。	用于 CI 诊断。
`scripts/adjust-composer.php`	生成的 `composer.json` 元数据与版本。	为生成的输出写入包约束条件与 replace 项目。	调整后的 `composer.json`。	版本无效或缺少已生成的文件。	负责生成包的标识信息。
`AdjustComposer::__construct(string $version, string $target = 'php81')`	版本字符串与目标通道。	PHP 8.1 目标。	`AdjustComposer`	目标无效时，或在生成路径中发生错误。	由构建脚本与测试使用。
`AdjustComposer::generatePublicComposer()`	无。	为 `nextpdf/backport` 生成元数据。	`array`	预期无。	供测试使用的纯生成 API。
`AdjustComposer::generateProComposer()`	无。	为 `nextpdf/backport-pro` 生成元数据。	`array`	预期无。	供专属构建通道使用的纯生成 API。
`AdjustComposer::writePublicComposer(string $outputDir)`	输出目录。	写入生成的公开 `composer.json`。	`void`	文件系统错误。	仅在生成的输出目录中使用。
`AdjustComposer::writeProComposer(string $proOutputDir)`	Pro 输出目录。	写入生成的 Pro `composer.json`。	`void`	文件系统错误。	需要 Pro 输出树已存在。
`ValidateBuildContract::__construct(string $repoRoot)`	仓库根目录。	以提供的仓库根目录作为契约基底。	`ValidateBuildContract`	预期无。	脚本层契约验证器。
`ValidateBuildContract::run()`	无。	检查必要输入与构建假设。	`bool`	契约失败时返回 `false`。	在信任构建输出前先执行。

Rector 配置

当你需要了解哪个 Rector 配置文件驱动哪条目标通道，以及每一趟在 PHP 8.1 单趟或 PHP 7.4 两趟流程中的位置时，请使用这张表。

符号	参数	默认行为	返回	抛出或失败条件	备注
`rector/config/rector-php81.php`	源代码树与 Rector 运行时。	单趟降版至 PHP 8.1 目标。	转换后的源代码。	Rector 解析或转换失败。	用于 PHP 8.1 发行通道。
`rector/config/rector-php74-enums.php`	源代码树与 Rector 运行时。	执行 enum 转换的 PHP 7.4 第一趟。	中间转换后的源代码。	Rector 解析或转换失败。	在完整 PHP 7.4 趟之前执行。
`rector/config/rector-php74.php`	中间源代码与 Rector 运行时。	完整的 PHP 7.4 降版趟。	PHP 7.4 兼容的源代码。	Rector 解析或转换失败。	用于 PHP 7.4 发行通道。

自定义规则

当你维护或扩展这三个项目特定的 Rector 规则，需要了解每条规则的方法契约与它转换的语法时，请参考这张表。

符号	参数	默认行为	返回	抛出或失败条件	备注
`DowngradeAsymmetricVisibilityRector`	使用非对称可见性的属性或提升参数。	与较旧运行时兼容的常规可见性。	在可能的情况下保留读取可见性。	Rector 规则失败。	setter 限制仅在编译期生效，并会从生成的输出中移除。
`DowngradeAsymmetricVisibilityRector::getRuleDefinition()`	无。	返回 Rector 规则的元数据与示例。	`RuleDefinition`	预期无。	让规则说明对 Rector 工具保持可见。
`DowngradeAsymmetricVisibilityRector::getNodeTypes()`	无。	选择规则要检查的节点类型。	`array<class-string<Node>>`	预期无。	范围应保持狭窄，以维持转换的确定性。
`DowngradeAsymmetricVisibilityRector::refactor(Node $node)`	AST 节点。	在出现非对称可见性的位置进行转换。	节点 `Node	null`	Rector 规则失败。
`DowngradeCloneWithRector`	`clone()` 搭配属性覆盖。	clone 加上明确的属性赋值。	使用生成的临时变量。	Rector 规则失败。	必须在 readonly 属性降版之后执行。
`DowngradeCloneWithRector::getRuleDefinition()`	无。	返回规则的元数据与示例。	`RuleDefinition`	预期无。	由 Rector 诊断使用。
`DowngradeCloneWithRector::getNodeTypes()`	无。	选择 return 与表达式节点。	`array<class-string<Node>>`	预期无。	让规则聚焦于 clone-with 语法。
`DowngradeCloneWithRector::refactor(Node $node)`	AST 节点。	把 clone-with 改写成 clone 加上赋值。	`array	null`	Rector 规则失败。
`DowngradeTraitConstantsRector`	Trait 常量及其引用。	静态属性与属性引用。	在可能的情况下保留可见性。	Rector 规则失败。	移除 `final`，因为较旧的属性无法声明为 final。
`DowngradeTraitConstantsRector::getRuleDefinition()`	无。	返回规则的元数据与示例。	`RuleDefinition`	预期无。	由 Rector 诊断使用。
`DowngradeTraitConstantsRector::getNodeTypes()`	无。	选择 trait 与类常量访问节点。	`array<class-string<Node>>`	预期无。	让规则限定于 trait 常量。
`DowngradeTraitConstantsRector::refactor(Node $node)`	AST 节点。	把 trait 常量及其引用改写为兼容的属性。	节点 `Node	null`	Rector 规则失败。

生成的包契约

用这张表查看构建器会产出什么：下游项目实际安装的包名称，以及由哪一个承载 Pro 发行版。

产出的包	执行期角色	备注
`nextpdf/backport`	生成的开源运行时发行版。	为目标运行时取代选定的 `nextpdf/*` 包。
`nextpdf/backport-pro`	在 Pro 源代码存在时生成的专属 Pro 发行版。	与开源包分开发布。

开发注意事项

构建器会以源代码发布版本作为输入，并产出生成产物。请勿把生成的输出当作事实来源来修补。
每个自定义规则在进入构建流程之前都必须具备 fixture 测试。
发布作业必须在目标运行时上验证生成的输出，而不只是在构建主机上验证。