HTML Renderer

The HtmlRenderer class is the main entry point for all HTML-to-PDF operations. It provides a fluent API for loading content, configuring output, and rendering PDF documents.

Factory Method

Create a renderer instance with the static create() factory.

php

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

// Default configuration (auto-detects Chrome)
$renderer = HtmlRenderer::create();

// With a custom Chrome binary path
$renderer = HtmlRenderer::create(
    chromePath: '/usr/bin/google-chrome',
);

// With a custom temporary directory
$renderer = HtmlRenderer::create(
    chromePath: '/usr/bin/chromium',
    tempDir: '/tmp/artisan-render',
);

Loading Content

From a String

Pass raw HTML directly with loadHtml(). The string can be a full HTML document or a fragment.

php

$renderer->loadHtml('<h1>Hello, World!</h1>');

When you pass a fragment, Artisan wraps it in a minimal <!DOCTYPE html> document automatically.

From a Local File

Load an .html file from disk with loadFile(). Relative paths to stylesheets, images, and scripts within the file are resolved from the file's directory.

php

$renderer->loadFile('/templates/quarterly-report.html');

From a URL

Fetch and render a live URL with loadUrl(). The page is loaded inside headless Chrome, so JavaScript executes and AJAX calls resolve before rendering.

php

$renderer->loadUrl('https://reports.example.com/q4-2026');

You can set a navigation timeout to prevent hanging on slow pages:

php

$renderer->loadUrl('https://example.com/dashboard', timeoutMs: 30000);

Output Methods

Save to File

php

$renderer->save('/output/report.pdf');

Get as String

Retrieve the raw PDF bytes for further processing (e.g., storing in a database, attaching to an email).

php

$pdfContent = $renderer->toString();

// Example: store in database
DB::table('documents')->insert([
    'name'    => 'report.pdf',
    'content' => $pdfContent,
]);

Send to Browser

Stream the PDF directly to the HTTP response with appropriate headers.

php

// Inline display (browser PDF viewer)
$renderer->output('report.pdf', 'inline');

// Force download
$renderer->output('report.pdf', 'download');

Full Example: Invoice

php

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

$html = <<<'HTML'
<!DOCTYPE html>
<html>
<head>
    <style>
        body { font-family: 'Inter', sans-serif; margin: 20mm; }
        .header { display: flex; justify-content: space-between; align-items: flex-start; }
        .company { font-size: 24px; font-weight: 700; color: #1a237e; }
        .meta { text-align: right; color: #666; font-size: 13px; }
        .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; margin: 30px 0; }
        .grid section { padding: 15px; background: #f8f9fa; border-radius: 6px; }
        table { width: 100%; border-collapse: collapse; margin-top: 20px; }
        th { background: #1a237e; color: white; padding: 10px 12px; text-align: left; }
        td { border-bottom: 1px solid #e0e0e0; padding: 10px 12px; }
        tr:nth-child(even) { background: #fafafa; }
        .total { font-weight: 700; font-size: 18px; text-align: right; margin-top: 20px; }
    </style>
</head>
<body>
    <div class="header">
        <div class="company">Acme Corporation</div>
        <div class="meta">
            Invoice #2026-001<br>
            Date: 2026-02-16<br>
            Due: 2026-03-16
        </div>
    </div>
    <div class="grid">
        <section>
            <strong>Bill To</strong><br>
            Jane Smith<br>
            456 Oak Avenue<br>
            Springfield, IL 62704
        </section>
        <section>
            <strong>Ship To</strong><br>
            Jane Smith<br>
            789 Elm Street<br>
            Springfield, IL 62704
        </section>
    </div>
    <table>
        <thead>
            <tr>
                <th>Item</th>
                <th>Qty</th>
                <th>Unit Price</th>
                <th>Amount</th>
            </tr>
        </thead>
        <tbody>
            <tr><td>Web Development</td><td>40 hrs</td><td>$150.00</td><td>$6,000.00</td></tr>
            <tr><td>UI/UX Design</td><td>20 hrs</td><td>$125.00</td><td>$2,500.00</td></tr>
            <tr><td>Annual Hosting</td><td>1</td><td>$1,200.00</td><td>$1,200.00</td></tr>
        </tbody>
    </table>
    <div class="total">Total: $9,700.00</div>
</body>
</html>
HTML;

HtmlRenderer::create()
    ->loadHtml($html)
    ->save('/invoices/2026-001.pdf');

Method Chaining

Every setter on HtmlRenderer returns $this, enabling a fluent builder pattern.

php

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

HtmlRenderer::create()
    ->loadFile('/templates/report.html')
    ->withOptions(
        RenderOptions::create()
            ->setPageSize('A4')
            ->setLandscape(false)
            ->setMargins(top: 15, right: 10, bottom: 15, left: 10)
            ->setPrintBackground(true)
    )
    ->withStyleInjector(
        StyleInjector::create()
            ->addCss('body { font-size: 12pt; }')
    )
    ->save('/output/styled-report.pdf');

Error Handling

php

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

try {
    HtmlRenderer::create()
        ->loadUrl('https://example.com/slow-report')
        ->save('/output/report.pdf');
} catch (ChromeNotFoundException $e) {
    // Chrome binary not found -- check CHROME_PATH
    logger()->error('Chrome not installed: ' . $e->getMessage());
} catch (TimeoutException $e) {
    // Page took too long to load or render
    logger()->warning('Render timed out: ' . $e->getMessage());
} catch (RenderException $e) {
    // Any other rendering failure
    logger()->error('Render failed: ' . $e->getMessage());
}

Next Steps

Render Options -- Fine-tune page size, margins, headers, and footers.
Advanced Features -- PDF merging, CSS injection, screenshots.

HTML Renderer ​

Factory Method ​

Loading Content ​

From a String ​

From a Local File ​

From a URL ​

Output Methods ​

Save to File ​

Get as String ​

Send to Browser ​

Full Example: Invoice ​

Method Chaining ​

Error Handling ​

Next Steps ​