Migrar desde mPDF

Esta guía te ayuda a migrar de mPDF (mpdf/mpdf) a TCPDF-Next. mPDF es una biblioteca de HTML a PDF con amplio soporte CSS y funcionalidades como texto CJK, códigos de barras y marcas de agua. TCPDF-Next ofrece un superconjunto de las capacidades de mPDF con cumplimiento de estándares modernos y cero dependencias en tiempo de ejecución.

Comparación de funcionalidades

Funcionalidad	mPDF	TCPDF-Next
Versión de PHP	7.4+	8.5+
Versión de PDF	PDF 1.4 / 1.7	PDF 2.0
Arquitectura	Centrada en HTML/CSS	Nativa de PDF con soporte HTML
Dependencias en runtime	10+ paquetes Composer	Cero
Cifrado	RC4, AES-128, AES-256	Solo AES-256 (PDF 2.0)
Firmas digitales	No soportado	PAdES B-B hasta B-LTA
PDF/A	PDF/A-1b, PDF/A-3b (parcial)	PDF/A-4 (ISO 19005-4 completo)
Tagged PDF	Limitado	Accesibilidad PDF/UA completa
Soporte CJK	Sí (fuentes incluidas 50+ MB)	Sí (registra las tuyas, subsetting optimizado)
RTL / BiDi	Sí	Sí (compatible con UAX #9)
Códigos de barras	Sí (1D y 2D)	Sí (vectorial nativo, conjunto ampliado)
Marcas de agua	Sí	Sí
Generación de TOC	Sí	Sí
Uso de memoria	Alto (DOM completo en memoria)	Moderado (salida en streaming)

Funcionalidades específicas de mPDF y equivalentes en TCPDF-Next

Tags HTML personalizados

mPDF define tags HTML no estándar. Estos requieren adaptación:

Tag personalizado de mPDF	Equivalente en TCPDF-Next
<tocpagebreak>	$pdf->addTableOfContentsPage()
<tocentry content="..." level="0">	$toc->addEntry('...', level: 0)
<barcode code="..." type="C128">	$page->addBarcode(BarcodeFactory::code128('...'))
<columnbreak>	$renderer->columnBreak()
<pagebreak>	<div style="page-break-before: always"> (CSS estándar)
<bookmark content="...">	$pdf->addBookmark('...')
<watermarktext content="DRAFT">	$pdf->setWatermark(Watermark::text('DRAFT'))
<watermarkimage src="...">	$pdf->setWatermark(Watermark::image('...'))

Headers y footers HTML

mPDF (antes):

$mpdf->SetHTMLHeader('<div style="text-align: center;">Header</div>');
$mpdf->SetHTMLFooter('<div>Page {PAGENO} of {nbpg}</div>');
$mpdf->SetHTMLHeader('<div>Even header</div>', 'E');

TCPDF-Next (después):

$pdf->setHtmlHeader('<div style="text-align: center;">Header</div>');
$pdf->setHtmlFooter('<div>Page {{pageNumber}} of {{totalPages}}</div>');
$pdf->setHtmlHeader('<div>Even header</div>', pages: 'even');

Modos de WriteHTML

mPDF (antes):

$mpdf->WriteHTML($css, \Mpdf\HTMLParserMode::HEADER_CSS);
$mpdf->WriteHTML($body, \Mpdf\HTMLParserMode::HTML_BODY);

TCPDF-Next (después):

$renderer = new HtmlRenderer($pdf);
$renderer->addStylesheet($css);
$renderer->writeHtml($body);

Marcas de agua

mPDF (antes):

$mpdf->SetWatermarkText('DRAFT', 0.1);
$mpdf->showWatermarkText = true;

TCPDF-Next (después):

$pdf->setWatermark(
    Watermark::text('DRAFT')
        ->setOpacity(0.1)
        ->setRotation(45)
        ->setColor(Color::rgb(200, 200, 200))
);

Mapeo de configuración

Config de mPDF	Equivalente en TCPDF-Next
mode => 'utf-8'	Siempre UTF-8 (no necesita configuración)
format => 'A4'	setPageFormat(PageFormat::A4)
margin_left/right/top/bottom	setMargins(new Margins(...))
default_font	$renderer->setDefaultFont(...)
tempDir	PdfDocument::create()->setTempDir(...)
autoScriptToLang	$renderer->setAutoFontDetection(true)
biDirectional	Siempre habilitado (UAX #9)
pdfaAuto	setPdfALevel(PdfALevel::PDF_A_4)

Métodos de salida

mPDF (antes):

$mpdf->Output('/path/to/file.pdf', \Mpdf\Output\Destination::FILE);
$mpdf->Output('doc.pdf', \Mpdf\Output\Destination::DOWNLOAD);
$mpdf->Output('doc.pdf', \Mpdf\Output\Destination::INLINE);
$content = $mpdf->Output('', \Mpdf\Output\Destination::STRING_RETURN);

TCPDF-Next (después):

$pdf->save('/path/to/file.pdf');
$bytes = $pdf->toString();

// Respuesta web (ejemplo Laravel)
return response($pdf->toString(), 200, [
    'Content-Type' => 'application/pdf',
    'Content-Disposition' => 'attachment; filename="doc.pdf"',
]);

Reducción de dependencias

Migrar desde mPDF simplifica drásticamente tu árbol de dependencias:

Eliminadas (mPDF + transitivas):

• mpdf/mpdf + 10+ paquetes transitivos
• psr/log, psr/http-message, setasign/fpdi, mpdf/qrcode

Añadidas:

• yeee-fang/tcpdf-next (cero dependencias en runtime)

Comparación de rendimiento

Métrica	mPDF	TCPDF-Next	Mejora
PDF simple de 1 página	45.3 ms	8.2 ms	5.5x más rápido
Documento de 100 páginas	3,210 ms	845 ms	3.8x más rápido
Memoria pico (1 página)	18.4 MB	4.2 MB	4.4x menos
Memoria pico (100 páginas)	198.2 MB	28.6 MB	6.9x menos
Tamaño de archivo (1 página)	24.3 KB	12.4 KB	2.0x más pequeño

Consulta Benchmarks de rendimiento para la metodología completa y casos de prueba.

Lectura adicional

• Tabla de mapeo de API — Mapeo completo de métodos
• Benchmarks — Comparación completa de rendimiento con mPDF
• Referencia de API — Documentación completa de la API de TCPDF-Next
• FAQ — Preguntas frecuentes sobre migración