HTML Renderer

La clase HtmlRenderer es el punto de entrada principal para todas las operaciones de HTML a PDF. Proporciona una API fluent para cargar contenido, configurar la salida y renderizar documentos PDF.

Método factory

Crea una instancia del renderer con el factory estático create().

php

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

// Configuración predeterminada (auto-detecta Chrome)
$renderer = HtmlRenderer::create();

// Con una ruta personalizada al binario de Chrome
$renderer = HtmlRenderer::create(
    chromePath: '/usr/bin/google-chrome',
);

// Con un directorio temporal personalizado
$renderer = HtmlRenderer::create(
    chromePath: '/usr/bin/chromium',
    tempDir: '/tmp/artisan-render',
);

Carga de contenido

Desde una cadena

Pasa HTML sin procesar directamente con loadHtml(). La cadena puede ser un documento HTML completo o un fragmento.

php

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

Cuando pasas un fragmento, Artisan lo envuelve automáticamente en un documento <!DOCTYPE html> mínimo.

Desde un archivo local

Carga un archivo .html desde disco con loadFile(). Las rutas relativas a hojas de estilo, imágenes y scripts dentro del archivo se resuelven desde el directorio del archivo.

php

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

Desde una URL

Obtén y renderiza una URL activa con loadUrl(). La página se carga dentro de Chrome headless, por lo que JavaScript se ejecuta y las llamadas AJAX se resuelven antes del renderizado.

php

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

Puedes establecer un timeout de navegación para prevenir bloqueos en páginas lentas:

php

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

Métodos de salida

Guardar en archivo

php

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

Obtener como cadena

Recupera los bytes PDF sin procesar para procesamiento adicional (ej., almacenar en base de datos, adjuntar a un email).

php

$pdfContent = $renderer->toString();

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

Enviar al navegador

Transmite el PDF directamente a la respuesta HTTP con las cabeceras apropiadas.

php

// Visualización en línea (visor PDF del navegador)
$renderer->output('report.pdf', 'inline');

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

Ejemplo completo: Factura

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');

Encadenamiento de métodos

Cada setter en HtmlRenderer retorna $this, habilitando un patrón de builder fluent.

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');

Manejo de errores

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());
}

Próximos pasos

Render Options -- Ajuste fino de tamaño de página, márgenes, encabezados y pies de página.
Funciones avanzadas -- Fusión de PDFs, inyección de CSS, capturas de pantalla.

HTML Renderer ​

Método factory ​

Carga de contenido ​

Desde una cadena ​

Desde un archivo local ​

Desde una URL ​

Métodos de salida ​

Guardar en archivo ​

Obtener como cadena ​

Enviar al navegador ​

Ejemplo completo: Factura ​

Encadenamiento de métodos ​

Manejo de errores ​

Próximos pasos ​