Render Options

La classe RenderOptions è un value object immutabile che controlla come Chrome renderizza il tuo HTML a PDF. Ogni setter restituisce una nuova istanza, mantenendo la tua configurazione prevedibile e senza effetti collaterali.

Creare Options

use Yeeefang\TcpdfNext\Artisan\RenderOptions;

// Inizia con default sensibili
$options = RenderOptions::create();

// Costruisci configurazione fluently
$options = RenderOptions::create()
    ->setPageSize('A4')
    ->setMargins(top: 15, right: 10, bottom: 15, left: 10)
    ->setPrintBackground(true);

Applicare Options

Passa il RenderOptions configurato a HtmlRenderer::withOptions().

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

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

Dimensione Pagina

Imposta il formato carta usando nomi formato standard.

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

Formati supportati: A0--A6, B0--B6, Letter, Legal, Tabloid, Ledger.

Orientamento

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

Margini

Imposta margini individuali in millimetri.

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

Quando i template header o footer sono abilitati, i margini top e bottom definiscono lo spazio riservato per essi.

Scala

Controlla il fattore scala rendering. I valori vanno da 0.1 a 2.0, con 1.0 come predefinito (100%).

// Riduci contenuto all'80%
$options = RenderOptions::create()
    ->setScale(0.8);

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

Header e Footer

Chrome CDP supporta template HTML per header e footer. I template hanno accesso a classi CSS speciali che Chrome sostituisce con valori dinamici al momento del rendering.

Classi CSS Disponibili

Classe CSS	Sostituita Con
.date	Data stampa formattata
.title	Titolo documento
.url	URL documento
.pageNumber	Numero pagina corrente
.totalPages	Numero totale pagine

Template Header

$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 -- Confidenziale</span>
            <span class="date"></span>
        </div>
    ');

Template Footer

$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;">
            Pagina <span class="pageNumber"></span> di <span class="totalPages"></span>
        </div>
    ');

Header e Footer Combinati

$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;">Rapporto Trimestrale</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>Pagina <span class="pageNumber"></span> / <span class="totalPages"></span></span>
        </div>
    ');

Stampa Background

Per impostazione predefinita, Chrome omette colori e immagini background (corrispondente al comportamento dialogo stampa browser). Abilita rendering background esplicitamente.

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

Regole CSS @page

Quando abilitato, le regole CSS @page nel tuo HTML sovrascrivono la dimensione pagina e margini configurati in RenderOptions.

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

Il tuo HTML può quindi controllare il layout:

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

Attendere Contenuto

Attendi un Selettore DOM

Ritarda il rendering finché un elemento specifico appare nel DOM. Utile quando JavaScript genera contenuto dinamicamente.

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

Timeout

Imposta il tempo massimo (in millisecondi) per attendere caricamento pagina e rendering. Predefinito a 30000 (30 secondi).

$options = RenderOptions::create()
    ->setTimeout(60000);    // 60 secondi per pagine pesanti

Se il timeout viene superato, viene lanciata una TimeoutException.

Esempio 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;">
            Documento Interno -- Non Distribuire
        </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');

Prossimi Passi

• HTML Renderer -- Caricamento contenuto da stringhe, file e URL.
• Funzionalità Avanzate -- Unione PDF, iniezione CSS, screenshot.