跳到內容
NextPDF

NextPDF compat-legacy 的啟動與探索

概覽

標題為「概覽」的區段

nextpdf/compat-legacy 提供一個相容 TCPDF 的門面，也就是 NextPDF\Compat\Tcpdf\TCPDF 這個類別，並將工作委派給 NextPDF 引擎。這是一個相容層，不是可直接替換的複製品。在約 120 個受檢視的 TCPDF 6.x 方法中，它以直接委派方式涵蓋了 94 個。其餘方法都有已記錄的行為差異（見 /integrations/tcpdf-compat/method-coverage/）。

自動載入時不會進行全域接線。預設情況下，引入此套件不會建立全域的 \TCPDF 類別。你必須明確啟用全域別名；或採用遷移期間更建議的做法：在每個檔案中匯入轉接器類別。

TCPDF 門面的提供方式

標題為「TCPDF 門面的提供方式」的區段

這個門面是一個透過 PSR-4 自動載入的一般類別：

項目值
門面類別NextPDF\Compat\Tcpdf\TCPDF
PSR-4 前綴NextPDF\Compat\Tcpdf\ 對應到 src/Compat/Tcpdf/
共用契約NextPDF\Compat\Contracts\CompatAdapterInterface
逃生出口TCPDF::getDocument() 會回傳所包裝的 NextPDF\Core\Document

這個類別刻意不是 final：既有 TCPDF 使用者通常會繼承 TCPDF 來覆寫 Header() 與 Footer()，因此這個轉接器保留了該擴充點。在內部，這個類別仍是門面。它組合了 25 個單一職責的關注點 trait，並將所有 PDF 操作委派給建構時建立的 Document 實例。

啟動流程

標題為「啟動流程」的區段

Composer autoload

Class referenced: new TCPDF or new global TCPDF

Constructor runs

LegacyDefaults::register defines K_/PDF_ constants if absent

ConstructorBridge::build maps orientation/unit/format to Document

Document, UnitConverter, PageSize stored on the facade

Creator/Author seeded from PDF_CREATOR / PDF_AUTHOR

Diagram

建構程序是唯一的「啟動」步驟。套件本身不會進行服務容器註冊，也沒有任何框架啟動程序。框架整合是由你自行加上的一層薄層——見 /integrations/tcpdf-compat/integration/.

LegacyDefaults::register() 具有冪等性：只有在某個常數尚未被定義時，才會定義它。只要你在第一次建構之前就定義它們，應用程式自行定義的常數一律優先（見 /integrations/tcpdf-compat/configuration/ §「組態解析順序」）。

選擇性啟用的全域類別別名

標題為「選擇性啟用的全域類別別名」的區段

如果你的程式碼在全域命名空間呼叫 new \TCPDF(...)，而你目前還無法變更這些呼叫點，請在應用程式啟動時註冊一次全域別名：

examples/boot-aliases.php
<?php


declare(strict_types=1);


require __DIR__ . '/vendor/autoload.php';


use NextPDF\Compat\Tcpdf\LegacyBootstrap;


LegacyBootstrap::enableAliases();


// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases() 會註冊 \TCPDF、\TCPDF_STATIC、\TCPDF_FONTS、\TCPDF_COLORS 與 \TCPDF_IMAGES。其行為由 tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php 驗證，如下：

  • 它具有冪等性——呼叫兩次並不會擲出例外，且只會註冊一次。
  • LegacyBootstrap::isRegistered() 會回報它是否已經執行。
  • 註冊之後的 new \TCPDF() 會是該轉接器的實例。

避免與真正安裝的 TCPDF 發生衝突

標題為「避免與真正安裝的 TCPDF 發生衝突」的區段

這是本頁最重要的規則。

enableAliases() 只有在同名的類別尚未存在時才會註冊別名（class_exists($alias, autoload: false)）。因此：

  • 如果已安裝 tecnickcom/tcpdf 且其 \TCPDF 先被載入，該別名就會被靜默略過，你的程式碼也會繼續使用既有的 TCPDF，而不是這個轉接器。
  • 在同一個行程中同時執行這兩個函式庫並啟用全域別名是不受支援的，而且會產生模稜兩可的行為。

在遷移期間，建議採用明確的逐檔匯入（use NextPDF\Compat\Tcpdf\TCPDF;）。這種做法便於用 grep 搜尋，也不會造成歧義。一旦嚴格模式稽核通過，就移除 tecnickcom/tcpdf（見 /integrations/tcpdf-compat/migration/ 第 5 階段）。當 \TCPDF 解析到錯誤的類別時，/integrations/tcpdf-compat/troubleshooting/ 提供了診斷方法。

容器繫結

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

此套件不隨附任何框架容器繫結。如果你在容器中繫結這個門面，請繫結一個工廠，讓它為每份文件回傳一個全新的 NextPDF\Compat\Tcpdf\TCPDF。文件狀態屬於個別實例，不得在彼此無關的文件之間共用（見 /integrations/tcpdf-compat/production-usage/ §「並行」）。典型繫結方式可參見 /integrations/tcpdf-compat/integration/.

組態解析順序

標題為「組態解析順序」的區段

建構時，轉接器會依以下順序解析組態：先是建構函式引數，接著是任何既有、由應用程式定義的舊版常數，最後才對尚未被定義的常數套用 LegacyDefaults 的 TCPDF 6.2.13 預設值。完整細節以及新版的 AdaptationConfig 物件，見 /integrations/tcpdf-compat/configuration/.

診斷

標題為「診斷」的區段

若要驗證門面已接線完成，且引擎連結能正確解析，請建構一個轉接器並產生一份單頁 PDF，然後檢查 %PDF 前綴。這與套件輸出測試所驗證的範圍相同。可實際執行的檢查位於 /integrations/tcpdf-compat/install/ §「驗證安裝」。

若要在啟用別名之前偵測與真正 TCPDF 的衝突，請在你會呼叫 enableAliases() 的位置，檢查全域的 \TCPDF 是否已經存在。若它確實存在，某個別名就會被略過，因此在你倚賴這個轉接器之前，請先解決此衝突（改用明確匯入，或移除真正的 TCPDF）。

TCPDF API 涵蓋範圍

標題為「TCPDF API 涵蓋範圍」的區段

具權威性且經測試驗證的涵蓋範圍對照表，是儲存庫內的檔案 docs/TCPDF_COVERAGE.md。讀者版摘要（含靜默忽略與尚未實作的方法清單）位於 /integrations/tcpdf-compat/method-coverage/. 本套件不宣稱自己是「可直接替換的替代品」或「100% 相容 TCPDF」；它是一個相容 TCPDF 的替代方案，具備已知且經測試的相容範圍，以及已記錄在案的行為差異。

另請參閱

標題為「另請參閱」的區段
  • docs/TCPDF_COVERAGE.md — 權威的涵蓋範圍來源（儲存庫內）
  • /integrations/tcpdf-compat/integration/ — 將門面串接至 application/framework
  • /integrations/tcpdf-compat/method-coverage/ — 各方法的行為與缺口
  • /integrations/tcpdf-compat/migration/ — 分階段的遷移策略
  • /integrations/tcpdf-compat/troubleshooting/ — alias/real-TCPDF 衝突的診斷
  • tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php — 別名行為的測試標準（oracle）