跳到內容
NextPDF

NextPDF backport 啟動與探索

這是建置工具，而非執行階段相依套件。本文件說明建置器如何在維護者或 CI 主機上完成初始化啟動。下游應用程式絕不會載入這段程式碼。

概覽

標題為「概覽」的區段

建置器不使用框架、相依注入容器，也沒有服務提供者自動探索。它是一組 PHP CLI 指令稿，透過 require_once 與 Composer 的 PSR-4 自動載入器串接而成。在此，「探索」具體指兩件事：合併階段會讀取哪些原始碼儲存庫，以及協調器如何依目標選擇 Rector 設定。

建置流程總覽

標題為「建置流程總覽」的區段

協調器是 scripts/build.php。它會先啟動，接著依序執行五個階段。每個階段都有關卡控管，因此任一階段首次失敗時，就會停止建置：

  1. 合併原始碼 — 將各原始碼儲存庫複製到單一目錄樹中。
  2. 執行 Rector 降版 — PHP 8.1 只需單次處理；PHP 7.4 則需兩次處理，並另外套用修正。
  3. 產生 composer.json — 寫出產出的套件清單，並附上其 replace 對應表。
  4. 複製靜態資產 — 授權條款與產生的變更日誌。
  5. 驗證輸出 — 計算產出的 PHP 檔案數量；最具權威性的語法關卡則稍後在 CI 中執行。

已對照 scripts/build.php（run()、step()）驗證。規則選擇的細節在 /integrations/backport/configuration/；CI 關卡則在 /integrations/backport/production-usage/.

原始碼模組的探索

標題為「原始碼模組的探索」的區段

原始碼探索並非由清單檔驅動，而是依據 scripts/merge-sources.php 中的一份固定對應表；該表以儲存庫名稱為索引鍵，並依目標選定。

在 PHP 8.1 目標下，這份對應表包含 nextpdf（核心）、nextpdf-Artisan、nextpdf-compat-legacy、nextpdf-Laravel、nextpdf-Symfony、nextpdf-CodeIgniter，以及納入 Pro 時的 nextpdf-Pro。在 PHP 7.4 目標下，這份對應表會縮減為僅 nextpdf 一項。每個儲存庫都會解析到 --source-dir 根目錄下的同層目錄。每個預期的儲存庫都會在任何複製之前先行驗證；若有缺漏，便會中止合併並列出其名稱與路徑。已對照 scripts/merge-sources.php（MergeSources::__construct()、run()）驗證。

合併會把核心放在 src/，並將每個轉接器放在各自的命名空間子目錄下（src/Artisan/、src/Laravel/ 等）。Pro 會放進獨立的 pro/src/ 目錄樹，以便作為自己的套件產出。已對照 MergeSources（mergeCore()、mergeArtisan()、mergePro()）驗證。

啟動序列

標題為「啟動序列」的區段
  1. scripts/build.php 在 CLI SAPI 下被呼叫，並以 require_once 載入 merge-sources.php 與 adjust-composer.php。
  2. CLI 進入點會以 getopt() 讀取選項：--version、--source-dir、--output-dir、--target、--dry-run、--no-pro。
  3. 建構一個 Build 實例。建構函式會對照 ['php74', 'php81'] 驗證 --target，並在任何工作開始之前，對無效值拋出 InvalidArgumentException。在 PHP 7.4 目標下，它會強制只使用核心並停用 Pro。
  4. Build::run() 會執行這五個階段；成功時以狀態碼 0 結束，首次失敗時則以 1 結束。

已對照 scripts/build.php（CLI 進入點、Build::__construct()、run()）驗證。

容器繫結

標題為「容器繫結」的區段

不適用。建置器是一個 CLI 工具，沒有相依注入容器，也沒有框架服務容器。串接靠的是明確的 require_once，外加 Composer 對 NextPDF\Backport\（規則）與 NextPDF\Backport\Scripts\（指令稿）的 PSR-4 自動載入。已對照 composer.jsonautoload 與 scripts/build.php 中的 require_once 陳述式驗證。

設定解析順序

標題為「設定解析順序」的區段

沒有設定檔。設定就是這組 CLI 旗標，會依指令稿內建的預設值解析：

  1. CLI 旗標（若有提供）。
  2. getopt() 解析區塊中的預設值（例如，target 預設為 php81，version 預設為 2.0.0）。
  3. 建構函式依目標推導出的行為（PHP 7.4 會強制只使用核心並停用 Pro，與 --no-pro 無關）。

已對照 scripts/build.php（CLI 進入點與 Build::__construct()）驗證。完整的旗標參考在 /integrations/backport/configuration/.

診斷

標題為「診斷」的區段

協調器本身就是診斷介面。執行試跑（composer build:dry），便能在不寫入任何內容的情況下，印出將會讀取的原始碼儲存庫以及每個階段的意圖。每個階段都會印出成功的勾選標記，或帶有名稱的失敗訊息。沒有獨立的 diagnose 子命令，也沒有 bin/ 進入點。建置器是透過 scripts/build.php 或其 Composer 指令稿別名來呼叫。已對照 scripts/build.php（step()、dryRun 分支）、scripts/merge-sources.php（run() 試跑路徑），以及 composer.jsonscripts 驗證。

另請參閱

標題為「另請參閱」的區段
  • /integrations/backport/overview/ — 建置器是什麼，以及它會產出什麼。
  • /integrations/backport/integration/ — 建置主機的整合契約。
  • /integrations/backport/configuration/ — Rector 設定與旗標參考。
  • /integrations/backport/troubleshooting/ — 逐階段的失敗參考。