Fitur Lanjutan

Selain rendering HTML-ke-PDF dasar, paket Artisan menyediakan utilitas untuk menggabungkan dokumen, menginjeksi style global, menangkap screenshot, dan fine-tuning perilaku Chrome.

Penggabungan PDF

Class PdfMerger menggabungkan beberapa sumber HTML menjadi satu dokumen PDF. Setiap sumber di-render sebagai bagian terpisah, dan hasilnya digabungkan secara berurutan.

use Yeeefang\TcpdfNext\Artisan\PdfMerger;
use Yeeefang\TcpdfNext\Artisan\RenderOptions;

$merger = PdfMerger::create();

$merger
    ->addHtml('<h1>Cover Page</h1><p>Annual Report 2026</p>')
    ->addFile('/templates/chapter-1.html')
    ->addFile('/templates/chapter-2.html')
    ->addUrl('https://charts.example.com/annual-summary')
    ->addHtml('<h1>Appendix</h1><p>Supporting data tables.</p>');

$merger->save('/reports/annual-2026.pdf');

Options Per-Bagian

Setiap bagian bisa memiliki RenderOptions sendiri. Misalnya, halaman cover landscape dan bab portrait.

$coverOptions = RenderOptions::create()
    ->setPageSize('A4')
    ->setLandscape(true)
    ->setPrintBackground(true);

$chapterOptions = RenderOptions::create()
    ->setPageSize('A4')
    ->setLandscape(false)
    ->setDisplayHeaderFooter(true)
    ->setFooterTemplate('
        <div style="font-size: 8px; text-align: center; width: 100%; color: #888;">
            Page <span class="pageNumber"></span>
        </div>
    ');

PdfMerger::create()
    ->addHtml('<h1>Cover</h1>', options: $coverOptions)
    ->addFile('/templates/chapter-1.html', options: $chapterOptions)
    ->addFile('/templates/chapter-2.html', options: $chapterOptions)
    ->save('/reports/merged.pdf');

Injeksi CSS

Class StyleInjector menambahkan CSS rule di awal halaman yang di-render. Ini berguna untuk menerapkan stylesheet brand global ke template yang tidak Anda kontrol.

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;
use Yeeefang\TcpdfNext\Artisan\StyleInjector;

$injector = StyleInjector::create()
    ->addCss('
        body {
            font-family: "Inter", "Noto Sans TC", sans-serif;
            font-size: 11pt;
            line-height: 1.6;
            color: #333;
        }
        h1 { color: #1a237e; }
    ')
    ->addCssFile('/styles/brand.css');

HtmlRenderer::create()
    ->loadFile('/templates/report.html')
    ->withStyleInjector($injector)
    ->save('/output/branded-report.pdf');

Layer Style Berganda

Style diinjeksi sesuai urutan penambahan. Rule yang ditambahkan kemudian meng-override yang sebelumnya, mengikuti specificity CSS standar.

$injector = StyleInjector::create()
    ->addCssFile('/styles/reset.css')
    ->addCssFile('/styles/brand.css')
    ->addCss('table { page-break-inside: avoid; }');  // override

Screenshot

Class ScreenshotCapture me-render HTML ke format gambar alih-alih PDF. Berguna untuk menghasilkan thumbnail, preview media sosial, atau visual regression testing.

use Yeeefang\TcpdfNext\Artisan\ScreenshotCapture;

// Screenshot halaman penuh sebagai PNG
ScreenshotCapture::create()
    ->loadHtml('<h1>Preview</h1><p>This will be a PNG image.</p>')
    ->fullPage(true)
    ->format('png')
    ->save('/output/preview.png');

JPEG dengan Quality

ScreenshotCapture::create()
    ->loadUrl('https://example.com/dashboard')
    ->format('jpeg')
    ->quality(85)
    ->save('/output/dashboard.jpg');

Konfigurasi Viewport

ScreenshotCapture::create()
    ->loadFile('/templates/email.html')
    ->viewport(width: 1200, height: 800)
    ->deviceScaleFactor(2)  // retina
    ->fullPage(false)
    ->save('/output/email-preview.png');

Konfigurasi Chrome

Path Binary Kustom

Artisan auto-detect Chrome di path OS umum. Override dengan chromePath.

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

$renderer = HtmlRenderer::create(
    chromePath: '/opt/google/chrome/chrome',
);

Atau set environment variable CHROME_PATH secara global.

Flag Headless Mode

Artisan melewatkan --headless=new secara default (Chrome 112+). Anda bisa menambahkan flag ekstra untuk lingkungan tertentu.

$renderer = HtmlRenderer::create(
    chromeFlags: [
        '--no-sandbox',            // diperlukan di Docker
        '--disable-gpu',           // direkomendasikan di Docker
        '--disable-dev-shm-usage', // hindari masalah /dev/shm
        '--font-render-hinting=none',
    ],
);

Connection Pooling

Untuk skenario throughput tinggi, gunakan ulang satu instance Chrome di beberapa render. Ini menghilangkan biaya startup (sekitar 300--500 ms) untuk setiap render berikutnya.

use Yeeefang\TcpdfNext\Artisan\ChromeBridge;
use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

// Buat bridge yang persisten
$bridge = ChromeBridge::create(chromePath: '/usr/bin/chromium');

// Gunakan ulang di beberapa render
foreach ($reports as $report) {
    HtmlRenderer::createWithBridge($bridge)
        ->loadHtml($report->html)
        ->save("/output/{$report->id}.pdf");
}

// Tutup secara eksplisit setelah selesai
$bridge->close();

Penanganan Error

Semua exception Artisan meng-extend Yeeefang\TcpdfNext\Artisan\Exceptions\ArtisanException.

use Yeeefang\TcpdfNext\Artisan\Exceptions\RenderException;
use Yeeefang\TcpdfNext\Artisan\Exceptions\ChromeNotFoundException;
use Yeeefang\TcpdfNext\Artisan\Exceptions\TimeoutException;

try {
    HtmlRenderer::create()->loadUrl($url)->save($path);
} catch (ChromeNotFoundException $e) {
    // Instal Chrome atau set CHROME_PATH
} catch (TimeoutException $e) {
    // Tingkatkan timeout atau periksa jaringan
} catch (RenderException $e) {
    // Periksa $e->getMessage() untuk detail
}

Exception	Penyebab Umum
ChromeNotFoundException	Chrome tidak terinstal, CHROME_PATH salah
TimeoutException	Halaman lambat, JS promise yang tidak resolve, masalah jaringan
RenderException	HTML tidak valid, Chrome crash, kegagalan penulisan disk

Tips Performa

1. Gunakan ulang instance Chrome -- Gunakan ChromeBridge untuk operasi batch.
2. Minimalkan JavaScript -- Semakin sedikit JS yang harus dieksekusi Chrome, semakin cepat render.
3. Inline critical CSS -- Hindari pengambilan stylesheet eksternal jika memungkinkan.
4. Set timeout ketat -- Gagal cepat pada halaman rusak alih-alih memblokir queue.
5. Gunakan setPrintBackground(false) -- Lewati rendering background saat Anda tidak membutuhkannya.

Langkah Selanjutnya

• Render Options -- Ukuran halaman, margin, dan template header/footer.
• Setup Docker -- Menjalankan Artisan di lingkungan container.
• Ringkasan -- Ringkasan paket dan instalasi.