Migrasi dari DomPDF
Panduan ini membantu Anda melakukan migrasi dari DomPDF (dompdf/dompdf) ke TCPDF-Next. Kedua library memiliki filosofi desain yang berbeda secara fundamental -- DomPDF adalah renderer HTML/CSS-ke-PDF, sedangkan TCPDF-Next adalah library PDF-native dengan engine rendering HTML yang powerful.
Pendekatan DomPDF vs Pendekatan TCPDF-Next
DomPDF memperlakukan pembuatan PDF sebagai rendering HTML. Anda menulis HTML dan CSS, lalu DomPDF mengonversinya ke PDF. Ini praktis tetapi membatasi Anda pada apa yang bisa diekspresikan CSS, tanpa akses ke fitur PDF native seperti tanda tangan digital, enkripsi, atau kepatuhan PDF/A.
TCPDF-Next menawarkan dua pendekatan:
| Pendekatan | Deskripsi | Terbaik Untuk |
|---|---|---|
| Core API | Konstruksi PDF langsung via method PHP | Layout presisi, form, grafik, tanda tangan |
| Artisan HTML Renderer | Renderer HTML/CSS berbasis DOM (HtmlRenderer) | Konten heavy-HTML, migrasi dari DomPDF |
Untuk sebagian besar migrasi DomPDF, gunakan Artisan HTML Renderer -- menerima template HTML yang ada dengan perubahan minimal.
Pemetaan API
| DomPDF | TCPDF-Next | Catatan |
|---|---|---|
new Dompdf($options) | PdfDocument::create()->build() | Fluent builder |
$dompdf->loadHtml($html) | $renderer->writeHtml($html) | HTML yang sama berfungsi |
$dompdf->loadHtmlFile($url) | $renderer->writeHtmlFile($path) | Hanya file lokal secara default |
$dompdf->setPaper('A4', 'portrait') | ->setPageFormat(PageFormat::A4) | Berbasis enum |
$dompdf->render() | Otomatis saat save() / toString() | Tidak perlu langkah render eksplisit |
$dompdf->output() | $pdf->toString() | Mengembalikan string biner |
$dompdf->stream('file.pdf') | Helper respons framework | Lihat contoh di bawah |
$options->set('defaultFont', ...) | $renderer->setDefaultFont(...) | |
$options->set('isRemoteEnabled', true) | ResourcePolicy::allowDomain(...) | Allowlist eksplisit |
$options->set('chroot', $dir) | ResourcePolicy::allowLocalDirectory(...) | Kontrol lebih granular |
Contoh Migrasi Dasar
DomPDF (sebelum):
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 (sesudah):
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');Perbandingan Dukungan CSS
| Fitur CSS | DomPDF | TCPDF-Next |
|---|---|---|
| Box model (margin, padding, border) | Ya | Ya |
| Float | Parsial | Parsial |
| Flexbox | Tidak | Tidak |
| Grid | Tidak | Tidak |
position: absolute/relative | Parsial | Ya |
@font-face | Ya | Ya |
page-break-before/after | Ya | Ya |
background-image | Parsial | Ya |
border-radius | Tidak | Ya |
opacity | Ya | Ya |
CSS variable (--custom) | Tidak | Tidak |
| Media query | Tidak | @media print saja |
Layout table | Ya | Ya (ditingkatkan) |
TIP
HTML renderer TCPDF-Next mendukung sebagian besar properti CSS 2.1 dan properti CSS 3 terpilih. Flexbox dan Grid tidak didukung -- gunakan tabel untuk layout kompleks. Jika Anda menemukan perbedaan rendering CSS, periksa dokumentasi HTML Renderer.
Kapan Menggunakan Core vs Artisan
| Skenario | Pendekatan yang Direkomendasikan |
|---|---|
| Migrasi template HTML yang ada | Artisan HTML Renderer |
| Layout pixel-perfect (invoice, sertifikat) | Core API |
| Tanda tangan digital diperlukan | Core API (signing berfungsi dengan keduanya, tetapi Core memberi lebih banyak kontrol) |
| Kepatuhan PDF/A | Keduanya (keduanya mendukung PDF/A-4) |
| Barcode / QR code | Core API (rendering vektor native) |
| Form dengan field yang bisa diisi | Core API |
| Laporan sederhana dari HTML | Artisan HTML Renderer |
Perbandingan Performa
| Metrik | DomPDF | TCPDF-Next | Peningkatan |
|---|---|---|---|
| PDF sederhana 1 halaman | 62,1 ms | 8,2 ms | 7,6x lebih cepat |
| Laporan 20 halaman | 891 ms | 187 ms | 4,8x lebih cepat |
| Puncak memori (1 halaman) | 22,1 MB | 4,2 MB | 5,3x lebih kecil |
| Puncak memori (20 halaman) | 89,7 MB | 12,4 MB | 7,2x lebih kecil |
| Ukuran file output (1 halaman) | 31,8 KB | 12,4 KB | 2,6x lebih kecil |
Lihat Benchmark Performa untuk metodologi detail dan kasus uji tambahan.
Kemampuan Baru Setelah Migrasi
Fitur yang tersedia di TCPDF-Next yang tidak didukung DomPDF:
- Tanda tangan digital -- PAdES B-B hingga B-LTA dengan dukungan hardware security module.
- Enkripsi AES-256 -- Proteksi dokumen berbasis password dan sertifikat.
- PDF/A-4 -- Kepatuhan arsip penuh (ISO 19005-4).
- Tagged PDF / PDF/UA -- Aksesibilitas untuk screen reader.
- Barcode native -- QR, Data Matrix, Code 128, EAN, dan lainnya sebagai grafik vektor.
- Form field -- Text field, checkbox, dan dropdown yang bisa diisi.
- Cross-reference stream -- Ukuran file lebih kecil dengan struktur PDF modern.
Bacaan Lanjutan
- Tabel Pemetaan API -- Pemetaan method detail
- Benchmark -- Perbandingan performa lengkap
- Ikhtisar Keamanan -- Peningkatan keamanan dibanding DomPDF
- Referensi API -- Dokumentasi API TCPDF-Next lengkap