Migrer depuis DomPDF
Ce guide vous aide à migrer de DomPDF (dompdf/dompdf) vers TCPDF-Next. Les deux bibliothèques ont des philosophies de conception fondamentalement différentes — DomPDF est un moteur de rendu HTML/CSS vers PDF, tandis que TCPDF-Next est une bibliothèque PDF native avec un puissant moteur de rendu HTML.
Approche DomPDF vs approche TCPDF-Next
DomPDF traite la génération PDF comme un rendu HTML. Vous écrivez du HTML et CSS, et DomPDF le convertit en PDF. C'est pratique mais vous limite à ce que CSS peut exprimer, sans accès aux fonctionnalités natives PDF comme les signatures numériques, le chiffrement ou la conformité PDF/A.
TCPDF-Next offre deux approches :
| Approche | Description | Idéal pour |
|---|---|---|
| API Core | Construction PDF directe via méthodes PHP | Mises en page précises, formulaires, graphiques, signatures |
| Artisan HTML Renderer | Moteur de rendu HTML/CSS basé sur DOM (HtmlRenderer) | Contenu riche en HTML, migration depuis DomPDF |
Pour la plupart des migrations DomPDF, utilisez le Artisan HTML Renderer — il accepte vos modèles HTML existants avec des modifications minimales.
Mapping API
| DomPDF | TCPDF-Next | Notes |
|---|---|---|
new Dompdf($options) | PdfDocument::create()->build() | Constructeur fluide |
$dompdf->loadHtml($html) | $renderer->writeHtml($html) | Même HTML fonctionne |
$dompdf->loadHtmlFile($url) | $renderer->writeHtmlFile($path) | Fichiers locaux uniquement par défaut |
$dompdf->setPaper('A4', 'portrait') | ->setPageFormat(PageFormat::A4) | Basé sur enum |
$dompdf->render() | Automatique sur save() / toString() | Pas d'étape de rendu explicite |
$dompdf->output() | $pdf->toString() | Retourne chaîne binaire |
$dompdf->stream('file.pdf') | Helpers de réponse framework | Voir exemples ci-dessous |
$options->set('defaultFont', ...) | $renderer->setDefaultFont(...) | |
$options->set('isRemoteEnabled', true) | ResourcePolicy::allowDomain(...) | Liste blanche explicite |
$options->set('chroot', $dir) | ResourcePolicy::allowLocalDirectory(...) | Contrôle plus granulaire |
Exemple de migration basique
DomPDF (avant) :
use Dompdf\Dompdf;
use Dompdf\Options;
$options = new Options();
$options->set('defaultFont', 'Helvetica');
$options->set('isRemoteEnabled', true);
$dompdf = new Dompdf($options);
$dompdf->loadHtml($html);
$dompdf->setPaper('A4', 'portrait');
$dompdf->render();
file_put_contents('output.pdf', $dompdf->output());TCPDF-Next (après) :
use YeeeFang\TcpdfNext\Document\PdfDocument;
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Html\HtmlRenderer;
$pdf = PdfDocument::create()
->setPageFormat(PageFormat::A4)
->build();
$renderer = new HtmlRenderer($pdf);
$renderer->setDefaultFont('Helvetica', size: 12);
$renderer->writeHtml($html);
$pdf->save('output.pdf');Comparaison du support CSS
| Fonctionnalité CSS | DomPDF | TCPDF-Next |
|---|---|---|
| Modèle de boîte (margin, padding, border) | Oui | Oui |
| Floats | Partiel | Partiel |
| Flexbox | Non | Non |
| Grid | Non | Non |
position: absolute/relative | Partiel | Oui |
@font-face | Oui | Oui |
page-break-before/after | Oui | Oui |
background-image | Partiel | Oui |
border-radius | Non | Oui |
opacity | Oui | Oui |
Variables CSS (--custom) | Non | Non |
| Media queries | Non | @media print uniquement |
Mise en page table | Oui | Oui (amélioré) |
TIP
Le moteur de rendu HTML de TCPDF-Next supporte la plupart des propriétés CSS 2.1 et certaines propriétés CSS 3 sélectionnées. Flexbox et Grid ne sont pas supportés — utilisez des tableaux pour les mises en page complexes. Si vous rencontrez des différences de rendu CSS, consultez la documentation HTML Renderer.
Quand utiliser Core vs Artisan
| Scénario | Approche recommandée |
|---|---|
| Migrer des modèles HTML existants | Artisan HTML Renderer |
| Mises en page au pixel près (factures, certificats) | API Core |
| Signatures numériques requises | API Core (signature fonctionne avec les deux, mais Core donne plus de contrôle) |
| Conformité PDF/A | L'une ou l'autre (les deux supportent PDF/A-4) |
| Codes-barres / QR codes | API Core (rendu vectoriel natif) |
| Formulaires avec champs modifiables | API Core |
| Rapports simples depuis HTML | Artisan HTML Renderer |
Comparaison des performances
| Métrique | DomPDF | TCPDF-Next | Amélioration |
|---|---|---|---|
| PDF simple 1 page | 62.1 ms | 8.2 ms | 7.6x plus rapide |
| Rapport 20 pages | 891 ms | 187 ms | 4.8x plus rapide |
| Mémoire pic (1 page) | 22.1 MB | 4.2 MB | 5.3x moins |
| Mémoire pic (20 pages) | 89.7 MB | 12.4 MB | 7.2x moins |
| Taille fichier sortie (1 page) | 31.8 KB | 12.4 KB | 2.6x plus petit |
Voir Benchmarks de performance pour la méthodologie détaillée et cas de test supplémentaires.
Nouvelles capacités après migration
Fonctionnalités disponibles dans TCPDF-Next que DomPDF ne supporte pas :
- Signatures numériques — PAdES B-B à B-LTA avec support de module de sécurité matériel.
- Chiffrement AES-256 — Protection de document par mot de passe et certificat.
- PDF/A-4 — Conformité d'archivage complète (ISO 19005-4).
- PDF balisé / PDF/UA — Accessibilité pour lecteurs d'écran.
- Codes-barres natifs — QR, Data Matrix, Code 128, EAN et plus en graphiques vectoriels.
- Champs de formulaire — Champs de texte modifiables, cases à cocher, listes déroulantes.
- Flux de références croisées — Fichiers plus petits avec structure PDF moderne.
Lecture complémentaire
- Table de mapping API — Mapping détaillé de méthodes
- Benchmarks — Comparaison complète des performances
- Aperçu Sécurité — Améliorations de sécurité par rapport à DomPDF
- Référence API — Documentation API complète TCPDF-Next