Render Options

La classe RenderOptions est un value object immuable qui contrôle comment Chrome rend votre HTML en PDF. Chaque setter retourne une nouvelle instance, gardant votre configuration prévisible et sans effets secondaires.

Création d'options

use Yeeefang\TcpdfNext\Artisan\RenderOptions;

// Démarrer avec valeurs par défaut sensées
$options = RenderOptions::create();

// Construire configuration de manière fluent
$options = RenderOptions::create()
    ->setPageSize('A4')
    ->setMargins(top: 15, right: 10, bottom: 15, left: 10)
    ->setPrintBackground(true);

Application des options

Passer les RenderOptions configurés à HtmlRenderer::withOptions().

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

HtmlRenderer::create()
    ->loadHtml('<h1>Sortie configurée</h1>')
    ->withOptions($options)
    ->save('/output/configuré.pdf');

Taille de page

Définir le format papier utilisant des noms de format standard.

$options = RenderOptions::create()
    ->setPageSize('A4');       // 210 x 297 mm (par défaut)

Formats supportés : A0-A6, B0-B6, Letter, Legal, Tabloid, Ledger.

Orientation

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

Marges

Définir marges individuelles en millimètres.

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

Lorsque templates en-tête ou pied de page sont activés, les marges haute et basse définissent l'espace réservé pour eux.

Échelle

Contrôler le facteur d'échelle de rendu. Valeurs de 0.1 à 2.0, avec 1.0 par défaut (100%).

// Réduire contenu à 80%
$options = RenderOptions::create()
    ->setScale(0.8);

// Agrandir contenu à 120%
$options = RenderOptions::create()
    ->setScale(1.2);

En-têtes et pieds de page

Chrome CDP supporte templates HTML pour en-têtes et pieds de page. Les templates ont accès à des classes CSS spéciales que Chrome remplace par des valeurs dynamiques au moment du rendu.

Classes CSS disponibles

Classe CSS	Remplacée par
.date	Date impression formatée
.title	Titre document
.url	URL document
.pageNumber	Numéro page actuelle
.totalPages	Nombre total de pages

Template en-tête

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

Template pied de page

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

En-tête et pied de page combinés

$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;">Rapport trimestriel</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>
    ');

Impression arrière-plan

Par défaut, Chrome omet couleurs et images d'arrière-plan (correspondant au comportement de dialogue d'impression navigateur). Activer rendu arrière-plan explicitement.

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

Règles CSS @page

Lorsqu'activées, les règles CSS @page dans votre HTML surchargent la taille de page et marges configurées dans RenderOptions.

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

Votre HTML peut alors contrôler la mise en page :

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

Attente de contenu

Attendre sélecteur DOM

Retarder le rendu jusqu'à ce qu'un élément spécifique apparaisse dans le DOM. Utile quand JavaScript génère du contenu dynamiquement.

$options = RenderOptions::create()
    ->setWaitForSelector('#graphique-rendu');

Timeout

Définir le temps maximal (en millisecondes) à attendre pour chargement et rendu de page. Par défaut 30000 (30 secondes).

$options = RenderOptions::create()
    ->setTimeout(60000);    // 60 secondes pour pages lourdes

Si le timeout est dépassé, une TimeoutException est levée.

Exemple complet

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;">
            Document interne — Ne pas distribuer
        </div>
    ')
    ->setFooterTemplate('
        <div style="font-size: 8px; width: 100%; text-align: center; color: #999;">
            <span class="pageNumber"></span> / <span class="totalPages"></span>
        </div>
    ')
    ->setWaitForSelector('.contenu-pret')
    ->setTimeout(45000);

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

Prochaines étapes

• HTML Renderer -- Charger contenu depuis chaînes, fichiers et URLs.
• Fonctionnalités avancées -- Fusion PDF, injection CSS, captures d'écran.