Prise en main rapide d'Artisan

En un coup d’œil

Associe un ChromeRendererConfig à un document NextPDF, appelle writeHtmlChrome(), puis enregistre le résultat. Chrome effectue le rendu du HTML ; le pont importe le résultat sous forme de Form XObject, et le texte reste sélectionnable.

Vue d’ensemble conceptuelle

writeHtmlChrome() est une méthode du cœur NextPDF exposée par le Document et fournie par le trait HasTextOutput. La méthode valide l’entrée, résout le renderer Artisan, envoie le HTML à Chrome, analyse le PDF renvoyé, puis intègre la page 0 sous forme de Form XObject à la position courante du curseur. La signature publique est writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static — vérifiée à partir de nextpdf/coresrc/Core/Concerns/HasTextOutput.php.

Exemple de code — Démarrage rapide

quickstart.php

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Artisan\ChromeRendererConfig;

require __DIR__ . '/vendor/autoload.php';

$config = new ChromeRendererConfig(
    chromeBinaryPath: '/usr/bin/chromium',
);

$doc = Document::createStandalone();
$doc->setChromeRendererConfig($config);
$doc->addPage();

$doc->writeHtmlChrome('
    <div style="display: flex; gap: 20px; font-family: sans-serif;">
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Revenue</h2><p style="font-size: 2em; color: #2563eb;">$124,500</p>
        </div>
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Orders</h2><p style="font-size: 2em; color: #16a34a;">1,847</p>
        </div>
    </div>
');

$doc->save('/tmp/report.pdf');

C’est le flux de référence présenté dans le README.md du paquet. Chrome gère la mise en page flex. Les chiffres restent du texte sélectionnable dans la sortie, car la page est intégrée sous forme de Form XObject, et non sous forme d’image matricielle.

Taille de page personnalisée

Passe une largeur et une hauteur explicites en points PDF pour utiliser un format de page fixe (ici, A4) :

$doc->writeHtmlChrome($html, width: 595.28, height: 841.89);

Lorsque tu fournis les deux valeurs, Chrome imprime exactement à cette taille de papier. Lorsque tu omets la hauteur (ou que tu passes null), le pont s’ajuste automatiquement à la hauteur du contenu mesurée et ajoute une petite marge de sécurité pour le reflux. Consulte /integrations/artisan/production-usage/ pour comprendre pourquoi cette marge existe et dans quels cas la remplacer.

Ce que tu obtiens

Propriété	Comportement
Texte	Sélectionnable et indexable par la recherche (texte vectoriel, non rasterisé)
CSS	Mise en page Chrome — flexbox, grid, sélecteurs complexes, polices web via URI data
Réseau	Aucune récupération de sous-ressource ; les URL distantes ne se chargent pas (voir /integrations/artisan/security-and-operations/)
Pages	La page 0 de la sortie Chrome est importée

Cas limites & pièges

• Un HTML vide est sans effet. writeHtmlChrome('') renvoie le document inchangé (vérifié dans HasTextOutput::writeHtmlChrome).
• Aucune page existante. Si aucune page n’existe, writeHtmlChrome() en ajoute une avant le rendu.
• Les ressources distantes ne se chargent pas. <img src="https://..."> est rendu vide. Intègre les ressources sous forme d’URI data:. C’est la posture d’isolation réseau, et non un bug. Voir /integrations/artisan/security-and-operations/.
• Pont absent. Si nextpdf/artisan n’est pas installé, le cœur lève une exception liée à la disposition plutôt qu’une erreur fatale.

Performances

Le premier appel supporte le coût du démarrage de Chrome et de la mise en page. Les appels suivants réutilisent le processus Chrome actif via BrowserPool. Pour les traitements par lots ou les workers de longue durée, consulte les conseils sur le cycle de vie et les ressources sur la page /integrations/artisan/production-usage/.

Notes de sécurité

Le démarrage rapide utilise un HTML de confiance, codé en dur. Avant de transmettre le moindre HTML influencé par l’utilisateur à writeHtmlChrome(), lis /integrations/artisan/security-and-operations/. Le pont isole les accès réseau, mais le rendu HTML conserve une surface d’attaque.

Contexte commercial

Ce flux produit un PDF à partir de HTML à l’aide du pont open source. Pour intégrer un XML de facture électronique conforme dans le même document, le niveau Premium Pro fournit un intégrateur. Le parcours open source n’est pas affecté lorsque Premium est absent.

Voir aussi

• /integrations/artisan/install/
• /integrations/artisan/configuration/
• /integrations/artisan/production-usage/
• /integrations/artisan/troubleshooting/
• /integrations/artisan/security-and-operations/