Paket Artisan

Artisan · LGPL-3.0

Paket Artisan (yeeefang/tcpdf-next-artisan) menyediakan konversi HTML-ke-PDF pixel-perfect yang ditenagai oleh Chrome DevTools Protocol (CDP). Paket ini me-render HTML dengan dukungan CSS3 penuh -- termasuk Flexbox, Grid, web font, media query, dan animasi yang dibekukan saat render.

Kapan Menggunakan Artisan

Skenario	Rekomendasi
Generate PDF dari template HTML/CSS	Artisan
Konstruksi PDF programatik (cell, gambar)	Core
Arsip email HTML ke PDF	Artisan
Invoice dari data terstruktur	Core atau Artisan
Layout CSS kompleks (Grid, Flexbox)	Artisan
PDF bertanda tangan/terenkripsi	Core

Cara Kerja

Artisan meluncurkan instance Chrome headless melalui Chrome DevTools Protocol, memuat konten HTML Anda ke halaman browser, dan menggunakan fungsi print-to-PDF bawaan Chrome. Ini berarti setiap fitur CSS yang didukung Chrome tersedia untuk PDF Anda -- tidak perlu lagi berjuang dengan CSS parser yang terbatas.

HTML/CSS --> ChromeBridge --> Chrome CDP --> PDF binary --> save / stream

Instalasi

composer require yeeefang/tcpdf-next-artisan

Persyaratan:

• PHP 8.2+
• chrome-php/chrome ^1.15 (diinstal otomatis)
• Browser Chrome atau Chromium terinstal di host

# Ubuntu/Debian
apt-get install -y chromium-browser

# macOS
brew install --cask chromium

# Windows (Chocolatey)
choco install googlechrome

# Set path kustom via environment variable
export CHROME_PATH=/usr/bin/google-chrome

Quick Start

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

$renderer = HtmlRenderer::create();

$renderer
    ->loadHtml('<h1>Hello, World!</h1><p>Rendered with Chrome CDP.</p>')
    ->save('/output/hello.pdf');

Dari URL

HtmlRenderer::create()
    ->loadUrl('https://example.com/report')
    ->save('/output/report.pdf');

Dari File

HtmlRenderer::create()
    ->loadFile('/templates/invoice.html')
    ->save('/output/invoice.pdf');

Isi Paket

Class	Tujuan
HtmlRenderer	Entry point utama -- muat HTML, konfigurasi, render
ChromeBridge	Komunikasi Chrome DevTools Protocol
RenderOptions	Konfigurasi rendering (margin, skala, header)
PageSetup	Ukuran halaman dan orientasi untuk rendering
PdfMerger	Gabungkan beberapa halaman yang di-render menjadi satu PDF
StyleInjector	Injeksi stylesheet CSS sebelum rendering
ScreenshotCapture	Tangkap screenshot halaman (PNG/JPEG)

Hirarki Exception

Exception	Kapan
RenderException	Kegagalan rendering generik
ChromeNotFoundException	Binary Chrome tidak ditemukan di path yang diharapkan
TimeoutException	Page load atau rendering melebihi timeout yang dikonfigurasi

Semua exception berada di namespace Yeeefang\TcpdfNext\Artisan\Exceptions dan meng-extend class dasar ArtisanException.

Perbandingan dengan HTML Parser Core

Paket Core menyertakan modul HtmlParser untuk konversi HTML-ke-PDF dasar. Gunakan ketika Anda butuh solusi tanpa dependency. Gunakan Artisan ketika Anda butuh fidelitas rendering browser penuh.

Fitur	Core HtmlParser	Artisan
Dependency eksternal	Tidak ada	Chrome/Chromium
CSS Flexbox / Grid	Tidak	Ya
Web font (@font-face)	Tidak	Ya
Media query	Tidak	Ya
Eksekusi JavaScript	Tidak	Ya
CSS rule @page	Tidak	Ya
Performa (dokumen sederhana)	Lebih cepat	Lebih lambat
Performa (CSS kompleks)	N/A	Reliable

Langkah Selanjutnya

• HTML Renderer -- Memuat dan me-render konten HTML.
• Render Options -- Mengonfigurasi ukuran halaman, margin, header, dan footer.
• Fitur Lanjutan -- Penggabungan PDF, injeksi CSS, screenshot.
• Setup Docker -- Menjalankan Artisan di container.