Guide développeur Artisan

En bref

Le package Artisan a deux responsabilités liées : rendre du HTML via Chrome et importer le PDF obtenu comme page dans un document NextPDF. Lors du débogage, traite séparément les limites de responsabilité de Chrome, du parser et de l’importateur.

Utilise ce guide lorsque tu écris des intégrations de renderer, des workers à longue durée de vie, des diagnostics de parser ou des tests autour de nextpdf/artisan.

Frontière d’architecture

Couche	Détenue par	Responsabilité	À ne pas mettre ici
Application	Application	Autoriser la génération du HTML et choisir la configuration du renderer.	Gestion du processus du navigateur.
Politique HTML	Application et package	Refuser le HTML dangereux ou surdimensionné avant le rendu.	Autorisation de tenant ou décisions métier.
Renderer Chrome	`nextpdf/artisan`	Rendre le HTML sous forme d’un PDF autonome produit par Chrome.	Réparation générale de PDF ou édition arbitraire de PDF.
Parser/importateur	`nextpdf/artisan`	Analyser le PDF rendu et importer une page comme form XObject.	Validation complète de la conformité PDF.
Moteur central	`nextpdf/nextpdf`	Placer les objets de formulaire importés et écrire le document final.	Cycle de vie CDP de Chrome.

Cycle de vie à l’exécution

Étape	Comportement	Action du développeur
Création de la configuration	`ChromeRendererConfig` définit le binaire, le timeout, le CSS, la taille d’entrée et le comportement du sandbox.	Utilise une configuration propre à l’environnement plutôt que des hypothèses codées en dur à l’exécution.
Création du renderer	`ChromeHtmlRenderer` possède un `BrowserPool`.	Réutilise le renderer au sein d’un worker, puis ferme-le à l’arrêt.
Validation du HTML	La politique de sécurité vérifie la taille et enveloppe le document avec le CSS par défaut.	Valide l’autorisation de l’appelant avant cette étape.
Impression Chrome	Le CDP produit le rendu sous forme de PDF autonome.	Garde les ressources externes bloquées, sauf si une politique ayant fait l’objet d’une revue les autorise.
Analyse du PDF	`PdfReader::parse()` lit les données xref, les pages, les objets, les ressources et les révisions.	Traite les échecs du parser comme des échecs de rendu, sauf si le diagnostic est l’objectif.
Import de la page	`PageImporter::import()` extrait le contenu de la page, la media box, les ressources et les objets embarqués.	Importe la page `0` sauf si le workflow choisit délibérément une autre page.

Structure d’application recommandée

Chemin	Rôle
`app/Pdf/Renderers/*`	Wrapper applicatif autour de `ChromeHtmlRenderer`.
`app/Pdf/Templates/*`	Rendu des templates HTML et mapping DTO-vers-vue.
`app/Pdf/Policies/*`	Politique de rendu pour la taille du HTML, les ressources et le tenant.
`tests/Pdf/Renderer/*`	Tests de fumée du renderer avec de petits fixtures HTML.
`tests/Pdf/Parser/*`	Fixtures de parser pour la sortie Chrome importée.

Garde le rendu des templates séparé du rendu par le navigateur. Le renderer doit recevoir le HTML final et une largeur de page connue.

<?php

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\PageImporter;
use NextPDF\Parser\PdfReader;

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig(
    renderTimeout: 30,
    maxHtmlSize: 1_000_000,
));

$result = $renderer->render($html, widthPt: 595.28);

$reader = new PdfReader($result->getPdfData());
$reader->parse();

$form = (new PageImporter())->import($reader);

Modèle de renderer

Crée un renderer par processus worker ou par portée de requête. Réutiliser le renderer évite de répéter le coût de démarrage de Chrome. Le fermer explicitement évite les fuites de processus lors de l’arrêt du worker.

<?php

final class InvoiceChromeRenderer
{
    public function __construct(
        private readonly ChromeHtmlRenderer $renderer,
    ) {}

    public function renderInvoice(string $html): string
    {
        return $this->renderer
            ->render($html, widthPt: 595.28)
            ->getPdfData();
    }

    public function close(): void
    {
        $this->renderer->close();
    }
}

Modèle de diagnostic du parser

Les API du parser sont utiles lorsque la sortie de Chrome ne peut pas être importée. Garde les diagnostics en lecture seule et évite de modifier l’état du parser après un import réussi.

Question de diagnostic	API à utiliser	Signal attendu
Le fichier s’analyse-t-il ?	`PdfReader::parse()`	Lève une exception en cas de structure PDF invalide.
La page `0` existe-t-elle ?	`PdfReader::getPage(0)`	Renvoie un `PdfObject`.
Y a-t-il du contenu ?	`PdfReader::getPageContentStream($page)`	Flux de contenu non vide.
Les ressources sont-elles présentes ?	`PdfReader::getPageResources($page)`	Tableau du dictionnaire de ressources.
Y a-t-il des révisions incrémentales ?	`PdfReader::getRevisionCount()`	Nombre supérieur à un.
Quel objet a échoué ?	`PdfTokenizer::getOffset()` et le contexte d’exception du parser.	Décalage en octets permettant de réduire le fixture.

Points d’extension

Point d’extension	À utiliser pour	Contrainte
`ChromeRendererConfig::fromArray()`	Mapping depuis la configuration du framework.	Les valeurs optionnelles inconnues ou mal typées reviennent aux valeurs par défaut.
`HtmlSecurityPolicyInterface`	Politique HTML au niveau de l’analyse.	Ne remplace pas les contrôles de transport, de processus ou d’autorisation.
`LoggerInterface`	Diagnostics de rendu et de navigateur.	Ne journalise pas le contenu HTML par défaut.
`BrowserPool`	Réutilisation d’un processus Chrome à longue durée de vie.	Doit être fermé à l’arrêt du worker.
`PageImporter`	Incorporer une page externe analysée.	Le reader doit d’abord avoir été analysé.
Classes du parser	Diagnostics et sortie Chrome importée.	Ce n’est pas une boîte à outils générale de réparation de PDF.

Workflow de développement

Reproduis le fragment HTML dans un test de rendu minimal.
Vérifie maxHtmlSize, le CSS par défaut et le chemin du binaire Chrome.
Effectue le rendu avec une largeur fixe en points.
Analyse les octets PDF renvoyés avec PdfReader::parse().
Importe la page 0 sauf si le workflow choisit délibérément une autre page.
Ajoute des tests sur fixture pour le plus petit fragment HTML qui reproduit chaque échec.
Ferme le renderer dans les hooks d’arrêt du worker.

Gestion des échecs

Échec	Où il devrait être géré	Réponse recommandée
Binaire Chrome manquant	Vérification du déploiement et chemin de création du renderer.	Fais échouer la vérification de disponibilité avant d’accepter du trafic de rendu.
HTML surdimensionné	Politique HTML.	Rejette avant de démarrer Chrome.
Timeout du navigateur	Frontière du renderer.	Fais échouer le rendu et enregistre le nom du template, la taille, la largeur et le timeout.
Échec du parser	Frontière d’import.	Stocke un petit fixture assaini pour le débogage quand la politique l’autorise.
Fuite de processus de navigateur	Cycle de vie du worker.	Ferme-le à l’arrêt et redémarre-le après un nombre contrôlé de rendus.

Valeurs par défaut sûres

Préoccupation	Valeur par défaut	Quand la remplacer
Timeout de rendu	`30` secondes.	Augmente-le uniquement pour des documents mesurés et bornés.
Taille HTML maximale	`5,000,000` octets.	Abaisse-la pour les endpoints publics.
Sandbox	Activé.	Désactive-le uniquement quand les contraintes du conteneur l’exigent et que l’hôte est isolé.
Hauteur	Automatique quand `heightPt <= 0`.	Utilise une hauteur fixe pour des contraintes strictes de mise en page.
Ressources externes	Bloquées par la politique du renderer.	Ne les autorise que via une politique de ressources revue.

Liste de vérification des tests

Les tests de rendu couvrent du HTML et du CSS représentatifs.
Les tests de sécurité couvrent le HTML surdimensionné et les tentatives d’accès à des ressources bloquées.
Les tests d’import vérifient que l’objet de formulaire renvoyé a du contenu, une media box et des ressources.
Les tests de parser couvrent la table xref, le flux xref, le flux d’objets et les cas de fixtures mal formés.
Les tests de worker appellent close() et confirment qu’aucun processus de navigateur ne subsiste.
Les tests de performance enregistrent le temps de rendu par template et par taille de contenu.