Render Options

La clase RenderOptions es un value object inmutable que controla cómo Chrome renderiza tu HTML a PDF. Cada setter retorna una nueva instancia, manteniendo tu configuración predecible y libre de efectos secundarios.

Crear opciones

use Yeeefang\TcpdfNext\Artisan\RenderOptions;

// Comenzar con valores predeterminados sensatos
$options = RenderOptions::create();

// Construir configuración de forma fluent
$options = RenderOptions::create()
    ->setPageSize('A4')
    ->setMargins(top: 15, right: 10, bottom: 15, left: 10)
    ->setPrintBackground(true);

Aplicar opciones

Pasa el RenderOptions configurado a HtmlRenderer::withOptions().

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

HtmlRenderer::create()
    ->loadHtml('<h1>Configured Output</h1>')
    ->withOptions($options)
    ->save('/output/configured.pdf');

Tamaño de página

Establece el formato de papel usando nombres de formato estándar.

$options = RenderOptions::create()
    ->setPageSize('A4');       // 210 x 297 mm (predeterminado)

Formatos soportados: A0--A6, B0--B6, Letter, Legal, Tabloid, Ledger.

Orientación

$options = RenderOptions::create()
    ->setPageSize('A4')
    ->setLandscape(true);      // 297 x 210 mm

Márgenes

Establece márgenes individuales en milímetros.

$options = RenderOptions::create()
    ->setMargins(
        top: 20,
        right: 15,
        bottom: 20,
        left: 15,
    );

Cuando las plantillas de encabezado o pie de página están habilitadas, los márgenes superior e inferior definen el espacio reservado para ellos.

Escala

Controla el factor de escala de renderizado. Los valores van de 0.1 a 2.0, con 1.0 como predeterminado (100%).

// Reducir contenido al 80%
$options = RenderOptions::create()
    ->setScale(0.8);

// Ampliar contenido al 120%
$options = RenderOptions::create()
    ->setScale(1.2);

Encabezados y pies de página

Chrome CDP soporta plantillas HTML para encabezados y pies de página. Las plantillas tienen acceso a clases CSS especiales que Chrome reemplaza con valores dinámicos al momento del renderizado.

Clases CSS disponibles

Clase CSS	Reemplazada con
.date	Fecha de impresión formateada
.title	Título del documento
.url	URL del documento
.pageNumber	Número de página actual
.totalPages	Número total de páginas

Plantilla de encabezado

$options = RenderOptions::create()
    ->setDisplayHeaderFooter(true)
    ->setMargins(top: 25, right: 10, bottom: 20, left: 10)
    ->setHeaderTemplate('
        <div style="font-size: 9px; width: 100%; padding: 0 10mm; display: flex; justify-content: space-between;">
            <span>Acme Corp -- Confidential</span>
            <span class="date"></span>
        </div>
    ');

Plantilla de pie de página

$options = RenderOptions::create()
    ->setDisplayHeaderFooter(true)
    ->setMargins(top: 15, right: 10, bottom: 25, left: 10)
    ->setFooterTemplate('
        <div style="font-size: 9px; width: 100%; text-align: center; color: #999;">
            Page <span class="pageNumber"></span> of <span class="totalPages"></span>
        </div>
    ');

Encabezado y pie de página combinados

$options = RenderOptions::create()
    ->setPageSize('A4')
    ->setMargins(top: 25, right: 15, bottom: 25, left: 15)
    ->setDisplayHeaderFooter(true)
    ->setHeaderTemplate('
        <div style="font-size: 9px; width: 100%; padding: 0 15mm; display: flex; justify-content: space-between; border-bottom: 1px solid #e0e0e0; padding-bottom: 5px;">
            <span style="font-weight: bold;">Quarterly Report</span>
            <span class="date"></span>
        </div>
    ')
    ->setFooterTemplate('
        <div style="font-size: 8px; width: 100%; padding: 0 15mm; display: flex; justify-content: space-between; color: #888;">
            <span>Acme Corporation</span>
            <span>Page <span class="pageNumber"></span> / <span class="totalPages"></span></span>
        </div>
    ');

Impresión de fondos

Por defecto, Chrome omite colores e imágenes de fondo (coincidiendo con el comportamiento del diálogo de impresión del navegador). Habilita el renderizado de fondos explícitamente.

$options = RenderOptions::create()
    ->setPrintBackground(true);

Reglas CSS @page

Cuando están habilitadas, las reglas CSS @page en tu HTML sobrescriben el tamaño de página y márgenes configurados en RenderOptions.

$options = RenderOptions::create()
    ->setPreferCssPageSize(true);

Tu HTML puede entonces controlar el diseño:

@page {
    size: A3 landscape;
    margin: 10mm;
}

Espera de contenido

Esperar por un selector DOM

Retrasa el renderizado hasta que un elemento específico aparezca en el DOM. Útil cuando JavaScript genera contenido dinámicamente.

$options = RenderOptions::create()
    ->setWaitForSelector('#chart-rendered');

Timeout

Establece el tiempo máximo (en milisegundos) para esperar la carga de página y el renderizado. El valor predeterminado es 30000 (30 segundos).

$options = RenderOptions::create()
    ->setTimeout(60000);    // 60 seconds for heavy pages

Si se excede el timeout, se lanza una TimeoutException.

Ejemplo completo

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

$options = RenderOptions::create()
    ->setPageSize('Letter')
    ->setLandscape(false)
    ->setMargins(top: 25, right: 15, bottom: 25, left: 15)
    ->setScale(1.0)
    ->setPrintBackground(true)
    ->setDisplayHeaderFooter(true)
    ->setHeaderTemplate('
        <div style="font-size: 9px; width: 100%; text-align: center;">
            Internal Document -- Do Not Distribute
        </div>
    ')
    ->setFooterTemplate('
        <div style="font-size: 8px; width: 100%; text-align: center; color: #999;">
            <span class="pageNumber"></span> / <span class="totalPages"></span>
        </div>
    ')
    ->setWaitForSelector('.content-ready')
    ->setTimeout(45000);

HtmlRenderer::create()
    ->loadUrl('https://dashboard.example.com/export')
    ->withOptions($options)
    ->save('/exports/dashboard.pdf');

Próximos pasos

• HTML Renderer -- Carga de contenido desde cadenas, archivos y URLs.
• Funciones avanzadas -- Fusión de PDFs, inyección de CSS, capturas de pantalla.