Migration từ DomPDF
Hướng dẫn này giúp bạn migration từ DomPDF (dompdf/dompdf) sang TCPDF-Next. Hai thư viện có triết lý thiết kế khác nhau cơ bản — DomPDF là trình render HTML/CSS sang PDF, trong khi TCPDF-Next là thư viện PDF-native với engine render HTML mạnh mẽ.
Cách tiếp cận DomPDF vs TCPDF-Next
DomPDF coi việc tạo PDF là render HTML. Bạn viết HTML và CSS, DomPDF chuyển nó thành PDF. Điều này tiện lợi nhưng giới hạn bạn ở những gì CSS có thể biểu đạt, không có quyền truy cập tính năng PDF native như chữ ký số, mã hóa, hoặc tuân thủ PDF/A.
TCPDF-Next cung cấp hai cách tiếp cận:
| Cách tiếp cận | Mô tả | Phù hợp cho |
|---|---|---|
| Core API | Xây dựng PDF trực tiếp qua method PHP | Layout chính xác, form, đồ họa, chữ ký |
| Artisan HTML Renderer | Trình render HTML/CSS dựa trên DOM (HtmlRenderer) | Nội dung HTML nhiều, migration từ DomPDF |
Cho hầu hết migration từ DomPDF, dùng Artisan HTML Renderer — nó nhận template HTML hiện có với thay đổi tối thiểu.
Ánh xạ API
| DomPDF | TCPDF-Next | Ghi chú |
|---|---|---|
new Dompdf($options) | PdfDocument::create()->build() | Fluent builder |
$dompdf->loadHtml($html) | $renderer->writeHtml($html) | Cùng HTML hoạt động |
$dompdf->loadHtmlFile($url) | $renderer->writeHtmlFile($path) | Mặc định chỉ file cục bộ |
$dompdf->setPaper('A4', 'portrait') | ->setPageFormat(PageFormat::A4) | Dùng Enum |
$dompdf->render() | Tự động khi save() / toString() | Không cần bước render rõ ràng |
$dompdf->output() | $pdf->toString() | Trả về binary string |
$dompdf->stream('file.pdf') | Helper response framework | Xem ví dụ bên dưới |
$options->set('defaultFont', ...) | $renderer->setDefaultFont(...) | |
$options->set('isRemoteEnabled', true) | ResourcePolicy::allowDomain(...) | Allowlist rõ ràng |
$options->set('chroot', $dir) | ResourcePolicy::allowLocalDirectory(...) | Kiểm soát chi tiết hơn |
Ví dụ migration cơ bản
DomPDF (trước):
use Dompdf\Dompdf;
use Dompdf\Options;
$options = new Options();
$options->set('defaultFont', 'Helvetica');
$options->set('isRemoteEnabled', true);
$dompdf = new Dompdf($options);
$dompdf->loadHtml($html);
$dompdf->setPaper('A4', 'portrait');
$dompdf->render();
file_put_contents('output.pdf', $dompdf->output());TCPDF-Next (sau):
use YeeeFang\TcpdfNext\Document\PdfDocument;
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Html\HtmlRenderer;
$pdf = PdfDocument::create()
->setPageFormat(PageFormat::A4)
->build();
$renderer = new HtmlRenderer($pdf);
$renderer->setDefaultFont('Helvetica', size: 12);
$renderer->writeHtml($html);
$pdf->save('output.pdf');So sánh hỗ trợ CSS
| Tính năng CSS | DomPDF | TCPDF-Next |
|---|---|---|
| Box model (margin, padding, border) | Có | Có |
| Float | Một phần | Một phần |
| Flexbox | Không | Không |
| Grid | Không | Không |
position: absolute/relative | Một phần | Có |
@font-face | Có | Có |
page-break-before/after | Có | Có |
background-image | Một phần | Có |
border-radius | Không | Có |
opacity | Có | Có |
CSS variable (--custom) | Không | Không |
| Media query | Không | Chỉ @media print |
table layout | Có | Có (cải tiến) |
TIP
HTML renderer của TCPDF-Next hỗ trợ hầu hết thuộc tính CSS 2.1 và một số thuộc tính CSS 3 chọn lọc. Flexbox và Grid không được hỗ trợ — dùng table cho layout phức tạp. Nếu gặp khác biệt render CSS, kiểm tra tài liệu HTML Renderer.
Khi nào dùng Core vs Artisan
| Tình huống | Cách tiếp cận khuyến nghị |
|---|---|
| Migration template HTML hiện có | Artisan HTML Renderer |
| Layout chính xác pixel (hóa đơn, chứng chỉ) | Core API |
| Cần chữ ký số | Core API (ký hoạt động với cả hai, nhưng Core cho kiểm soát tốt hơn) |
| Tuân thủ PDF/A | Cả hai (đều hỗ trợ PDF/A-4) |
| Barcode / QR code | Core API (render vector native) |
| Form với trường điền được | Core API |
| Report đơn giản từ HTML | Artisan HTML Renderer |
So sánh hiệu năng
| Chỉ số | DomPDF | TCPDF-Next | Cải thiện |
|---|---|---|---|
| PDF 1 trang đơn giản | 62.1 ms | 8.2 ms | Nhanh hơn 7.6x |
| Report 20 trang | 891 ms | 187 ms | Nhanh hơn 4.8x |
| Bộ nhớ đỉnh (1 trang) | 22.1 MB | 4.2 MB | Ít hơn 5.3x |
| Bộ nhớ đỉnh (20 trang) | 89.7 MB | 12.4 MB | Ít hơn 7.2x |
| Kích thước file output (1 trang) | 31.8 KB | 12.4 KB | Nhỏ hơn 2.6x |
Xem Benchmark hiệu năng để biết phương pháp chi tiết và test case bổ sung.
Tính năng mới sau migration
Các tính năng có trong TCPDF-Next mà DomPDF không hỗ trợ:
- Chữ ký số — PAdES B-B đến B-LTA với hỗ trợ hardware security module.
- Mã hóa AES-256 — Bảo vệ document bằng mật khẩu và certificate.
- PDF/A-4 — Tuân thủ lưu trữ đầy đủ (ISO 19005-4).
- Tagged PDF / PDF/UA — Trợ năng cho trình đọc màn hình.
- Barcode native — QR, Data Matrix, Code 128, EAN, và nhiều hơn dạng đồ họa vector.
- Trường form — Text field, checkbox, dropdown điền được.
- Cross-reference stream — Kích thước file nhỏ hơn với cấu trúc PDF hiện đại.
Đọc thêm
- Bảng ánh xạ API — Ánh xạ method chi tiết
- Benchmark — So sánh hiệu năng đầy đủ
- Tổng quan bảo mật — Cải thiện bảo mật so với DomPDF
- Tham chiếu API — Tài liệu API TCPDF-Next đầy đủ