Migration từ mPDF
Hướng dẫn này giúp bạn migration từ mPDF (mpdf/mpdf) sang TCPDF-Next. mPDF là thư viện HTML sang PDF với hỗ trợ CSS rộng và các tính năng như văn bản CJK, barcode và watermark. TCPDF-Next cung cấp tập tính năng bao trùm mPDF với tuân thủ chuẩn hiện đại và không dependency runtime.
So sánh tính năng
| Tính năng | mPDF | TCPDF-Next |
|---|---|---|
| Phiên bản PHP | 7.4+ | 8.5+ |
| Phiên bản PDF | PDF 1.4 / 1.7 | PDF 2.0 |
| Kiến trúc | Tập trung HTML/CSS | PDF-native với hỗ trợ HTML |
| Dependency runtime | 10+ package Composer | Không |
| Mã hóa | RC4, AES-128, AES-256 | Chỉ AES-256 (PDF 2.0) |
| Chữ ký số | Không hỗ trợ | PAdES B-B đến B-LTA |
| PDF/A | PDF/A-1b, PDF/A-3b (một phần) | PDF/A-4 (đầy đủ ISO 19005-4) |
| Tagged PDF | Hạn chế | Trợ năng PDF/UA đầy đủ |
| Hỗ trợ CJK | Có (font đi kèm 50+ MB) | Có (đăng ký riêng, subset tối ưu) |
| RTL / BiDi | Có | Có (tuân thủ UAX #9) |
| Barcode | Có (1D và 2D) | Có (vector native, bộ mở rộng) |
| Watermark | Có | Có |
| Tạo TOC | Có | Có |
| Sử dụng bộ nhớ | Cao (toàn bộ DOM trong bộ nhớ) | Trung bình (streaming output) |
Tính năng riêng mPDF và tương đương TCPDF-Next
Tag HTML tùy chỉnh
mPDF định nghĩa tag HTML không chuẩn. Các tag này cần điều chỉnh:
| Tag tùy chỉnh mPDF | Tương đương TCPDF-Next |
|---|---|
<tocpagebreak> | $pdf->addTableOfContentsPage() |
<tocentry content="..." level="0"> | $toc->addEntry('...', level: 0) |
<barcode code="..." type="C128"> | $page->addBarcode(BarcodeFactory::code128('...')) |
<columnbreak> | $renderer->columnBreak() |
<pagebreak> | <div style="page-break-before: always"> (CSS chuẩn) |
<bookmark content="..."> | $pdf->addBookmark('...') |
<watermarktext content="DRAFT"> | $pdf->setWatermark(Watermark::text('DRAFT')) |
<watermarkimage src="..."> | $pdf->setWatermark(Watermark::image('...')) |
HTML Header và Footer
mPDF (trước):
php
$mpdf->SetHTMLHeader('<div style="text-align: center;">Header</div>');
$mpdf->SetHTMLFooter('<div>Page {PAGENO} of {nbpg}</div>');
$mpdf->SetHTMLHeader('<div>Even header</div>', 'E');TCPDF-Next (sau):
php
$pdf->setHtmlHeader('<div style="text-align: center;">Header</div>');
$pdf->setHtmlFooter('<div>Page {{pageNumber}} of {{totalPages}}</div>');
$pdf->setHtmlHeader('<div>Even header</div>', pages: 'even');Chế độ WriteHTML
mPDF (trước):
php
$mpdf->WriteHTML($css, \Mpdf\HTMLParserMode::HEADER_CSS);
$mpdf->WriteHTML($body, \Mpdf\HTMLParserMode::HTML_BODY);TCPDF-Next (sau):
php
$renderer = new HtmlRenderer($pdf);
$renderer->addStylesheet($css);
$renderer->writeHtml($body);Watermark
mPDF (trước):
php
$mpdf->SetWatermarkText('DRAFT', 0.1);
$mpdf->showWatermarkText = true;TCPDF-Next (sau):
php
$pdf->setWatermark(
Watermark::text('DRAFT')
->setOpacity(0.1)
->setRotation(45)
->setColor(Color::rgb(200, 200, 200))
);Ánh xạ cấu hình
| Cấu hình mPDF | Tương đương TCPDF-Next |
|---|---|
mode => 'utf-8' | Luôn UTF-8 (không cần cấu hình) |
format => 'A4' | setPageFormat(PageFormat::A4) |
margin_left/right/top/bottom | setMargins(new Margins(...)) |
default_font | $renderer->setDefaultFont(...) |
tempDir | PdfDocument::create()->setTempDir(...) |
autoScriptToLang | $renderer->setAutoFontDetection(true) |
biDirectional | Luôn bật (UAX #9) |
pdfaAuto | setPdfALevel(PdfALevel::PDF_A_4) |
Method Output
mPDF (trước):
php
$mpdf->Output('/path/to/file.pdf', \Mpdf\Output\Destination::FILE);
$mpdf->Output('doc.pdf', \Mpdf\Output\Destination::DOWNLOAD);
$mpdf->Output('doc.pdf', \Mpdf\Output\Destination::INLINE);
$content = $mpdf->Output('', \Mpdf\Output\Destination::STRING_RETURN);TCPDF-Next (sau):
php
$pdf->save('/path/to/file.pdf');
$bytes = $pdf->toString();
// Web response (ví dụ Laravel)
return response($pdf->toString(), 200, [
'Content-Type' => 'application/pdf',
'Content-Disposition' => 'attachment; filename="doc.pdf"',
]);Giảm dependency
Migration từ mPDF giúp đơn giản hóa dependency tree đáng kể:
Loại bỏ (mPDF + transitive):
mpdf/mpdf+ 10+ package transitivepsr/log,psr/http-message,setasign/fpdi,mpdf/qrcode
Thêm:
yeee-fang/tcpdf-next(không dependency runtime)
So sánh hiệu năng
| Chỉ số | mPDF | TCPDF-Next | Cải thiện |
|---|---|---|---|
| PDF 1 trang đơn giản | 45.3 ms | 8.2 ms | Nhanh hơn 5.5x |
| Document 100 trang | 3,210 ms | 845 ms | Nhanh hơn 3.8x |
| Bộ nhớ đỉnh (1 trang) | 18.4 MB | 4.2 MB | Ít hơn 4.4x |
| Bộ nhớ đỉnh (100 trang) | 198.2 MB | 28.6 MB | Ít hơn 6.9x |
| Kích thước file output (1 trang) | 24.3 KB | 12.4 KB | Nhỏ hơn 2.0x |
Xem Benchmark hiệu năng để biết phương pháp đầy đủ và test case.
Đọc thêm
- Bảng ánh xạ API — Ánh xạ method toàn diện
- Benchmark — So sánh hiệu năng đầy đủ với mPDF
- Tham chiếu API — Tài liệu API TCPDF-Next đầy đủ
- FAQ — Câu hỏi migration thường gặp