TCPDF 相容性開發者指南
快速概覽
標題為「快速概覽」的區段相容性配接器是一個移轉層。它應該讓舊版行為保持可見，而不是把它藏起來。用它讓應用程式持續運作，同時把高價值路徑移轉到原生 NextPDF API。
當你在維護 TCPDF 形式的舊版程式碼、擴充配接器覆蓋範圍，或規劃分階段移轉到原生 NextPDF API 時，請使用本指南。
架構邊界
標題為「架構邊界」的區段| 分層 | 擁有者 | 職責 | 不要放在這裡 |
|---|---|---|---|
| 舊版應用程式 | 應用程式 | 在移轉期間維持現有 TCPDF 形式的呼叫運作。 | 應改用原生 NextPDF API 的新 PDF 功能。 |
| 配接器外殼 | nextpdf/compat-legacy | 公開 TCPDF 形式的類別與共用相容性狀態。 | 大型方法群組或轉換邏輯。 |
| 關注點 trait | nextpdf/compat-legacy | 依舊版方法群組分類：文字、字型、影像、安全性、表單、頁面。 | 跨群組的輸出政策。 |
| 橋接類別 | nextpdf/compat-legacy | 轉換舊版引數、目的地、色彩、單位與格式。 | 業務專屬的行為。 |
| 核心引擎 | nextpdf/nextpdf | 產生原生文件。 | 舊版相容性承諾。 |
執行階段生命週期
標題為「執行階段生命週期」的區段| 階段 | 行為 | 開發者動作 |
|---|---|---|
| 啟動 | 選用的舊版啟動程序會公開相容性名稱。 | 僅在舊版程式碼預期有 TCPDF 符號的地方使用。 |
| 建構 | 舊版建構式引數會被調整為核心文件組態。 | 在移轉期間保持建構式輸入穩定。 |
| 方法呼叫 | 支援的方法會透過關注點與橋接，對映到 NextPDF 行為。 | 先檢查方法覆蓋範圍，再假設行為對等。 |
| 不支援的功能 | 不支援的行為會擲出明確的相容性例外。 | 替換該呼叫，或將它隔離在應用程式程式碼後方。 |
| 輸出 | 輸出橋接會把舊版目的地行為對映到 NextPDF 輸出。 | 驗證檔名與儲存根目錄。 |
移轉盤點
標題為「移轉盤點」的區段先蒐集應用程式中的每一個 TCPDF 方法呼叫。變更行為前，先把每個呼叫分類。
| 分類 | 意義 | 動作 |
|---|---|---|
| 支援的配接器方法 | 方法已列為支援，並有測試。 | 暫時保留，之後觸及該區域時再移轉。 |
| 部分支援的配接器方法 | 方法存在，但行為尚未完全對齊舊版 TCPDF。 | 加上 fixture 測試，並手動驗證輸出。 |
| 明確不支援的方法 | 配接器會擲出相容性例外。 | 改用原生 NextPDF，或移除該功能。 |
| 業務專屬包裝 | 應用程式已經把 TCPDF 呼叫包裝起來。 | 先移轉包裝內部。 |
| 合規敏感的呼叫 | 簽章、加密、標記、PDF/A、無障礙或發票流程。 | 移轉到原生 NextPDF API，並進行專屬驗證。 |
配接器貢獻模式
標題為「配接器貢獻模式」的區段把相容性支援加在實際擁有該行為的最小方法群組中。
| 變更類型 | 在何處實作 | 必要測試 |
|---|---|---|
| 文字輸出方法 | Concerns\AdaptsTextOutput 或字型關注點。 | 舊版 fixture，以及原生輸出斷言。 |
| 頁面或邊界方法 | 頁面、定位或邊界關注點。 | 座標轉換與頁面狀態測試。 |
| 影像或繪圖方法 | 影像、繪圖、色彩或漸層關注點。 | 輸入驗證與 visual/structural 輸出測試。 |
| 輸出目的地 | OutputBridge。 | 目的地對映與不安全路徑測試。 |
| 不支援的功能 | 例外工廠或方法覆蓋表。 | 例外類型與訊息測試。 |
若某個關注點 trait 已擁有該群組，不要把大型方法直接加進配接器外殼。
原生移轉模式
標題為「原生移轉模式」的區段先用配接器穩定現況，再把穩定的工作流程移到原生 API。
<?php
// Temporary compatibility code.$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();$pdf->AddPage();$pdf->SetFont('dejavusans', '', 12);$pdf->Cell(0, 10, 'Invoice 1234');
// Target native shape.$document = \NextPDF\Core\Document::createStandalone();$document->addPage() ->setFont('dejavusans', '', 12) ->cell(0, 10, 'Invoice 1234');把移轉視為一連串小型的行為變更。即使某個高風險區段移到原生 API，頁面仍然可以使用配接器。
擴充點
標題為「擴充點」的區段| 擴充點 | 用途 | 限制 |
|---|---|---|
AdaptationConfig | 在移轉期間控制配接器行為。 | 讓預設值保持經過檢視且明確。 |
| 關注點 trait | 組織方法群組，例如文字、表單、影像或安全性。 | 把方法加到適當的關注點，而不是配接器外殼。 |
| 橋接類別 | 把舊版引數形式轉換為核心值。 | 讓橋接行為持續受到移轉測試覆蓋。 |
CompatAdapterInterface | 供工具使用的配接器層級抽象。 | 在新程式碼中，不要用它來取代原生核心契約。 |
| 方法覆蓋表 | 供開發者查閱的支援帳本。 | 在支援狀態變更時更新。 |
移轉工作流程
標題為「移轉工作流程」的區段- 安裝配接器，並原封不動執行舊版測試套件。
- 開啟方法覆蓋，並把每個被呼叫的方法分類。
- 先替換不支援的方法。
- 把高流量或合規敏感路徑移到原生核心 API。
- 為每個已移轉的方法群組加上 fixture 覆蓋範圍。
- 當沒有應用程式進入點依賴啟動別名時，移除這些別名。
失敗處理
標題為「失敗處理」的區段| 失敗 | 應在何處處理 | 建議的回應 |
|---|---|---|
| 不支援的方法 | 配接器例外。 | 替換該呼叫，或將它隔離在應用程式配接器後方。 |
| 版面部分對等 | 移轉測試與視覺檢視。 | 在推出前，先記錄可接受的差異。 |
| 不安全的輸出目的地 | OutputBridge 與應用程式儲存政策。 | 拒絕不安全的路徑，並優先使用原生輸出 API。 |
| 安全性功能不一致 | 原生移轉計畫。 | 不要為受規範的輸出推出僅相容性的行為。 |
| 啟動別名衝突 | 應用程式啟動程序。 | 移除全域別名，或把它們限定在舊版進入點的範圍內。 |
安全的預設值
標題為「安全的預設值」的區段| 關注點 | 預設值 | 何時覆寫 |
|---|---|---|
| 不支援的方法 | 擲出明確的例外。 | 在生產環境中不要放寬此行為。 |
| 舊版預設值 | 集中於 LegacyDefaults。 | 只有在已知的移轉行為需要時才覆寫。 |
| 輸出對映 | 會經過 OutputBridge。 | 移轉後改用原生輸出 API。 |
| 覆蓋範圍來源 | 方法覆蓋頁面與測試。 | 在每次配接器升級後，重新執行覆蓋範圍檢查。 |
| 嚴格模式 | 在移轉稽核期間維持啟用。 | 只在有記錄的舊版相容性期間內才停用。 |
測試檢查清單
標題為「測試檢查清單」的區段- 為每個已移轉的方法群組保留一份舊版 fixture。
- 在替換舊版方法之前，先新增一個原生 NextPDF 測試。
- 斷言不支援的方法會擲出有記錄的例外。
- 當逐位元組相等並非務實的移轉目標時，改為比較輸出結構。
- 在新增或變更配接器方法後，執行方法覆蓋範圍檢查。
- 為舊版程式碼使用的每個輸出目的地加上儲存路徑測試。