TCPDF 相容性 API 參考

概覽

本 nextpdf/compat-legacy 套件提供主要類別 NextPDF\Compat\Tcpdf\TCPDF，鏡像 TCPDF 6.x 的公開 API，並透過現代 NextPDF 引擎繪製輸出。它也提供一小組支援元件：用來註冊全域類別別名的 LegacyBootstrap、一組 AdaptationConfig/LegacyDefaults 組態介面、內部橋接類別（輸出、建構式、色彩、單位、頁面格式），以及相容性例外。它是遷移輔助工具，並非永久相依項目。完整的舊版方法狀態列在方法涵蓋表中。本頁說明應用程式碼應明確依賴的介面。

**從這裡開始：**如果你剛開始使用這個套件，先建構 NextPDF\Compat\Tcpdf\TCPDF，照常呼叫你慣用的 TCPDF 方法（AddPage()、SetFont()、Cell()），最後以 Output($name, $dest) 收尾。這個類別幾乎是下方所有內容的進入點。可執行的入門範例請見常見任務一節。

常見任務

以下是這個套件最常見的實務任務。每個區塊都已對照轉接器原始碼驗證，可直接執行。

用熟悉的 TCPDF 呼叫產生 PDF，並把它擷取為字串（用於佇列、HTTP 回應或儲存）：

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetTitle('Invoice 1234');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$bytes = $pdf->Output('invoice.pdf', 'S');

作用：透過 TCPDF 介面形狀的轉接器建構一份 PDF 2.0 文件，並回傳原始位元組（%PDF...），因為目的地 'S' 會經由 OutputBridge 路由到 Document::getPdfData()，而不是直接 echo 輸出，因此在 worker 或控制器中都很安全。

只要在啟動時註冊一次全域別名，就能不修改任何原始碼，直接執行既有的 new \TCPDF(...) 程式碼：

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

$pdf = new \TCPDF('P', 'mm', 'A4'); // resolves to the adapter
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/legacy.pdf', 'F');

作用：enableAliases() 會以冪等方式註冊 \TCPDF（以及 \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES 等輔助類別），但只在這些名稱尚未定義時才註冊，因此未經修改的舊版程式碼會在轉接器上執行。

透過揭露每一個被靜默丟棄的 TCPDF 參數，對一次遷移進行稽核：

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter
}

作用：啟用 setStrictMode(true) 後，任何無法重現 TCPDF 行為的呼叫都會拋出 TcpdfNotImplementedException，並指明被忽略的參數。這會把靜默降級轉換成遷移待辦清單（只應在稽核流程中執行，絕不可用於正式環境）。

主要轉接器

這張表列出轉接器的正式介面。當你需要確認所建構的類別（TCPDF）、它的嚴格模式與逃生口方法，以及它實作的合約時，請查這張表。

符號	參數	預設行為	回傳	拋出或失敗於	備註
`NextPDF\Compat\Tcpdf\TCPDF`	建構式參數透過 `ConstructorBridge` 沿用舊版 TCPDF 的介面形狀。	建立由 NextPDF 文件支撐的轉接器。	`TCPDF`	建構式驗證或不支援功能的例外。	供遷移期間使用，不適用於新撰寫的原生 NextPDF 程式碼。
`TCPDF::getDocument()`	無。	回傳底層的 NextPDF 文件。	`NextPDF\Core\Document`	預期無。	供必須混用舊版與原生呼叫的遷移程式碼作為逃生口使用。
`TCPDF::getUnitConverter()`	無。	回傳由舊版單位建立的轉換器。	`UnitConverter`	預期無。	用於遷移診斷，而非一般應用程式碼。
`TCPDF::setStrictMode(bool $enabled)`	嚴格模式旗標。	啟用或停用不支援相容性行為時的明確失敗。	`static`	預期無。	在遷移稽核期間保持啟用。
`TCPDF::isStrictMode()`	無。	回傳目前的嚴格模式旗標。	`bool`	預期無。	在測試斷言中很有用。
`TCPDF` 舊版方法	依方法而異。	支援的方法會對映到核心文件呼叫；不支援的方法則明確失敗。	依方法而異。	`TcpdfNotImplementedException` 或 `UnsupportedFeatureException`。	在依賴某個方法之前，先查方法涵蓋表。
`CompatAdapterInterface::getDocument()`	無。	由 `TCPDF` 實作的合約方法。	`Document`	預期無。	讓工具能存取原生文件。
`CompatAdapterInterface::Output(string $name = '', string $dest = '')`	檔名與舊版目的地。	委派給輸出橋接層。	`string`	核心寫入錯誤或不支援的目的地錯誤。	鏡像舊版 TCPDF 的輸出入口；具體的 `TCPDF::Output` 提供 `'doc.pdf'`/`'I'` 的預設值。

舊版方法群組

這張表對照轉接器涵蓋的 TCPDF 方法家族。到方法涵蓋表確認確切狀態前，可先掃過這張表，大致判斷某個舊版呼叫落在哪一類。

群組	代表性符號	預設行為	備註
生命週期與輸出	`Open()`、`Close()`、`Output()`、`getPDFData()`	在原生文件之上維持 TCPDF 介面形狀的文件生命週期。	遷移後請優先使用原生輸出 API。
中繼資料	`SetTitle()`、`SetAuthor()`、`SetSubject()`、`SetKeywords()`、`SetCreator()`	把中繼資料 setter 對映到底層文件。	請將中繼資料正規化保留在應用程式碼中。
頁面與定位	`AddPage()`、`setPage()`、`lastPage()`、`GetX()`、`SetXY()`	把舊版單位與座標轉換成原生頁面操作。	遷移後請以視覺方式驗證絕對定位。
邊界與版面	`SetMargins()`、`SetAutoPageBreak()`、`setCellPaddings()`、`getMargins()`	儲存相容性狀態並對映支援的數值。	複雜的 TCPDF 分頁行為可能需要人工檢查。
字型與文字	`SetFont()`、`AddFont()`、`Cell()`、`MultiCell()`、`Write()`、`Text()`	把常見的文字操作路由到原生字型與文字 API。	請使用正式環境的字型檢查 CJK 與編碼行為。
HTML	`writeHTML()`、`writeHTMLCell()`、`fixHTMLCode()`	把支援的 HTML 送進原生 HTML 管線。	原生 renderer（渲染器）不是完整的 TCPDF HTML 複製品。
影像與繪圖	`Image()`、`Line()`、`Rect()`、`Circle()`、`SetDrawColor()`	透過轉接器層對映支援的圖形操作。	不支援的向量或特殊格式會明確失敗。
導覽與註解	`Bookmark()`、`AddLink()`、`SetLink()`、`Annotation()`	在已有對映的位置保留常見導覽呼叫。	請驗證產生的大綱與連結。
安全性與簽章	`SetProtection()`、`setSignature()`、`setTimeStamp()`、`setUserRights()`	把支援的舊版安全性呼叫橋接到原生功能。	請把密碼學輸出視為獨立的驗證關卡。
表單、樣板與變換	`TextField()`、`startTemplate()`、`StartTransform()`、`Rotate()`、`Scale()`	實作支援的子集，並對不支援的行為明確失敗。	推出前請對照方法涵蓋表稽核每一個呼叫。

Bootstrap 與組態

當你把轉接器接進應用程式的啟動路徑時，例如註冊全域別名，或在舊版常數與現代 AdaptationConfig 之間做選擇，請查這張表。

符號	參數	預設行為	回傳	拋出或失敗於	備註
`LegacyBootstrap::enableAliases()`	無。	註冊一次相容性別名。	`void`	自動載入或環境錯誤。	只有在舊版程式碼預期 TCPDF 名稱必須存在於全域時才使用。
`LegacyBootstrap::isRegistered()`	無。	回報別名是否已完成註冊。	`bool`	預期無。	在 bootstrap 測試中很有用。
`LegacyBootstrap::resetForTesting()`	無。	清除測試用的註冊狀態。	`void`	預期無。	僅供測試的輔助方法。
`AdaptationConfig`	轉接器旗標與遷移控制項。	省略時使用套件的預設值。	`AdaptationConfig`	無效的選項值。	在遷移稽核期間請保持組態明確。
`AdaptationConfig::fromLegacyConstants()`	無。	讀取已知舊版常數並建構組態。	`AdaptationConfig`	無效的舊版常數值。	供大型舊版應用程式使用的過渡輔助方法。
`LegacyDefaults`	無。	提供預設的舊版數值。	預設值集合。	預期無。	集中存放相容性預設值的地方。

橋接與輔助類別

這些是轉接器使用的內部轉換類別。只有在你貢獻轉接器涵蓋範圍，或診斷某個舊版引數如何被轉譯時，才需要查這張表；日常應用程式碼不應直接使用。

符號	參數	預設行為	回傳	拋出或失敗於	備註
`ConstructorBridge`	舊版建構式引數清單。	將舊版選項正規化為 NextPDF 組態。	建構式資料。	無效的舊版引數值。	由轉接器內部使用。
`CellParameterAdapter`	TCPDF 儲存格參數。	將舊版位置引數對映到核心文字版面選項。	已轉接的參數。	無效的尺寸或對齊方式。	在新程式碼中請優先使用原生核心方法。
`OutputBridge::dispatch(Document $document, string $filename, string $dest)`	原生文件、檔名與舊版目的地。	將 inline/download/儲存行為對映到 NextPDF 輸出 API。	`string`	核心寫入錯誤；不支援的目的地。	輸出前請驗證檔名與儲存根目錄。
`OutputBridge::resolveDestination(string $dest)`	舊版目的地代碼。	將目的地轉換成原生輸出目的地。	`OutputDestination`	不支援的目的地錯誤。	讓目的地對映保持集中。
`ColorTranslator`	TCPDF 色彩引數。	將舊版色彩形式正規化。	核心色彩值。	無效的色彩值。	由色彩與繪圖層使用。
`PageFormatResolver`	舊版頁面格式輸入。	將已知名稱對映到核心頁面尺寸。	頁面格式值。	未知格式。	遷移後請使用明確的原生頁面尺寸。
`UnitConverter`	舊版量測值與單位。	轉換為核心單位。	數值。	無效的單位。	協助保留舊版版面行為。

例外

當某個遷移呼叫明確失敗時，請查這張表。它會告訴你哪個例外代表「未實作」、哪個代表「已知但不支援」，以及各自的復原方式。

符號	含意	復原
`TcpdfNotImplementedException`	轉接器刻意不實作請求的舊版方法。	改用原生 NextPDF API，或移除這個相依項目。
`TcpdfNotImplementedException::forSilentIgnore()`	某個舊版呼叫過去會被忽略，但現在為了讓遷移更清楚而被揭露。	判斷明確的 no-op 行為是否可接受。
`TcpdfNotImplementedException::forUnimplemented()`	某個舊版呼叫沒有已實作的轉接器處理路徑。	改寫這個呼叫，或把它隔離在遷移程式碼後面。
`UnsupportedFeatureException`	這項舊版功能是已知功能，但在轉接器邊界內不受支援。	查閱遷移指引，並把該功能隔離在應用程式的轉接器後面。
`UnsupportedFeatureException::forMethod()`	建立特定於方法的不支援功能錯誤。	在相容性貢獻中使用，以保持一致的失敗訊息。

開發備註

請將轉接器當成遷移工具看待。新程式碼應直接以核心 NextPDF API 為目標。
不支援的行為應該明確失敗。除非應用程式明確接受這項風險，否則不要在捕捉相容性例外後，繼續產出不完整的文件。
請讓遷移變更保持小幅，並對照涵蓋表驗證每一個舊版方法。