NextPDF backport 集成

构建工具，而不是运行时依赖包。维护者使用此包生成 NextPDF 的 PHP 7.4 与 PHP 8.1 backport 发行版。应用程序绝不能把此包作为运行时依赖包加入。

概览

这里有两个截然不同的集成点。构建主机会把构建器仓库集成到发行流程中。下游应用程序会把生成的包 nextpdf/backport 集成到自己的依赖树中。构建器绝不会进入应用程序的依赖树。

安装（仅限构建主机）

构建器在 composer.json 中声明 "type": "project"，因此它是一个项目仓库，而不是函数库。请通过复制仓库并安装开发依赖的方式集成它，而不要使用 composer require：

git clone https://github.com/nextpdf-labs/backport.git
cd backport
git checkout PHP74
composer install --prefer-dist --no-progress

请检出与你要生成的目标对应的分支。针对仅包含 core 的 PHP 7.4 发行版，请使用 PHP74（默认值）。针对包含所有 adapter 的 PHP 8.1 发行版，请使用 PHP81。请勿传入 --no-dev。构建需要 Rector 引擎、PHPStan 与 PHPUnit，而它们都是开发依赖包。已对照 composer.json（type、require-dev）以及 /integrations/backport/overview/. 中的双分支模型加以验证。

启动与自动发现

没有框架自动发现机制。构建时，scripts/build.php 通过显式的 require_once 与 Composer PSR-4 自动加载，接入 Rector 与三条自定义抽象语法树规则。完整的启动顺序与来源模块发现记载于 /integrations/backport/boot-and-discovery/.

容器绑定

不适用。构建器是一个没有依赖注入容器的 CLI 工具。已对照仓库结构与 composer.jsonautoload 加以验证。

发布配置

「发布配置」并不是一个文件，而是一组构建标志，加上 scripts/adjust-composer.php 中的固定包定义：

• 目标对应表。 --target=php81 会生成 nextpdf/backport（约束条件 >=8.1 <8.5，会取代 core、各 adapter 以及 compat-legacy），并在包含 Pro 时生成 nextpdf/backport-pro。--target=php74 会生成 nextpdf/backport（约束条件 >=7.4 <8.1，仅取代 nextpdf/core），且不含 Pro。
• 排除。 --no-pro 会在 PHP 8.1 目标上排除 Pro 包。PHP 7.4 目标按设计会排除 Pro 与所有 adapter。
• 版本。 构建会将 --version（或去掉开头 v 后的发行标签）写入生成的 composer.json 与 CHANGELOG.md。

已对照 scripts/build.php 与 scripts/adjust-composer.php（generatePublicComposer()、generateProComposer()、buildReplace()）加以验证。完整的标志参考位于 /integrations/backport/configuration/.

发行流程集成

构建器通过 .github/workflows/ 中的 GitHub Actions 工作流程集成到发行流程中。0-ci.yml 会通过 PHPStan、规则测试与一次 dry-run，对任一永久分支上的每项变更进行把关。build.yml 会在 source-release repository-dispatch 事件或手动派发时，生成并发行该发行版。完整的运作模型——触发条件、各路径、验证矩阵以及共用的发行——记载于 /integrations/backport/production-usage/.

输出使用冒烟测试

发行管线本身就是集成冒烟测试。构建完成后，工作流程会将 runner 切换至目标 PHP，并对产出的源代码逐一执行 php -l。随后，它会在验证矩阵上安装并演练所生成的包（PHP 8.1 路径使用 PHP 8.1–8.4，PHP 7.4 路径使用 PHP 7.4 与 8.0）。会被目标运行时拒绝的发行版，不会进入正式发行。已对照 .github/workflows/build.yml（语法检查与 validate-* 作业）加以验证。你可以使用验证阶段打印的 Docker 命令，以相同方式对本机生成的输出进行冒烟测试——请参阅 /integrations/backport/quickstart/.

公开进入点

构建器的公开接口是 CLI 协调器及其 Composer 命令别名，而不是 bin/ 可执行文件。

进入点	解析为	用途
composer build	php scripts/build.php	完整构建
composer build:dry	php scripts/build.php --dry-run	Dry-run 构建
composer test	phpunit	规则 fixture 测试套件
composer analyse	phpstan analyse rector/rules scripts --level=10	对构建代码进行静态分析

已对照 composer.jsonscripts 加以验证。下游包的进入点就是原本的 NextPDF\ API 符号，backport 并未对其进行变更。该包会取代来源包，并通过单一 PSR-4 前缀自动加载合并后的树。

另请参阅

• /integrations/backport/overview/ — 构建器是什么，以及它会生成什么。
• /integrations/backport/boot-and-discovery/ — 启动顺序与来源发现。
• /integrations/backport/install/ — 构建主机与下游安装。
• /integrations/backport/production-usage/ — 发行管线。