跳到內容
NextPDF

NextPDF compat-legacy 概觀

概觀

標題為「概觀」的區段

nextpdf/compat-legacy 是一套 TCPDF 相容的替代方案：這個相容層會在 NextPDF PDF 2.0 引擎之上提供 TCPDF 6.x 的公開 API。它存在的目的只有一個：讓已經依賴 TCPDF 6.x 的程式碼庫不必重寫，就能在 NextPDF 引擎上執行，使遷移可以逐一檔案推進，而不需要一次全部完成。

它並非 TCPDF 的分支（fork），也不會被描述成行為保證一致的複製品。它是保留 TCPDF 呼叫簽章的獨立實作。更精確地說：它透過直接委派涵蓋了約 120 個受調查的 TCPDF 6.x 方法中的 94 個，其餘方法則具有已記載的行為差異（請參閱 /integrations/tcpdf-compat/method-coverage/）。

它是什麼

標題為「它是什麼」的區段
  • 一項遷移輔助工具。 這個套件是 NextPDF compat 系列的一部分。它的目的在於縮短脫離舊版 PDF 函式庫的路徑，而不是成為永久相依套件。請把它視為你在採用現代 API 後會移除的鷹架。
  • 一個 API 表面的轉接器。 它提供 TCPDF 的類別名稱、方法名稱、參數順序，以及 6.2.13 的預設值。呼叫會被委派給一個 NextPDF\Core\Document 實例。
  • 一套獨立的潔淨室（clean-room）實作。 沒有任何 TCPDF 原始碼、建置產物、字型資料或其他受著作權保護的表達內容，被複製或轉譯到這個套件中。TCPDF 這個名稱僅用於互通性識別。正式聲明位於套件的 NOTICE 檔案中。

它不是什麼

標題為「它不是什麼」的區段
  • 它並非一個輸出位元組完全相同的「即插即用替代品」。對於已委派的方法，可見結果是相容的，但產出的 PDF 位元組會有所不同，因為底層引擎是另一套不同且獨立的 PDF 2.0 實作。
  • 它並非「100% 與 TCPDF 相容」。有一組界定明確的方法會接受引擎並不遵循的舊版參數，或是完全不執行任何動作。這些情況都已列舉並測試；請參閱 /integrations/tcpdf-compat/method-coverage/。
  • 它本身並非一項簽章或封存產品。數位簽章與 PDF/A 封存符合性需要 NextPDF 商業版。本文件並未提出任何經認證、受保證或具法律效力簽章的主張。

為何要透過相容層進行遷移

標題為「為何要透過相容層進行遷移」的區段

在大型應用程式中重寫每一個 TCPDF 呼叫風險很高，也難以漸進交付。相容層讓你能夠：

  1. 替換相依套件並執行你現有的測試套件，找出哪些部分已經能原封不動地運作。
  2. 以嚴格模式進行一次稽核，列舉出每一處無法被完全重現的 TCPDF 行為。
  3. 逐一將那些呼叫點遷移到現代 NextPDF API，同時讓應用程式在整個過程中都維持可交付狀態。

最終狀態是採用現代的 NextPDF\Core\Document API，並移除相容層。完整策略請參閱 /integrations/tcpdf-compat/migration/。

在 NextPDF 引擎上你能獲得什麼

標題為「在 NextPDF 引擎上你能獲得什麼」的區段

當一個 TCPDF 呼叫被委派時，該呼叫會在一個 PDF 2.0（ISO 32000-2）引擎上執行，可使用 AES-256 標準處理常式加密，且整個轉接器都具備 PHPStan Level 10 的型別安全。輸出一律寫成 PDF 2.0；轉接器無法向下對應到較舊的 PDF 版本（請參閱 /integrations/tcpdf-compat/method-coverage/ §4）。

轉接器也針對若干 TCPDF 6.2.13 歷來的陷阱做了強化：

舊版行為轉接器行為
Error() 會呼叫 die() 並靜默終止行程Error() 會擲出 RuntimeException——可觀察且可捕捉
可能從標記語言執行 PHP 的 HTML 方法該逃生口已被停用——標記語言無法觸發 PHP 執行
Output() 會直接輸出（echo），可能破壞工作行程的輸出緩衝區輸出會透過安全的目的地橋接層導向
未受保護的 header/footer 遞迴已加上遞迴防護

範圍與版本

標題為「範圍與版本」的區段

相容層隨附於 core 發行版中（nextpdf/compat-legacy，需要 nextpdf/core ^3.0）。透過標準處理常式的加密在 core 中即可使用。數位簽章與 PDF/A 封存符合性需要 NextPDF 商業版；轉接器會公開進入點，但 core 路徑本身並非一項簽章產品。精確說明請參閱 /integrations/tcpdf-compat/security-and-operations/。

接下來該看哪裡

標題為「接下來該看哪裡」的區段
  • /integrations/tcpdf-compat/install/——安裝套件並驗證引擎連結。
  • /integrations/tcpdf-compat/quickstart/——建立第一份可執行且有測試支撐的文件。
  • /integrations/tcpdf-compat/method-coverage/——每個 TCPDF 方法在此處的確切行為。
  • /integrations/tcpdf-compat/migration/——逐一檔案推進的遷移策略。
  • /integrations/tcpdf-compat/configuration/——嚴格模式與轉接器設定。
  • /integrations/tcpdf-compat/production-usage/——在負載下與工作行程中執行轉接器。
  • /integrations/tcpdf-compat/security-and-operations/——加密、簽章態勢與強化。
  • /integrations/tcpdf-compat/troubleshooting/——常見的遷移失敗及其修正方式。
  • /integrations/tcpdf-compat/integration/ / /integrations/tcpdf-compat/boot-and-discovery/——將外觀（facade）接入應用程式，並註冊全域類別別名。

另請參閱

標題為「另請參閱」的區段
  • docs/TCPDF_COVERAGE.md——權威的涵蓋範圍對照表（位於儲存庫中）
  • 套件 NOTICE——獨立實作聲明