NextPDF Backport Builder 概覽
建置工具，而不是執行階段相依套件。NextPDF 維護者使用此套件產生與 PHP 8.1+ 和 PHP 7.4+ 相容的 NextPDF 發行版。應用程式絕不可將此套件加入執行階段相依套件。
NextPDF Backport Builder 是一套建置基礎設施，會為比開發基準更舊的 PHP 執行階段產生 NextPDF 生態系的 backport 發行版。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。 你安裝的成品是由此 builder 產生的
nextpdf/backport。builder 只會留在維護者或 CI 主機上。 - 你不是在產生出的程式碼上開發。 產生出的發行版是機器產生、唯讀的成品。請將錯誤回報與功能需求送至原始的
nextpdf/*原始碼儲存庫。 - 輸出會以版本標籤發行，而不是透過此儲存庫的分支發行。 發行流程會為產生出的目錄樹打標籤，並將封存檔附加到 GitHub release。
它會產生什麼
標題為「它會產生什麼」的區段builder 會輸出 Composer 套件；套件名稱與授權由 scripts/adjust-composer.php 固定：
| 產生的套件 | 授權 | 範圍 | 何時建置 |
|---|---|---|---|
nextpdf/backport | Apache-2.0 | Core，外加框架轉接器以及供 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 建置僅含 core。這一點已對照 scripts/adjust-composer.php（buildReplace()）驗證過。
使用者的自動載入器會透過單一 PSR-4 前綴解析合併後的目錄樹，也就是將 NextPDF\ 對應到 src/。PSR-4 會將命名空間前綴對應到一個基底目錄，並將每個完整限定類別名稱解析到該目錄下的對應檔案——參見 PHP-FIG PSR-4。Pro 套件則將 NextPDF\Pro\ 對應到它自己的 src/。
支援的 PHP 矩陣
標題為「支援的 PHP 矩陣」的區段下方矩陣只陳述 Rector 設定與建置指令碼強制要求的內容。建置主機一律執行現代 PHP，而輸出則以較舊的 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 目標範圍 | 僅 Core | scripts/build.php（--target=php74 強制僅 core，Pro 停用） |
PHP 8.1 建置會在 PHP 8.1、8.2、8.3 與 8.4 上驗證。PHP 7.4 建置會在 PHP 7.4 與 8.0 上驗證。這一點已對照 validate-php81 與 validate-php74 工作矩陣（位於 .github/workflows/build.yml）驗證過。這些是流程實際演練過的執行階段；它們是經觀察的驗證集合，並非符合性宣告。
雙分支模型
標題為「雙分支模型」的區段此儲存庫沒有 main 分支。PHP74 是預設分支，而 PHP81 是第二個永久分支。你所在的分支會決定兩件事：本機建置預設採用的目標，以及合併的是哪一組原始碼集。若變更同時影響兩個目標，會透過各自的 pull request 套用到每個分支。持續整合工作流程會同時在 PHP74 與 PHP81 上執行。這一點已對照 git branch -a 與 .github/workflows/0-ci.yml（branches: [PHP74, PHP81]）驗證過。
發行如何進行
標題為「發行如何進行」的區段發行路徑是事件驅動的。當 NextPDF 原始碼組織發布發行標籤時，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/ — 一個可執行的試跑與完整建置呼叫，皆有原始碼佐證。
- /integrations/backport/production-usage/ — 將 builder 接入發行工作流程。
- /integrations/backport/troubleshooting/ — 此流程防範的失敗模式，以及如何解讀它們。
- /integrations/backport/security-and-operations/ — 供應鏈態勢、信任邊界，以及維運保證。
- /integrations/backport/boot-and-discovery/ — builder 如何探索原始碼模組並啟動。
- /integrations/backport/integration/ — 建置主機整合合約。