從 mPDF 遷移

本指南協助您從 mPDF（mpdf/mpdf）遷移至 TCPDF-Next。mPDF 是一套類似 DomPDF 的 HTML 轉 PDF 函式庫，但具備更廣泛的 CSS 支援與額外功能。TCPDF-Next 提供 mPDF 功能的超集，並符合現代標準。

功能比較

特性	mPDF	TCPDF-Next
PHP 版本	7.4+	8.5+
PDF 版本	PDF 1.4 / 1.7	PDF 2.0
架構	HTML/CSS 為核心	PDF 原生，支援 HTML
CJK 支援	有（大型字型檔案）	有（最佳化子集）
RTL / BiDi	有	有（UAX #9 合規）
加密	RC4-40、RC4-128、AES-128、AES-256	僅 AES-256（PDF 2.0）
數位簽章	不支援	PAdES B-B 至 B-LTA
PDF/A	PDF/A-1b、PDF/A-3b（部分）	PDF/A-4（完整）
無障礙	有限	標記式 PDF（PDF/UA）
記憶體使用	高（完整 DOM + 圖片存於記憶體）	中等（串流輸出）
相依套件	10+ 個 Composer 套件	零執行期相依

何時該遷移

若您需要以下功能，請考慮從 mPDF 遷移至 TCPDF-Next：

• 數位簽章 — mPDF 不支援簽章功能
• 現代 PDF/A 合規 — PDF/A-4（不僅是 PDF/A-1b）
• 更佳安全性 — 僅 AES-256，無 RC4
• 更低記憶體使用 — 大型文件的串流輸出
• 更少相依套件 — 零執行期相依 vs. 10+
• 無障礙 — 具結構元素的標記式 PDF

逐步遷移

步驟 1：更新相依套件

composer remove mpdf/mpdf
composer require yeee-fang/tcpdf-next

TIP

移除 mPDF 同時也會移除其 10 多個傳遞相依套件（psr/log、psr/http-message、setasign/fpdi 等），大幅簡化您的相依樹。

步驟 2：替換文件建立

mPDF（遷移前）：

$mpdf = new \Mpdf\Mpdf([
    'mode' => 'utf-8',
    'format' => 'A4',
    'margin_left' => 15,
    'margin_right' => 15,
    'margin_top' => 16,
    'margin_bottom' => 16,
    'default_font_size' => 12,
    'default_font' => 'dejavusans',
]);

$mpdf->SetTitle('My Document');
$mpdf->SetAuthor('Jane Doe');

TCPDF-Next（遷移後）：

use YeeeFang\TcpdfNext\Document\PdfDocument;
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Document\Margins;
use YeeeFang\TcpdfNext\Html\HtmlRenderer;

$pdf = PdfDocument::create()
    ->setPageFormat(PageFormat::A4)
    ->setMargins(new Margins(left: 15, right: 15, top: 16, bottom: 16))
    ->setTitle('My Document')
    ->setAuthor('Jane Doe')
    ->build();

$renderer = new HtmlRenderer($pdf);
$renderer->setDefaultFont('DejaVuSans', size: 12);

步驟 3：替換 HTML 寫入

mPDF（遷移前）：

$mpdf->WriteHTML($stylesheet, \Mpdf\HTMLParserMode::HEADER_CSS);
$mpdf->WriteHTML($htmlBody, \Mpdf\HTMLParserMode::HTML_BODY);

TCPDF-Next（遷移後）：

$renderer = new HtmlRenderer($pdf);
$renderer->addStylesheet($stylesheet);
$renderer->writeHtml($htmlBody);

步驟 4：替換頁首頁尾

mPDF（遷移前）：

$mpdf->SetHTMLHeader('<div style="text-align: center;">公司名稱</div>');
$mpdf->SetHTMLFooter('<div style="text-align: center;">第 {PAGENO} 頁，共 {nbpg} 頁</div>');

TCPDF-Next（遷移後）：

$pdf->setHtmlHeader('<div style="text-align: center;">公司名稱</div>');
$pdf->setHtmlFooter('<div style="text-align: center;">第 {{pageNumber}} 頁，共 {{totalPages}} 頁</div>');

// 或使用回呼方式（更靈活）
$pdf->onPageFooter(function (Page $page, int $pageNumber, int $totalPages) {
    $page->addText("第 {$pageNumber} 頁，共 {$totalPages} 頁")
        ->setPosition(105, 287)
        ->setFont('Helvetica', size: 9)
        ->setAlignment(Alignment::CENTER);
});

步驟 5：替換浮水印

mPDF（遷移前）：

$mpdf->SetWatermarkText('DRAFT', 0.1);
$mpdf->showWatermarkText = true;

TCPDF-Next（遷移後）：

use YeeeFang\TcpdfNext\Document\Watermark;

$pdf->setWatermark(
    Watermark::text('DRAFT')
        ->setOpacity(0.1)
        ->setRotation(45)
        ->setFont('Helvetica', size: 72)
        ->setColor(Color::rgb(200, 200, 200))
);

步驟 6：替換 CJK 與 RTL 文字

mPDF（遷移前）：

$mpdf = new \Mpdf\Mpdf(['mode' => '+aCJK', 'autoScriptToLang' => true, 'autoLangToFont' => true]);
$mpdf->SetDirectionality('rtl');

TCPDF-Next（遷移後）：

// CJK 支援（註冊 CJK 字型）
$pdf->getFontManager()->registerFont('/path/to/NotoSansCJK-Regular.ttc', 'NotoSansCJK');
$renderer->setAutoFontDetection(true); // 依腳本自動選取字型

// RTL（透過 Unicode BiDi 演算法自動處理）
$renderer->writeHtml('<div dir="rtl">مرحبا بالعالم</div>');

步驟 7：替換輸出

mPDF（遷移前）：

$mpdf->Output('/path/to/file.pdf', \Mpdf\Output\Destination::FILE);
$mpdf->Output('doc.pdf', \Mpdf\Output\Destination::DOWNLOAD);
$content = $mpdf->Output('', \Mpdf\Output\Destination::STRING_RETURN);

TCPDF-Next（遷移後）：

$pdf->save('/path/to/file.pdf');   // 儲存至檔案
$bytes = $pdf->toString();          // 以字串回傳

// 下載（Web 框架）
return response($pdf->toString(), 200, [
    'Content-Type' => 'application/pdf',
    'Content-Disposition' => 'attachment; filename="doc.pdf"',
]);

mPDF 自訂標籤對應

mPDF 支援非標準 HTML 的自訂標籤，需要進行適配：

mPDF 自訂標籤	TCPDF-Next 對應
<tocpagebreak>	$pdf->addTableOfContentsPage()
<tocentry>	$toc->addEntry(...)
<barcode>	$page->addBarcode(...)
<columnbreak>	$renderer->columnBreak()
<pagebreak>	標準 <div style="page-break-before: always">
<bookmark>	$pdf->addBookmark(...)
<watermarktext>	$pdf->setWatermark(Watermark::text(...))
<watermarkimage>	$pdf->setWatermark(Watermark::image(...))

相依套件精簡

從 mPDF 遷移至 TCPDF-Next 可大幅精簡相依樹：

移除的 mPDF 相依套件：

• mpdf/mpdf + 10 多個傳遞套件
• psr/log、psr/http-message、setasign/fpdi、mpdf/qrcode 等

新增的 TCPDF-Next 相依套件：

• yeee-fang/tcpdf-next（零執行期相依）

延伸閱讀

• API 參考 — TCPDF-Next 完整 API 文件
• API 對應表 — 完整方法對照
• 效能基準 — 與 mPDF 的效能比較
• 常見問題 — 常見遷移疑問