跳转到内容
NextPDF

NextPDF backport 的启动与发现

这是构建工具，并非运行时依赖项。本文说明构建器如何在维护者或 CI 主机上初始化并启动。下游应用绝不会加载这段代码。

概览

标题为“概览”的章节

构建器不依赖框架，没有依赖注入容器，也没有服务提供者自动发现。它由一组 PHP CLI 脚本组成，通过 require_once 与 Composer 的 PSR-4 自动加载器串接起来。这里的「发现」具体指两件事：合并阶段会读取哪些源码仓库，以及编排器如何为目标选择 Rector 配置。

构建流水线总览

标题为“构建流水线总览”的章节

编排器是 scripts/build.php。它作为入口启动后，会按顺序执行五个阶段。每个阶段都有关卡管控，因此首次失败就会停止构建：

  1. 合并源码 — 将各源码仓库复制到单一目录树中。
  2. 执行 Rector 降版 — PHP 8.1 只需单次处理；PHP 7.4 则需要两次处理并额外修正。
  3. 生成 composer.json — 写出产物的软件包清单，并附上其 replace 映射表。
  4. 复制静态资产 — 许可证与生成的变更日志。
  5. 验证输出 — 统计产出的 PHP 文件数量；最具权威性的语法关卡会稍后在 CI 中执行。

已对照 scripts/build.php（run()、step()）验证。规则选择的细节见 /integrations/backport/configuration/；CI 关卡见 /integrations/backport/production-usage/.

源码模块的发现

标题为“源码模块的发现”的章节

源码发现并非由清单文件驱动，而是依靠 scripts/merge-sources.php 中的一份固定映射表；该表以仓库名称为键，并按目标选定。

对于 PHP 8.1 目标，这份映射表包含 nextpdf（核心）、nextpdf-Artisan、nextpdf-compat-legacy、nextpdf-Laravel、nextpdf-Symfony、nextpdf-CodeIgniter，以及纳入 Pro 时的 nextpdf-Pro。对于 PHP 7.4 目标，这份映射表会缩减为仅 nextpdf 一项。每个仓库都会被解析为 --source-dir 根目录下的同级目录。每个预期仓库都会在复制开始前先行验证；若有缺失，合并会中止，并列出其名称与路径。已对照 scripts/merge-sources.php（MergeSources::__construct()、run()）验证。

合并时会把核心放入 src/，并将每个适配器放入各自的命名空间子目录（src/Artisan/、src/Laravel/ 等）。Pro 会放入独立的 pro/src/ 目录树，以便以其自身的软件包形式产出。已对照 MergeSources（mergeCore()、mergeArtisan()、mergePro()）验证。

启动序列

标题为“启动序列”的章节
  1. scripts/build.php 在 CLI SAPI 下调用。它会通过 require_once 加载 merge-sources.php 与 adjust-composer.php。
  2. CLI 入口点使用 getopt() 读取选项：--version、--source-dir、--output-dir、--target、--dry-run、--no-pro。
  3. 构造一个 Build 实例。构造函数会将 --target 对照 ['php74', 'php81'] 验证，并在任何工作开始之前，对无效值抛出 InvalidArgumentException。对于 PHP 7.4 目标，它会强制只用核心并停用 Pro。
  4. Build::run() 会执行上述五个阶段，成功时以状态码 0 结束，首次失败时则以 1 结束。

已对照 scripts/build.php（CLI 入口点、Build::__construct()、run()）验证。

容器绑定

标题为“容器绑定”的章节

不适用。构建器是一个 CLI 工具，没有依赖注入容器，也没有框架服务容器。接线由明确的 require_once，以及 Composer 对 NextPDF\Backport\（规则）与 NextPDF\Backport\Scripts\（脚本）的 PSR-4 自动加载完成。已对照 composer.jsonautoload 与 scripts/build.php 中的 require_once 语句验证。

配置解析顺序

标题为“配置解析顺序”的章节

没有配置文件。配置就是这组 CLI 标志，并会对照脚本内置的默认值解析：

  1. CLI 标志（如果提供）。
  2. getopt() 解析块中的默认值（例如，target 默认为 php81，version 默认为 2.0.0）。
  3. 构造函数从目标推导出的行为（PHP 7.4 会强制只用核心并停用 Pro，与 --no-pro 无关）。

已对照 scripts/build.php（CLI 入口点与 Build::__construct()）验证。完整的标志参考见 /integrations/backport/configuration/.

诊断

标题为“诊断”的章节

编排器本身就是诊断接口。执行试运行（composer build:dry），即可在不写入任何内容的情况下，打印将要读取的源码仓库以及每个阶段的意图。每个阶段都会打印成功的对勾标记，或具名的失败消息。没有独立的 diagnose 子命令，也没有 bin/ 入口点。构建器通过 scripts/build.php 或其 Composer 脚本别名调用。已对照 scripts/build.php（step()、dryRun 分支）、scripts/merge-sources.php（run() 试运行路径），以及 composer.jsonscripts 验证。

另请参阅

标题为“另请参阅”的章节
  • /integrations/backport/overview/ — 构建器是什么，以及会产出什么。
  • /integrations/backport/integration/ — 构建主机的集成契约。
  • /integrations/backport/configuration/ — Rector 配置与标志参考。
  • /integrations/backport/troubleshooting/ — 逐阶段的失败参考。