跳轉到

Adaptation — TCPDF 相容套件

NextPDF Adaptation

nextpdf/tcpdf-compat 是 TCPDF 6.2.13 的 drop-in 相容層，透過實作 TCPDF 類別的公開 API，讓既有程式碼在不修改（或只需最小修改）的情況下切換至 NextPDF Core。

PHP Compatibility

This example uses PHP 8.5 syntax. If your environment runs PHP 8.1 or 7.4, use NextPDF Backport for a backward-compatible build.

設計哲學

相容層的目標是降低遷移風險，而非永久解決方案。方法對應層（NextPDF\Compat\TcpdfAdapter）將 TCPDF 的 PascalCase 方法呼叫代理至 NextPDF Core 的現代 API，同時保留原始行為語義。

建議的遷移路徑：

TCPDF 原生程式碼
    ↓ (第一步)
nextpdf/tcpdf-compat （零修改，驗證輸出一致性）
    ↓ (第二步，漸進式)
NextPDF Core 原生 API （充分利用 NextPDF 完整功能）

安裝

composer require nextpdf/tcpdf-compat

在 composer.json 中，可以同時安裝 tcpdf/tcpdf 和 nextpdf/tcpdf-compat，但 tcpdf-compat 的 TCPDF 類別定義會優先——確保在 Composer 的 classmap 中 tcpdf-compat 優先載入：

{
    "autoload": {
        "classmap": [
            "vendor/nextpdf/tcpdf-compat/src/"
        ]
    }
}

基本使用

<?php

// 既有程式碼：無需修改任何 use 語句或 new TCPDF() 呼叫
$pdf = new TCPDF('P', 'mm', 'A4', true, 'UTF-8', false);

$pdf->SetCreator(PDF_CREATOR);
$pdf->SetAuthor('John Doe');
$pdf->SetTitle('My Document');
$pdf->SetSubject('TCPDF Tutorial');
$pdf->SetKeywords('TCPDF, PDF, example');

$pdf->SetDefaultMonospacedFont(PDF_FONT_MONOSPACED);
$pdf->SetMargins(PDF_MARGIN_LEFT, PDF_MARGIN_TOP, PDF_MARGIN_RIGHT);
$pdf->SetHeaderMargin(PDF_MARGIN_HEADER);
$pdf->SetFooterMargin(PDF_MARGIN_FOOTER);
$pdf->SetAutoPageBreak(true, PDF_MARGIN_BOTTOM);

$pdf->AddPage();

$pdf->SetFont('helvetica', '', 16);
$pdf->Cell(0, 10, 'Hello World!', 0, false, 'C', 0, '', 0, false, 'M', 'M');

$pdf->Output('example.pdf', 'D');

此程式碼無需任何修改即可在 nextpdf/tcpdf-compat 下執行。

已支援的 TCPDF 功能

功能分類 支援狀態
基本文字與儲存格（Cell/MultiCell） 完整支援
HTML 渲染（writeHTML/writeHTMLCell） 部分支援（CSS 子集）
影像（Image/JPEG/PNG/SVG） 完整支援
頁首/頁尾（Header/Footer） 完整支援
書籤（Bookmark/CreateTOC） 完整支援
表單欄位（AcroForm） 完整支援
加密（setEncryption） 完整支援（AES-256 升級）
條碼（write1DBarcode/write2DBarcode） 完整支援（32+ 符號學）
頁面模板（loadTemplate/beginTemplate） 完整支援
字型（AddFont/SetFont） 完整支援（自動子集化）

已知差異與限制

TCPDF 行為 NextPDF Compat 行為 說明
座標系統（左上角原點） 相同 已對應
字型度量差異（<±2%） 可能略有差異 字型渲染引擎不同
Output('', 'S') 回傳類型 non-empty-string 型別一致
PHP 7.4+ 下使用 需搭配 nextpdf/backport 見 Backport 套件

參見