Vue d'ensemble de NextPDF Artisan
NextPDF Artisan est le pont Chrome de NextPDF. Il transmet un fragment HTML à un processus headless Chrome via le Chrome DevTools Protocol, capture la sortie printToPDF, puis intègre le résultat dans le document cible sous forme de Form XObject. Le texte incorporé reste sélectionnable et indexable par la recherche.
Vue d’ensemble conceptuelle
Section intitulée « Vue d’ensemble conceptuelle »Le package Artisan (nextpdf/artisan) étend le moteur open source NextPDF avec un moteur de rendu qui délègue la mise en page à Chrome. Le pipeline HTML natif de NextPDF couvre déjà un large sous-ensemble de CSS. Le pont Artisan sert aux documents qui exigent une mise en page de qualité Chrome — flexbox et grid CSS, polices web personnalisées chargées depuis des URI de données, et sélecteurs complexes — tout en produisant du texte vectoriel plutôt qu’une capture d’écran rasterisée.
Le pont est un pipeline composé de petits composants à responsabilité unique. ChromeHtmlRenderer orchestre un rendu. ChromeSecurityPolicy valide l’entrée et l’enveloppe dans un document HTML verrouillé. BrowserPool gère le cycle de vie du processus Chrome. ViewportCalculator fait correspondre les points PDF aux pixels CSS. Le lecteur NextPDF\Parser analyse la sortie de Chrome, et PageImporter la convertit en Form XObject. Chaque composant est final, injecté par constructeur et typé pour le niveau 10 de PHPStan.
Le pont est lié à une dépendance externe. Il a besoin de la bibliothèque chrome-php/chrome (^1.15) ainsi que d’un binaire Chrome ou Chromium accessible au processus PHP. Aucun des deux n’est fourni. Si la bibliothèque est absente, le pont lève ChromeNotAvailableException plutôt que de se dégrader silencieusement — voir /integrations/artisan/failure-modes/ sur la page /integrations/artisan/troubleshooting/.
Un rendu n’atteint jamais Chrome tant que l’entrée n’a pas été acceptée par ChromeSecurityPolicy::validate(), et le document transmis à Chrome est toujours enveloppé avec une Content-Security-Policy stricte et un blocage réseau CDP en défense en profondeur. Comme le pont traite du HTML potentiellement non fiable, sa posture de transport et d’isolation est documentée explicitement sur la page /integrations/artisan/security-and-operations/ plutôt que résumée ici.
Cela décrit le comportement observé du package tel qu’il est livré, vérifié par rapport à src/Artisan/ et à la suite tests/Unit/Artisan/. Il ne s’agit pas d’une revendication de parité pixel pour pixel avec un navigateur Chrome interactif : les animations sont capturées à leur image finale, la mise en page ne repose pas sur JavaScript, et seule la première page Chrome est importée.
Architecture
Section intitulée « Architecture »Responsabilités des composants
Section intitulée « Responsabilités des composants »| Composant | Responsabilité | Source |
|---|---|---|
ChromeHtmlRenderer | Orchestre un rendu unique ; renvoie ChromeRenderResult | src/Artisan/ChromeHtmlRenderer.php |
ChromeRendererConfig | Objet valeur de configuration immuable | src/Artisan/ChromeRendererConfig.php |
ChromeSecurityPolicy | Validation de l’entrée + enveloppe HTML sécurisée | src/Artisan/ChromeSecurityPolicy.php |
BrowserPool | Cycle de vie du processus Chrome et politique de redémarrage | src/Artisan/BrowserPool.php |
ViewportCalculator | Conversion 72 pt/inch ↔ 96 px/inch | src/Artisan/ViewportCalculator.php |
ChromeRenderResult | Sortie de rendu typée (ChromeRenderResultInterface) | src/Artisan/ChromeRenderResult.php |
PageImporter | Page Chrome analysée → ImportedFormXObject | src/Artisan/PageImporter.php |
EInvoiceServiceFactory | Fabrique sans conteneur pour les contrats de facturation électronique Premium | src/Artisan/EInvoiceServiceFactory.php |
Cas limites & pièges
Section intitulée « Cas limites & pièges »- Lignée de versions. L’artefact Composer publié porte le tag
v0.1.0. Les docblocks du code source portent@since 1.7.0(pont Chrome) et@since 1.1.0(fabrique de facturation électronique), tous deux hérités de la ligne de versionsnextpdf/cored’avant le renommage ; le package a été renomménextpdf/artisanà l’entrée du CHANGELOG2.0.0. Considère le tag Composer comme la version d’installation faisant autorité, et les marqueurs@sincecomme la provenance de version du moteur. - Première page seulement.
PageImporter::import()utilise par défaut l’index de page 0. Le contenu qui déborde sur une seconde page Chrome est tronqué, sauf si une hauteur explicite est fournie — ce point est traité sur la page /integrations/artisan/production-usage/. - Pas de conteneur DI. Artisan ne dépend d’aucun conteneur.
EInvoiceServiceFactoryfournit aux environnements dépourvus de conteneur de services une surface d’instanciation cohérente ; voir /integrations/artisan/boot-and-discovery/.
Performance
Section intitulée « Performance »Chaque rendu paie, à chaque appel, le coût du chargement de page Chrome et de printToPDF. BrowserPool maintient le processus Chrome en vie entre les rendus, et le redémarre tous les 100 rendus pour limiter la croissance de la mémoire. La complexité Big-O est dominée par la mise en page de l’entrée par Chrome, pas par le pont lui-même. Pour le budget mesuré du flux de référence de cette page, voir performance_budget dans le front-matter et la page /integrations/artisan/production-usage/.
Notes de sécurité
Section intitulée « Notes de sécurité »Le pont restitue du HTML potentiellement non fiable dans Chrome. L’entrée est validée en taille et en contenu avant que Chrome ne la voie. Le document enveloppé porte default-src 'none'. Un blocage au niveau CDP bloque chaque requête de sous-ressource. Le modèle complet de transport et d’isolation — y compris les limites explicites du drapeau de bac à sable de Chrome — se trouve sur la page /integrations/artisan/security-and-operations/. Ne considère pas cette section comme la posture de sécurité complète.
Contexte commercial
Section intitulée « Contexte commercial »Le pont open source restitue du HTML en PDF. Les niveaux Premium ajoutent l’intégration conforme de facturation électronique (Pro) et la validation (Enterprise) par-dessus le document restitué. Quand ces niveaux ne sont pas installés, EInvoiceServiceFactory renvoie null, si bien que le chemin open source reste pleinement fonctionnel sans eux.
Voir aussi
Section intitulée « Voir aussi »- /integrations/artisan/install/
- /integrations/artisan/configuration/
- /integrations/artisan/quickstart/
- /integrations/artisan/chrome-renderer-setup/
- /integrations/artisan/security-and-operations/
- /integrations/artisan/production-usage/