NextPDF Backport Builder 快速入門

這是建置工具，不是執行階段相依套件。本逐步教學會在維護者或持續整合（CI）主機上執行。下游專案使用的是這裡產出的封存檔。這些步驟絕不會在應用程式伺服器上執行。

概覽

你會執行三件事。首先是試跑（dry-run），用來在不變動任何檔案的情況下，證明整個流程已正確串接。接著進行完整的 PHP 8.1 建置，再進行完整的 PHP 7.4 建置。每個步驟都只需要一道指令。每道指令背後，都是一個 Composer 指令稿，或一次有文件記載的 scripts/build.php 呼叫。

先決條件

• 一台 PHP >=8.4 <9.0 的建置主機，並已安裝建置相依套件（composer install，不加 --no-dev）。請參閱 /integrations/backport/install/。
• 原始碼存放庫必須以同一個原始碼根目錄下的同層目錄方式取出。PHP 8.1 建置會讀取 nextpdf、nextpdf-Artisan、nextpdf-compat-legacy、nextpdf-Laravel、nextpdf-Symfony、nextpdf-CodeIgniter，以及 nextpdf-Pro（供 Pro 使用）。PHP 7.4 建置只讀取 nextpdf。已對照 scripts/merge-sources.php 驗證。

步驟 1 — 試跑（dry-run）

試跑會以只回報（report-only）模式執行每個階段。合併階段會列出它將複製的內容。Rector 會被宣告，但不會實際執行。composer 產生、資產複製與驗證階段會印出各自準備執行的動作。不會寫入任何內容。請先執行這一步，確認你的原始碼配置與旗標都正確，因為這是最快的檢查方式。

composer build:dry

composer build:dry 會解析為 php scripts/build.php --dry-run。已對照 composer.jsonscripts 與 scripts/build.php 驗證（也就是各階段中的 dryRun 分支）。在預設旗標下，目標是 php81，原始碼根目錄則使用指令稿預設值。如步驟 2 所示，兩者都可以覆寫。

如果試跑回報缺少某個原始碼存放庫，它會立即失敗並指出該存放庫名稱。繼續之前，請先修正原始碼配置。請參閱 /integrations/backport/troubleshooting/。

步驟 2 — 完整的 PHP 8.1 建置

PHP 8.1 建置會依序執行數個步驟。它會合併 core，以及各框架轉接器與 tcpdf 相容層。它會執行單趟（single-pass）的 Rector 設定。它會產生 nextpdf/backportcomposer.json。它會複製授權條款、寫入一份 CHANGELOG.md，並計算所產生的 PHP 檔案數量。

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output

已對照 scripts/build.php CLI 進入點驗證。五個階段會依序執行：合併原始碼、執行 Rector 降階、產生 composer.json、複製靜態資產、驗證輸出。每個階段成功時都會印出一個勾選符號。第一個失敗的階段會中止建置，並印出該階段的錯誤。若要排除 Pro，請加上 --no-pro。

成功時，協調器會印出耗用時間與輸出路徑。納入 Pro 時，也會印出 Pro 的輸出路徑。接著，輸出目錄會包含 src/、tests/、一份產生的 composer.json（其中宣告了 replace 對應表與 polyfill 需求）、LICENSE，以及 CHANGELOG.md。

步驟 3 — 完整的 PHP 7.4 建置

PHP 7.4 建置只包含 core，並執行兩趟（two-pass）流程。這幾趟分別是：enum 前處理、清除快取、Rector 後的修正，接著進行完整降階。

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output-php74 \
  --target=php74

已對照 scripts/build.php 驗證。在此，--target=php74 會強制只建置 core 並停用 Pro，而 runRector() 會選用兩趟路徑。產生的 composer.json 帶有 >=7.4 <8.1 這項限制，只取代 nextpdf/core，並在 8.2–8.5 的 polyfill 之上，再加入 PHP 8.0 與 8.1 的 polyfill。

步驟 4 — 讀取輸出

驗證階段會計算 output/src 中的 PHP 檔案數量，若數量為零就會失敗。它不會在本機執行語法檢查，因為本機直譯器是建置主機上的新版 PHP，而不是目標版本。它會印出 Docker 指令，供你對照真正的目標執行階段進行驗證。已對照 scripts/build.php（validateOutput()）驗證。

若要完整驗證，請在目標 PHP 下執行語法檢查。發行工作流程做的正是這件事：它會在 PHP 8.1（或 PHP 7.4）上對輸出進行語法檢查，接著在整個支援矩陣上安裝並實際操作。請參閱 /integrations/backport/production-usage/。

你建置出了什麼

產出物	由何者建置	版本限制	取代對象
nextpdf/backport（PHP 8.1）	步驟 2	>=8.1 <8.5	core + artisan + laravel + symfony + codeigniter + compat-legacy
nextpdf/backport-pro（PHP 8.1）	步驟 2，當納入 Pro 時	>=8.1 <8.5	nextpdf/pro
nextpdf/backport（PHP 7.4）	步驟 3	>=7.4 <8.1	nextpdf/core

已對照 scripts/adjust-composer.php 驗證。

後續步驟

• /integrations/backport/production-usage/ — 將這套流程串接到事件驅動的發行工作流程。
• /integrations/backport/configuration/ — 這些指令背後的規則與旗標參考。
• /integrations/backport/troubleshooting/ — 各類階段失敗及其意義。