NextPDF Backport Builder 概览
构建工具——并非运行时依赖。NextPDF 维护者使用此包产出兼容 PHP 8.1+ 与 PHP 7.4+ 的 NextPDF 发行版。应用程序绝不能将此包添加为运行时依赖。
NextPDF Backport Builder 是一套构建基础设施，用于为早于开发基线的 PHP 运行时产出 NextPDF 生态的降级发行版。NextPDF 本身面向现代 PHP 版本编写，使用了较早解释器无法接受的语法。builder 通过 Rector（一个抽象语法树转换引擎）处理源码，并产出语法上可被 PHP 8.1 或 PHP 7.4 运行时接受的包。
该 Composer 包名为 nextpdf/backport-builder。它声明了 "type": "project"，且不包含任何 NextPDF 运行时依赖。它仅有的依赖项是构建引擎（rector/rector）、静态分析（phpstan/phpstan）、测试运行器（phpunit/phpunit），以及一组用于生成输出的 symfony/polyfill-* 包。这一点已通过对照仓库根目录中的 composer.json 核验。
此包不是什么
标题为“此包不是什么”的章节此仓库并不包含 NextPDF 引擎。它包含的是将引擎转换为 backport 形态的规则与脚本。因此可以明确三点边界：
- 你不会为了渲染 PDF 而安装它。 你安装的是
nextpdf/backport制品，它由此 builder 产出。builder 始终留在维护者或 CI 主机上。 - 你不会基于生成的代码进行开发。 生成的发行版是机器产出的只读制品。请将缺陷报告和功能请求提交到原始的
nextpdf/*源码仓库。 - 输出以版本标签形式发布，而不是作为此仓库的分支发布。 发布流水线会为生成的目录树打标签，并将归档附加到 GitHub release。
它产出什么
标题为“它产出什么”的章节builder 会产出 Composer 包；包名与许可证由 scripts/adjust-composer.php 固定确定：
| 产出的包 | 许可证 | 范围 | 何时构建 |
|---|---|---|---|
nextpdf/backport | Apache-2.0 | 核心，外加面向 PHP 8.1 目标的框架适配器与 tcpdf 兼容层 | 始终 |
nextpdf/backport-pro | proprietary | Pro 模块，作为独立的包产出 | PHP 8.1 目标，当存在 Pro 源码且未排除 Pro 时 |
nextpdf/backport 包声明了 Composer replace 条目，因此安装后即可满足原始包的约束。对于 PHP 8.1 目标，被替换的包为 nextpdf/core、nextpdf/artisan、nextpdf/laravel、nextpdf/symfony、nextpdf/codeigniter 与 nextpdf/compat-legacy。对于 PHP 7.4 目标，只有 nextpdf/core 会被替换，因为 PHP 7.4 构建仅包含核心。这一点已通过对照 scripts/adjust-composer.php（buildReplace()）核验。
使用方的自动加载器通过单一 PSR-4 前缀解析合并后的目录树，即将 NextPDF\ 映射到 src/。PSR-4 会将命名空间前缀映射到一个基目录，并将每个完全限定类名解析为该目录下的文件——参见 PHP-FIG PSR-4。Pro 包则将 NextPDF\Pro\ 映射到自己的 src/。
受支持的 PHP 矩阵
标题为“受支持的 PHP 矩阵”的章节下方矩阵仅说明 Rector 配置与构建脚本强制执行的内容。构建主机始终运行现代 PHP，而输出面向的是较旧版本。
| 关注点 | 值 | 证据 |
|---|---|---|
| 构建主机 PHP | >=8.4 <9.0 | composer.jsonrequire.php |
| CI build/test PHP | 8.5 | .github/workflows/0-ci.yml、build.yml（shivammathur/setup-phpphp-version: '8.5'） |
| PHP 8.1 目标输出约束 | >=8.1 <8.5 | scripts/adjust-composer.php（generatePublicComposer()） |
| PHP 7.4 目标输出约束 | >=7.4 <8.1 | scripts/adjust-composer.php（generatePublicComposer()） |
| PHP 8.1 目标范围 | Core + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy（+ Pro，独立） | scripts/merge-sources.php、scripts/adjust-composer.php |
| PHP 7.4 目标范围 | 仅核心 | scripts/build.php（--target=php74 强制仅核心，禁用 Pro） |
PHP 8.1 构建会在 PHP 8.1、8.2、8.3 与 8.4 上验证。PHP 7.4 构建会在 PHP 7.4 与 8.0 上验证。这一点已通过对照 .github/workflows/build.yml 中的 validate-php81 与 validate-php74 任务矩阵核验。这些是流水线实际运行所覆盖的运行时，是一组经过观测的验证集合，而不是合规性声明。
双分支模型
标题为“双分支模型”的章节此仓库没有 main 分支。PHP74 是默认分支，PHP81 是第二个常驻分支。当前所在分支决定两件事：本地构建默认面向哪个目标，以及会合并哪一组源码。同时影响两个目标的变更，会通过各自的拉取请求分别应用到每个分支。持续集成工作流会在 PHP74 与 PHP81 两个分支上运行。这一点已通过对照 git branch -a 与 .github/workflows/0-ci.yml（branches: [PHP74, PHP81]）核验。
一次发布是如何发生的
标题为“一次发布是如何发生的”的章节发布路径是事件驱动的。当 NextPDF 源码组织发布 release 标签时，类型为 source-release 的 repository-dispatch 事件会触发构建工作流。该工作流会在匹配标签处检出每个源码仓库，运行流水线，在目标运行时上对输出做语法检查，跨支持矩阵进行验证，并将归档附加到 GitHub release。版本标签遵循语义化版本控制——版本号是针对已声明公共 API 的 MAJOR.MINOR.PATCH（Semantic Versioning 2.0.0 §2）。这一点已通过对照 .github/workflows/build.yml 核验。
接下来去哪
标题为“接下来去哪”的章节- /integrations/backport/install/ —— 如何在构建主机上获取 builder，以及使用方如何安装产出的包。
- /integrations/backport/configuration/ —— Rector 配置、自定义规则与构建标志。
- /integrations/backport/quickstart/ —— 一个可运行的 dry-run 与完整构建调用，均有源码佐证。
- /integrations/backport/production-usage/ —— 将 builder 接入发布工作流。
- /integrations/backport/troubleshooting/ —— 流水线所防范的故障模式，以及如何解读它们。
- /integrations/backport/security-and-operations/ —— 供应链态势、信任边界与运维保证。
- /integrations/backport/boot-and-discovery/ —— builder 如何发现源码模块并启动。
- /integrations/backport/integration/ —— 构建主机集成契约。