Migrar desde DomPDF
Esta guía te ayuda a migrar de DomPDF (dompdf/dompdf) a TCPDF-Next. Las dos bibliotecas tienen filosofías de diseño fundamentalmente diferentes — DomPDF es un renderizador de HTML/CSS a PDF, mientras que TCPDF-Next es una biblioteca nativa de PDF con un potente motor de renderizado HTML.
Enfoque DomPDF vs enfoque TCPDF-Next
DomPDF trata la generación de PDF como renderizado HTML. Escribes HTML y CSS, y DomPDF lo convierte a PDF. Esto es conveniente pero te limita a lo que CSS puede expresar, sin acceso a funcionalidades nativas de PDF como firmas digitales, cifrado o cumplimiento PDF/A.
TCPDF-Next ofrece dos enfoques:
| Enfoque | Descripción | Ideal para |
|---|---|---|
| Core API | Construcción directa de PDF via métodos PHP | Layouts de precisión, formularios, gráficos, firmas |
| Artisan HTML Renderer | Renderizador HTML/CSS basado en DOM (HtmlRenderer) | Contenido con mucho HTML, migración desde DomPDF |
Para la mayoría de las migraciones desde DomPDF, usa el Artisan HTML Renderer — acepta tus plantillas HTML existentes con cambios mínimos.
Mapeo de API
| DomPDF | TCPDF-Next | Notas |
|---|---|---|
new Dompdf($options) | PdfDocument::create()->build() | Builder fluent |
$dompdf->loadHtml($html) | $renderer->writeHtml($html) | El mismo HTML funciona |
$dompdf->loadHtmlFile($url) | $renderer->writeHtmlFile($path) | Solo archivos locales por defecto |
$dompdf->setPaper('A4', 'portrait') | ->setPageFormat(PageFormat::A4) | Basado en enum |
$dompdf->render() | Automático en save() / toString() | Sin paso de render explícito |
$dompdf->output() | $pdf->toString() | Retorna string binario |
$dompdf->stream('file.pdf') | Helpers de respuesta del framework | Ver ejemplos abajo |
$options->set('defaultFont', ...) | $renderer->setDefaultFont(...) | |
$options->set('isRemoteEnabled', true) | ResourcePolicy::allowDomain(...) | Allowlist explícita |
$options->set('chroot', $dir) | ResourcePolicy::allowLocalDirectory(...) | Control más granular |
Ejemplo básico de migración
DomPDF (antes):
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 (despué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');Comparación de soporte CSS
| Funcionalidad CSS | DomPDF | TCPDF-Next |
|---|---|---|
| Box model (margin, padding, border) | Sí | Sí |
| Floats | Parcial | Parcial |
| Flexbox | No | No |
| Grid | No | No |
position: absolute/relative | Parcial | Sí |
@font-face | Sí | Sí |
page-break-before/after | Sí | Sí |
background-image | Parcial | Sí |
border-radius | No | Sí |
opacity | Sí | Sí |
Variables CSS (--custom) | No | No |
| Media queries | No | Solo @media print |
Layout table | Sí | Sí (mejorado) |
TIP
El renderizador HTML de TCPDF-Next soporta la mayoría de las propiedades CSS 2.1 y propiedades seleccionadas de CSS 3. Flexbox y Grid no están soportados — usa tablas para layouts complejos. Si encuentras diferencias de renderizado CSS, consulta la documentación del renderizador HTML.
Cuándo usar Core vs Artisan
| Escenario | Enfoque recomendado |
|---|---|
| Migrar plantillas HTML existentes | Artisan HTML Renderer |
| Layouts pixel-perfect (facturas, certificados) | Core API |
| Firmas digitales requeridas | Core API (firmar funciona con ambos, pero Core da más control) |
| Cumplimiento PDF/A | Cualquiera (ambos soportan PDF/A-4) |
| Códigos de barras / QR | Core API (renderizado vectorial nativo) |
| Formularios con campos rellenables | Core API |
| Reportes simples desde HTML | Artisan HTML Renderer |
Comparación de rendimiento
| Métrica | DomPDF | TCPDF-Next | Mejora |
|---|---|---|---|
| PDF simple de 1 página | 62.1 ms | 8.2 ms | 7.6x más rápido |
| Reporte de 20 páginas | 891 ms | 187 ms | 4.8x más rápido |
| Memoria pico (1 página) | 22.1 MB | 4.2 MB | 5.3x menos |
| Memoria pico (20 páginas) | 89.7 MB | 12.4 MB | 7.2x menos |
| Tamaño de archivo (1 página) | 31.8 KB | 12.4 KB | 2.6x más pequeño |
Consulta Benchmarks de rendimiento para la metodología detallada y casos de prueba adicionales.
Nuevas capacidades después de migrar
Funcionalidades disponibles en TCPDF-Next que DomPDF no soporta:
- Firmas digitales — PAdES B-B hasta B-LTA con soporte de módulos de seguridad hardware.
- Cifrado AES-256 — Protección de documentos basada en contraseña y certificado.
- PDF/A-4 — Cumplimiento archivístico completo (ISO 19005-4).
- Tagged PDF / PDF/UA — Accesibilidad para lectores de pantalla.
- Códigos de barras nativos — QR, Data Matrix, Code 128, EAN y más como gráficos vectoriales.
- Campos de formulario — Campos de texto, checkboxes y dropdowns rellenables.
- Cross-reference streams — Archivos más pequeños con estructura PDF moderna.
Lectura adicional
- Tabla de mapeo de API — Mapeo detallado de métodos
- Benchmarks — Comparación completa de rendimiento
- Resumen de seguridad — Mejoras de seguridad respecto a DomPDF
- Referencia de API — Documentación completa de la API de TCPDF-Next