跳轉到

TCPDF 遷移指南

本指南說明如何將既有的 TCPDF 程式碼遷移至 NextPDF，分為三個階段：零停機兼容切換、輸出驗證、漸進式 API 現代化。

前置作業

評估遷移範圍

在開始前，評估你的程式碼庫中 TCPDF 的使用規模：

# 統計直接使用 TCPDF 類別的檔案數
grep -rl "new TCPDF\|extends TCPDF\|TCPDF::" src/ | wc -l

# 列出所有使用 TCPDF 方法的呼叫
grep -rn "\$pdf->" src/ | grep -v "//.*\$pdf->" | sort -u

階段 1：安裝相容層（零停機）

1.1 安裝套件

composer require nextpdf/tcpdf-compat

1.2 確認 Composer autoload 優先順序

確保 tcpdf-compat 的類別定義優先於 tcpdf/tcpdf：

{
    "autoload": {
        "classmap": [
            "vendor/nextpdf/tcpdf-compat/src/Compat/"
        ]
    },
    "autoload-dev": {
        "psr-4": {
            "Tests\\": "tests/"
        }
    }
}

composer dump-autoload

1.3 驗證類別解析

// 快速驗證：確認 TCPDF 類別由 tcpdf-compat 提供
echo (new \ReflectionClass('TCPDF'))->getFileName();
// 預期輸出：...vendor/nextpdf/tcpdf-compat/src/Compat/TCPDF.php

階段 2：輸出驗證

在切換相容層後，驗證 PDF 輸出與原始 TCPDF 版本的視覺一致性：

2.1 建立視覺比較基準

# 使用原始 TCPDF 生成參考 PDF
php artisan nextpdf:compat:baseline --output=tests/fixtures/baseline/

# 切換至 tcpdf-compat 後重新生成
php artisan nextpdf:compat:generate --output=tests/fixtures/current/

# 視覺比較（需安裝 ImageMagick）
php artisan nextpdf:compat:compare \
    --baseline=tests/fixtures/baseline/ \
    --current=tests/fixtures/current/ \
    --threshold=0.01  # 允許 1% 像素差異

2.2 關鍵輸出指標

驗證項目 工具 通過標準
頁數一致 PdfParser::pageCount() 完全相同
字型嵌入 PDF 元資料檢查 所有字型已嵌入
影像品質 像素差異比較 ≤ 2% 差異
文字可搜尋性 pdftotext 所有文字可提取
加密設定 qpdf --check-linearization 加密參數一致

階段 3：漸進式 API 現代化

相容層驗證通過後，可逐步將 TCPDF 呼叫替換為 NextPDF Core 原生 API：

3.1 文字輸出遷移

// 舊版 TCPDF
$pdf->SetFont('helvetica', '', 12);
$pdf->SetXY(20, 30);
$pdf->Cell(0, 10, 'Hello World', 0, 1, 'L');

// NextPDF Core（現代 API）
$document->text(
    content: 'Hello World',
    x: 20, y: 30,
    font: FontReference::helvetica(size: 12),
    align: TextAlign::Left,
);

3.2 影像遷移

// 舊版 TCPDF
$pdf->Image('/path/to/logo.png', 10, 10, 50, 0, 'PNG');

// NextPDF Core
$document->image(
    path: '/path/to/logo.png',
    x: 10, y: 10,
    width: 50,     // height = null 保持比例
);

3.3 HTML 渲染遷移

// 舊版 TCPDF
$pdf->writeHTML('<h1>Title</h1><p>Content</p>');

// NextPDF Core（需安裝 nextpdf/artisan 或使用內建 Html 模組）
$document->renderHtml('<h1>Title</h1><p>Content</p>');

常見問題排除

問題：字型渲染差異

症狀：文字位置偏移、行高不一致
原因：TCPDF 使用舊版字型度量；NextPDF 使用 HarfBuzz 度量
解決：在相容層中啟用「TCPDF 相容字型度量模式」

// 在 compat config 中啟用舊版字型度量
\NextPDF\Compat\Config::set('font_metrics', 'tcpdf_legacy');

問題：自訂 Header/Footer 不顯示

症狀：繼承 TCPDF 並覆寫 Header()/Footer() 的程式碼無效果
原因：NextPDF 使用不同的頁首頁尾機制
解決：確認 TCPDF::Header() / TCPDF::Footer() 的方法簽名與父類別一致

回退策略

若遷移過程中發現無法解決的相容性問題，可安全地回退：

# 移除 tcpdf-compat，恢復原始 tcpdf/tcpdf
composer remove nextpdf/tcpdf-compat
composer require tcpdf/tcpdf
composer dump-autoload

相容層不修改任何原始業務邏輯，回退操作安全且可重複。

參見