安裝 NextPDF Backport Builder

這是建置工具，不是執行階段相依套件。這個建置器應安裝在維護者的工作站或 CI runner 上。下游應用程式絕不會安裝這個建置器；它只會安裝建置器產生的套件。

概覽

兩種對象會安裝不同的項目：

維護者或 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
```
執行規則 fixture 測試。每一條自訂 Rector 規則都有一套 fixture 測試，用來斷言確切的 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\ 命名空間，不需要更動。該套件透過映射到 src/ 的單一 PSR-4 前綴 NextPDF\，自動載入合併後的樹狀結構。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 授權。它需要相符 major.minor 的 nextpdf/backport，並額外加入 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/ —— 首次試跑與完整建置。