跳到內容
NextPDF

遷移指南

遷移指南

標題為「遷移指南」的區段

NextPDF 是一套供 PHP 使用的 PDF 2.0 引擎。如果你已經在用其他函式庫產生 PDF，遷移指南會把該函式庫的 API 對映到 NextPDF，並記錄你會遇到的行為差異。本頁是跨儲存庫索引：它記錄哪份指南會帶你從哪套函式庫遷出、每份指南由哪個儲存庫維護，以及所有指南共用的模型。

因為本頁只是索引，所以不會對任何指南做出行為宣稱。每份指南都由各自的儲存庫維護。aggregate（聚合）流程由 aggregator（文件聚合器）負責，會把各份指南拉進本網站；在某份指南尚未匯入前，下方連結會指向 placeholder（佔位符）。每一項行為宣稱都寫在指南本身，並由儲存庫內的測試或一條釘選的 ISO 32000-2 / CSS WG 條款佐證，而不是寫在這裡。

唯一的遷移模型

標題為「唯一的遷移模型」的區段

每一份 NextPDF 遷移指南都共用同一個誠實的模型；閱讀任何一份指南時，都應該先記住這點：

  • 相容，而非位元級完全相同。 NextPDF 與你要離開的那套函式庫是各自獨立的實作。遷移後的文件在意圖上是功能等價，不是像素或位元級完全相同。任何指南都不宣稱可直接替換（drop-in），也不宣稱 100% 相容。
  • 涵蓋率是量測得到的數量，不是一句斷言。 當某份指南列出涵蓋率數字時（例如 TCPDF 配接器），該數字是取自儲存庫內矩陣的功能完整度指標，意義上對應 ISO/IEC 25023 第 43 條——是對已涵蓋方法數量的量測，而非全面保證。
  • 每份指南都會公開說明自己的行為差異。 每份指南都附有明確的差異表，以及一節「不支援/無直接對應」的內容。差異是已記錄的引擎特性，不是缺陷。
  • 更換 renderer（渲染器）就需要重新審查。 遷移是一項程式碼變更，也需要重新建立輸出基準。每份指南都會說明如何測試這次遷移；視覺驗收按文件逐一進行，由整合者負責。

遷移的型態

標題為「遷移的型態」的區段

這些指南分為兩種型態。型態會說明你需要改動多少程式碼。

  • API 重寫式遷移沒有相容 shim（相容層）：每個呼叫點都要依指南中的動詞對映與選項對映重寫。HTML 轉 PDF 函式庫的遷移（dompdf、mpdf）就是這種型態——它們直接以 NextPDF 的 Html pipeline 為目標。
  • 先直接替換、再逐步遷移式遷移會提供一個近乎原始碼相容的配接器，所以最初的遷移只需要一次最小幅度的相依套件替換。從那之後，你再把呼叫點逐步遷移到現代 API，最後汰除這個配接器。TCPDF 遷移就是這種型態，透過 nextpdf/compat-legacy 配接器進行。

指南與所屬儲存庫對照

標題為「指南與所屬儲存庫對照」的區段

下方列出的每份指南都放在所屬儲存庫的 docs/public/ 之下，再由 aggregator 拉進本網站。所屬儲存庫才是該指南行為宣稱的權威來源；本索引只記錄路由。

來源指南型態所屬儲存庫頁面
DompdfDompdf → NextPDF Html 管線API 重寫nextpdf（核心）Dompdf 指南 dompdf（上游規劃中）
mPDFmPDF → NextPDF 核心API 重寫nextpdf（核心）mPDF 指南 mpdf（上游規劃中）
TCPDF 6.xTCPDF → NextPDF（透過 compat-legacy 配接器）先直接替換、再逐步遷移nextpdf-compat-tcpdf 儲存庫，套件 nextpdf/compat-legacyTCPDF 指南 tcpdf-compat（上游規劃中）

其中 dompdf 與 mpdf 指南放在核心儲存庫，因為它們以核心引擎的 API 為目標，並由核心的 examples/ 作為佐證。tcpdf-compat 指南放在 compat-tcpdf 儲存庫，因為 nextpdf/compat-legacy 套件負責 TCPDF 的行為面，也包含佐證該指南的配接器測試。本索引則放在 docs 本身，因為它跨越多個儲存庫，而且不對其中任何一個做出行為宣稱。

各份指南各有什麼用途

標題為「各份指南各有什麼用途」的區段
  • Dompdf → NextPDF（dompdf（上游規劃中））——適用於在伺服器端使用 dompdf/dompdf 的程式碼庫。它把 loadHtml/render/output 以及 Options 設定鍵對映到 NextPDF 的 Html pipeline，並把 CSS 功能的預期交由「僅限已驗證」的 CSS 支援矩陣決定。沒有 Dompdf 類別 shim；每個呼叫點都要重寫。
  • mPDF → NextPDF（mpdf（上游規劃中））——適用於使用 mpdf/mpdf 的程式碼庫。它把 WriteHTML/Output/AddPage 以及建構式的設定陣列對映到核心 API，並指出一項字型處理差異：NextPDF 透過單一字型目錄加上 CSS 比對來 resolve（解析），而且一律進行子集化。沒有 Mpdf 類別 shim。
  • TCPDF → NextPDF（compat-legacy）（tcpdf-compat（上游規劃中））——適用於想把最初改動降到最小的 TCPDF 6.x 程式碼庫。先安裝配接器，用嚴格模式對照儲存庫內的涵蓋率矩陣稽核你實際用到的介面，再把呼叫點從配接器上遷出，然後在其上加入 PDF/UA-2 標記結構——這是 TCPDF 從來沒有的能力。這個配接器是鷹架，不是終點，也不是可直接替換（drop-in）的保證。

指南連結如何解析

標題為「指南連結如何解析」的區段

上方每個 [[…]] placeholder 都是一個向前參照，指向一個放在所屬儲存庫 docs/public/migration/ 之下的頁面，再由 aggregator 把該頁拉進本網站。目標 slug 遵循同一套慣例：

/migration/<source>/

這裡的 <source> token 是你要遷出的函式庫簡稱：dompdf、mpdf 或 tcpdf-compat 其中之一，如上方指南對照表所列。在目標頁面尚未匯入前，它的連結仍只是 placeholder，無法解析。本索引不對任何目標指南做出行為宣稱；它只記錄路由，以及共用的遷移模型。

另請參閱

標題為「另請參閱」的區段
  • CSS 支援矩陣——dompdf 與 mpdf 指南會以這份「僅限已驗證」的權威作為 CSS 功能預期的依據。
  • Integration cookbook（整合範例集）——生態系整合套件的跨儲存庫索引（這是另一件事：把引擎接上去，而不是遷移到它上面）。