安装 NextPDF Backport 构建器

构建工具，并非运行时依赖。此构建器安装在维护者的工作站或 CI 运行器上。下游应用永远不会安装此构建器；它安装的是构建器生成的包。

概览

两类受众需要安装的内容不同：

维护者或 CI 操作员克隆此仓库并安装它的构建依赖。只有这种场景会安装 nextpdf/backport-builder。
在较旧 PHP 运行时上运行的下游应用从其发布渠道安装生成的 nextpdf/backport 包。该应用永远不会接触此仓库。

本页面同时涵盖这两种场景。请阅读与你的角色相符的章节。

构建主机安装

要求

依赖	约束	权威来源
PHP	`>=8.4 <9.0`	`composer.jsonrequire.php`
Composer	2.6+	`CONTRIBUTING.md` 环境表
`rector/rector`	`^2.0`	`composer.jsonrequire-dev`
`phpstan/phpstan`	`^2.1`	`composer.jsonrequire-dev`
`phpunit/phpunit`	`^13.0`	`composer.jsonrequire-dev`

持续集成工作流为构建作业和试运行作业均配置 PHP 8.5。构建主机只要 PHP 版本处于 >=8.4 <9.0 范围内，即满足该 Composer 约束。解析器必须能够接受源代码所使用的最新语法。已对照 .github/workflows/0-ci.yml 核实。

步骤

克隆此仓库，并检出与你计划构建的目标对应的分支。PHP74 是默认分支；它生成仅包含核心的 PHP 7.4 发行版。PHP81 生成包含所有适配器的 PHP 8.1 发行版。
Terminal window
```
git clone https://github.com/nextpdf-labs/backport.git
cd backport
git checkout PHP74
```
安装构建依赖。不要传入 --no-dev：Rector 引擎、PHPStan 和 PHPUnit 都位于 require-dev 中；缺少它们，构建无法运行。
Terminal window
```
composer install --prefer-dist --no-progress
```
确认工具链可以正常解析。analyse 脚本会以级别 10 对 rector/rules 和 scripts 运行 PHPStan。一次无报错的运行，可以在你生成任何输出之前证明构建代码本身可靠。
Terminal window
```
composer analyse
```
运行规则夹具测试。每条自定义 Rector 规则都有对应的夹具套件，用于断言精确的 before/after 转换。
Terminal window
```
composer test
```

完成第 4 步后，此主机即可开始构建。前往 /integrations/backport/quickstart/ 了解如何调用试运行和完整构建。

源码树预期

构建过程会将多个源仓库合并到一个目录树中。合并脚本期望这些仓库以同级目录形式位于同一个源根目录下，并按名称寻址。对于 PHP 8.1 目标，它会读取 nextpdf（核心）、nextpdf-Artisan、nextpdf-compat-legacy、nextpdf-Laravel、nextpdf-Symfony、nextpdf-CodeIgniter；若包含 Pro，还会读取 nextpdf-Pro。对于 PHP 7.4 目标，它仅读取 nextpdf。已对照 scripts/merge-sources.php（MergeSources::__construct()）核实。使用 --source-dir 指定源根目录。有关参数说明，参见 /integrations/backport/configuration/。

下游项目使用生成的包

在较旧 PHP 运行时上运行的项目，安装的是所生成的发行版，而不是此构建器。

PHP 8.1 至 8.3

composer require nextpdf/backport

所安装的包带有约束 >=8.1 <8.5，并替换 nextpdf/core、nextpdf/artisan、nextpdf/laravel、nextpdf/symfony、nextpdf/codeigniter 和 nextpdf/compat-legacy。应用代码仍按原样导入 NextPDF\ 命名空间。该包使用单一 PSR-4 前缀 NextPDF\（映射到 src/）自动加载合并后的目录树。PSR-4 自动加载器会将相对类名追加到为该前缀注册的基目录之后（PHP-FIG PSR-4）。已对照 scripts/adjust-composer.php（buildPublicAutoloadMap()、buildReplace()）核实。

PHP 7.4 至 8.0

composer require nextpdf/backport

PHP 7.4 发行版仅含核心。它带有约束 >=7.4 <8.1，且仅替换 nextpdf/core。框架适配器、tcpdf 兼容层以及 Pro 都不属于 PHP 7.4 发行版。已对照 scripts/adjust-composer.php 和 scripts/build.php 核实（PHP 7.4 目标强制仅含核心）。需要框架适配器的项目需使用 PHP 8.1 或更新版本。

Pro

composer require nextpdf/backport-pro

Pro 发行版是一个独立的包 nextpdf/backport-pro，采用 proprietary 许可证。它要求 nextpdf/backport 的 major.minor 与之匹配，并额外添加 phpseclib/phpseclib ^3.0。它仅为 PHP 8.1 目标生成。已对照 scripts/adjust-composer.php（generateProComposer()）核实。

PHP 7.4 发行版与 Pro 发行版互斥：受构建脚本的构造方式限制，不存在 PHP 7.4 的 Pro 构建。

所生成包中的 polyfill

生成的 composer.json 要求 symfony/polyfill-* 包，以便较新的标准库函数能够在目标运行时中解析。PHP 8.1 目标需要 PHP 8.2 到 8.5 的 polyfill。PHP 7.4 目标还需要额外的 PHP 8.0 和 8.1 的 polyfill。这些是所生成包的运行时依赖，而不是构建器的依赖。已对照 scripts/adjust-composer.php（generatePublicComposer()）核实。

下一步

/integrations/backport/configuration/ —— Rector 配置、自定义规则以及构建参数说明。
/integrations/backport/quickstart/ —— 首次试运行与完整构建。