Backport Builder API 參考

概覽

Backport Builder 是建構工具，不是執行期函式庫。它對外公開的介面包含：建構命令集（scripts/build.php 與其 composer build* 包裝命令）、背後的四個腳本層類別（Build、MergeSources、AdjustComposer、ValidateBuildContract）、三個 Rector 組態檔、三個自訂 Rector 規則，以及產生的套件契約（nextpdf/backport 與 nextpdf/backport-pro）。你會在建構主機或 CI 主機上執行它，將現代 NextPDF 原始碼轉換為降版後的散布版本。你絕不會把它加入應用程式。

從這裡開始：如果你剛開始使用，先執行 composer build:dry（它會對映到 php scripts/build.php --dry-run）。它會以僅報告模式執行每個階段而不寫入任何檔案，讓你可以在實際建構之前先確認原始碼目錄配置與旗標。下方第一個「常見任務」範例示範的就是這個流程。

常見任務

使用這個套件時，最常見的工作是在建構主機上發出建構呼叫。下方每個範例都是單一命令，並已對照 scripts/build.php 與 composer.json 原始碼驗證。

在不寫入任何內容的情況下驗證完整流程（安全的首次執行）：

composer build:dry

這會對映到 php scripts/build.php --dry-run：它會以僅報告模式執行合併、Rector、composer 產生、資產複製與驗證，不會複製任何內容。

產生完整的 PHP 8.1 散布版本（nextpdf/backport，以及在 Pro 原始碼存在時的 nextpdf/backport-pro）：

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

這會合併核心，加入 Framework（框架）轉接器與 tcpdf 的 shim（相容層），針對 PHP 8.1 目標執行單趟 Rector，並將產生的套件樹寫入 ./output。加上 --no-pro 即可略過 Pro 套件。

產生僅核心的 PHP 7.4 散布版本（兩趟 enum 流程）：

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

--target=php74 會強制只輸出核心並停用 Pro，接著執行 enum 前處理、Rector 後修補，以及完整的 PHP 7.4 降版趟。

命令介面

當你需要查詢建構進入點，以及驅動建構的腳本層類別其確切簽章、旗標與結束行為時，請參考這張表。

符號	參數	預設行為	回傳	擲出或失敗於	備註
`scripts/build.php`	目標、版本、原始碼路徑、輸出路徑，以及腳本所記載的各項旗標。	採用各分支特定的目標預設值。	產生的套件樹。	非零結束碼與各階段特定的錯誤輸出。	主要建構進入點。在建構主機上執行，而不是在應用程式中執行。
`Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false)`	版本、原始碼目錄、輸出目錄、目標執行期通道、Pro 納入旗標、dry-run 旗標。	PHP 8.1 目標；除 PHP 7.4 外皆納入 Pro；未啟用 dry-run 時會寫入。	`Build`	`InvalidArgumentException`：目標不支援時擲出；`run()` 執行期間發生階段錯誤。	支援 `scripts/build.php` 的腳本層類別。
`Build::run()`	無。	驗證契約、合併原始碼、調整 `composer.json` 中繼資料，並執行各趟 Rector。	`bool`	預期內的階段失敗會回傳 `false`；非預期的 filesystem/runtime 錯誤則可能擲出例外。	CI 收到 `false` 時應視為失敗。
`composer build:dry`	Composer 腳本包裝命令。	Dry-run 建構驗證。	結束狀態與日誌。	建構或驗證失敗時以非零結束碼結束。	供 CI 把關使用。
`scripts/merge-sources.php`	原始碼簽出路徑與合併目標。	為目標執行期合併選定的原始碼套件。	合併後的原始碼樹。	缺少原始碼、目標不支援、檔案系統失敗。	讓原始碼參照與發行標籤保持一致。
`MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false)`	原始碼基底目錄、輸出目錄、Pro 納入旗標、dry-run 旗標、僅核心旗標。	合併所有已設定的儲存庫，或在 `coreOnly` 為 true 時只合併核心。	`MergeSources`	執行期間出現無效的原始碼或輸出路徑。	支援 `scripts/merge-sources.php` 的腳本層類別。
`MergeSources::run()`	無。	將選定的原始碼樹複製並正規化至建構目標。	`bool`	預期內的合併失敗會回傳 `false`。	日誌可用 `getLog()` 讀取。
`MergeSources::getLog()`	無。	回傳累積的階段日誌項目。	`array`	預期無。	用於 CI 診斷。
`scripts/adjust-composer.php`	產生的 `composer.json` 中繼資料與版本。	為產生的輸出寫入套件約束條件與 replace 項目。	調整後的 `composer.json`。	版本無效或缺少已產生的檔案。	負責產生套件的識別資訊。
`AdjustComposer::__construct(string $version, string $target = 'php81')`	版本字串與目標通道。	PHP 8.1 目標。	`AdjustComposer`	目標無效，或產生路徑中發生錯誤。	由建構腳本與測試使用。
`AdjustComposer::generatePublicComposer()`	無。	為 `nextpdf/backport` 產生中繼資料。	`array`	預期無。	供測試使用的純產生 API。
`AdjustComposer::generateProComposer()`	無。	為 `nextpdf/backport-pro` 產生中繼資料。	`array`	預期無。	供專屬建構通道使用的純產生 API。
`AdjustComposer::writePublicComposer(string $outputDir)`	輸出目錄。	寫入產生的公開 `composer.json`。	`void`	檔案系統錯誤。	僅在產生的輸出目錄中使用。
`AdjustComposer::writeProComposer(string $proOutputDir)`	Pro 輸出目錄。	寫入產生的 Pro `composer.json`。	`void`	檔案系統錯誤。	需要 Pro 輸出樹已存在。
`ValidateBuildContract::__construct(string $repoRoot)`	儲存庫根目錄。	以提供的儲存庫根目錄作為契約基底。	`ValidateBuildContract`	預期無。	腳本層契約驗證器。
`ValidateBuildContract::run()`	無。	檢查必要輸入與建構假設。	`bool`	契約失敗時回傳 `false`。	在信任建構輸出之前先執行。

Rector 組態

當你需要確認哪個 Rector 組態檔驅動哪個目標通道，以及每一趟在 PHP 8.1 單趟或 PHP 7.4 兩趟流程中的位置時，請使用這張表。

符號	參數	預設行為	回傳	擲出或失敗於	備註
`rector/config/rector-php81.php`	原始碼樹與 Rector 執行期。	單趟降版至 PHP 8.1 目標。	轉換後的原始碼。	Rector 剖析或轉換失敗。	用於 PHP 8.1 散布通道。
`rector/config/rector-php74-enums.php`	原始碼樹與 Rector 執行期。	PHP 7.4 流程中進行 enum 轉換的第一趟。	中介轉換後的原始碼。	Rector 剖析或轉換失敗。	在完整的 PHP 7.4 趟之前執行。
`rector/config/rector-php74.php`	中介原始碼與 Rector 執行期。	完整的 PHP 7.4 降版趟。	PHP 7.4 相容的原始碼。	Rector 剖析或轉換失敗。	用於 PHP 7.4 散布通道。

自訂規則

當你維護或擴充這三個專案特定的 Rector 規則，並需要了解每個規則的方法契約與所轉換的語法時，請參考這張表。

符號	參數	預設行為	回傳	擲出或失敗於	備註
`DowngradeAsymmetricVisibilityRector`	使用非對稱可見性的屬性或提升參數。	與較舊執行期相容的一般可見性。	在可能的情況下保留讀取可見性。	Rector 規則失敗。	setter 限制只在編譯期生效，並會從產生的輸出中移除。
`DowngradeAsymmetricVisibilityRector::getRuleDefinition()`	無。	回傳 Rector 規則的中繼資料與範例。	`RuleDefinition`	預期無。	讓 Rector 工具能看見規則說明。
`DowngradeAsymmetricVisibilityRector::getNodeTypes()`	無。	選取規則要檢視的節點類型。	`array<class-string<Node>>`	預期無。	範圍應維持狹窄，以保持轉換的確定性。
`DowngradeAsymmetricVisibilityRector::refactor(Node $node)`	AST 節點。	轉換出現非對稱可見性的地方。	節點 `Node	null`	Rector 規則失敗。
`DowngradeCloneWithRector`	`clone()` 搭配屬性覆寫。	以 clone 加上明確的屬性指派。	使用產生的暫存變數。	Rector 規則失敗。	必須在 readonly 屬性降版之後執行。
`DowngradeCloneWithRector::getRuleDefinition()`	無。	回傳規則的中繼資料與範例。	`RuleDefinition`	預期無。	由 Rector 診斷使用。
`DowngradeCloneWithRector::getNodeTypes()`	無。	選取 return 與運算式節點。	`array<class-string<Node>>`	預期無。	讓規則聚焦於 clone-with 語法。
`DowngradeCloneWithRector::refactor(Node $node)`	AST 節點。	把 clone-with 改寫成 clone 加上指派。	`array	null`	Rector 規則失敗。
`DowngradeTraitConstantsRector`	Trait 常數及其參照。	靜態屬性與屬性參照。	在可能的情況下保留可見性。	Rector 規則失敗。	移除 `final`，因為較舊的屬性無法宣告為 final。
`DowngradeTraitConstantsRector::getRuleDefinition()`	無。	回傳規則的中繼資料與範例。	`RuleDefinition`	預期無。	由 Rector 診斷使用。
`DowngradeTraitConstantsRector::getNodeTypes()`	無。	選取 trait 與類別常數擷取節點。	`array<class-string<Node>>`	預期無。	將規則限定於 trait 常數。
`DowngradeTraitConstantsRector::refactor(Node $node)`	AST 節點。	把 trait 常數與其參照改寫成相容的屬性。	節點 `Node	null`	Rector 規則失敗。

產生的套件契約

用這張表查看建構器會產出什麼：下游專案實際安裝的套件名稱，以及哪一個套件承載 Pro 散布版本。

產出的套件	執行期角色	備註
`nextpdf/backport`	產生的開源執行期散布版本。	為目標執行期取代選定的 `nextpdf/*` 套件。
`nextpdf/backport-pro`	在 Pro 原始碼存在時產生的專屬 Pro 散布版本。	與開源套件分開發布。

開發注意事項

建構器會以原始碼發行版本為輸入，並產出產生的產物。請勿把產生的輸出當成事實來源來修補。
每個自訂規則在納入建構流程之前，都必須具備 fixture 測試。
發行作業必須在目標執行期上驗證產生的輸出，而不只是在建構主機上驗證。