Package Artisan
Le package Artisan (yeeefang/tcpdf-next-artisan) fournit une conversion HTML-to-PDF au pixel près propulsée par Chrome DevTools Protocol (CDP). Il rend le HTML avec un support CSS3 complet -- incluant Flexbox, Grid, web fonts, media queries et animations figées au moment du rendu.
Quand utiliser Artisan
| Scénario | Recommandé |
|---|---|
| Générer un PDF depuis des templates HTML/CSS | Artisan |
| Construction programmatique de PDF (cellules, dessin) | Core |
| Emails HTML vers archive PDF | Artisan |
| Facture depuis données structurées | Core ou Artisan |
| Mises en page CSS complexes (Grid, Flexbox) | Artisan |
| PDF signés/chiffrés | Core |
Comment ça fonctionne
Artisan lance une instance Chrome headless via le Chrome DevTools Protocol, charge votre contenu HTML dans une page de navigateur et utilise la fonctionnalité print-to-PDF intégrée de Chrome. Cela signifie que chaque fonctionnalité CSS que Chrome supporte est disponible pour vos PDF -- plus besoin de lutter avec des parseurs CSS limités.
HTML/CSS --> ChromeBridge --> Chrome CDP --> binaire PDF --> save / streamInstallation
composer require yeeefang/tcpdf-next-artisanPrérequis :
- PHP 8.2+
chrome-php/chrome ^1.15(installé automatiquement)- Navigateur Chrome ou Chromium installé sur l'hôte
# Ubuntu/Debian
apt-get install -y chromium-browser
# macOS
brew install --cask chromium
# Windows (Chocolatey)
choco install googlechrome
# Définir un chemin personnalisé via variable d'environnement
export CHROME_PATH=/usr/bin/google-chromeDémarrage rapide
use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;
$renderer = HtmlRenderer::create();
$renderer
->loadHtml('<h1>Hello, World!</h1><p>Rendered with Chrome CDP.</p>')
->save('/output/hello.pdf');Depuis une URL
HtmlRenderer::create()
->loadUrl('https://example.com/report')
->save('/output/report.pdf');Depuis un fichier
HtmlRenderer::create()
->loadFile('/templates/invoice.html')
->save('/output/invoice.pdf');Contenu du package
| Classe | Objectif |
|---|---|
HtmlRenderer | Point d'entrée principal -- charger HTML, configurer, rendre |
ChromeBridge | Communication Chrome DevTools Protocol |
RenderOptions | Configuration de rendu (marges, échelle, en-têtes) |
PageSetup | Taille de page et orientation pour le rendu |
PdfMerger | Fusionner plusieurs pages rendues en un seul PDF |
StyleInjector | Injecter des feuilles de style CSS avant le rendu |
ScreenshotCapture | Capturer des captures d'écran de page (PNG/JPEG) |
Hiérarchie d'exceptions
| Exception | Quand |
|---|---|
RenderException | Échec de rendu générique |
ChromeNotFoundException | Binaire Chrome non trouvé au chemin attendu |
TimeoutException | Chargement de page ou rendu a dépassé le timeout configuré |
Toutes les exceptions vivent sous le namespace Yeeefang\TcpdfNext\Artisan\Exceptions et étendent une classe de base commune ArtisanException.
Comparaison avec le parseur HTML Core
Le package Core inclut un module HtmlParser pour conversion HTML-to-PDF basique. Utilisez-le quand vous avez besoin d'une solution sans dépendance. Utilisez Artisan quand vous avez besoin d'une fidélité de rendu navigateur complète.
| Fonctionnalité | Core HtmlParser | Artisan |
|---|---|---|
| Dépendance externe | Aucune | Chrome/Chromium |
| CSS Flexbox / Grid | Non | Oui |
Web fonts (@font-face) | Non | Oui |
| Media queries | Non | Oui |
| Exécution JavaScript | Non | Oui |
Règles CSS @page | Non | Oui |
| Performance (docs simples) | Plus rapide | Plus lent |
| Performance (CSS complexe) | N/A | Fiable |
Prochaines étapes
- HTML Renderer -- Chargement et rendu de contenu HTML.
- Options de rendu -- Configuration taille de page, marges, en-têtes et pieds de page.
- Fonctionnalités avancées -- Fusion PDF, injection CSS, captures d'écran.
- Configuration Docker -- Exécuter Artisan dans des conteneurs.