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），並在納入時產生 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/ — 發行管線。