Migrar do mPDF

Este guia ajuda você a migrar do mPDF (mpdf/mpdf) para o TCPDF-Next. O mPDF é uma biblioteca HTML para PDF com amplo suporte CSS e recursos como texto CJK, códigos de barras e marcas d'água. O TCPDF-Next oferece um superconjunto das capacidades do mPDF com conformidade a padrões modernos e zero dependências de runtime.

Comparação de Recursos

Recurso	mPDF	TCPDF-Next
Versão PHP	7.4+	8.5+
Versão PDF	PDF 1.4 / 1.7	PDF 2.0
Arquitetura	Centrada em HTML/CSS	PDF-nativa com suporte HTML
Dependências de runtime	10+ pacotes Composer	Zero
Criptografia	RC4, AES-128, AES-256	Apenas AES-256 (PDF 2.0)
Assinaturas digitais	Não suportado	PAdES B-B até B-LTA
PDF/A	PDF/A-1b, PDF/A-3b (parcial)	PDF/A-4 (ISO 19005-4 completo)
PDF com tags	Limitado	Acessibilidade PDF/UA completa
Suporte CJK	Sim (fontes incluídas 50+ MB)	Sim (registre as suas, subsetting otimizado)
RTL / BiDi	Sim	Sim (conforme UAX #9)
Códigos de barras	Sim (1D e 2D)	Sim (vetorial nativo, conjunto expandido)
Marcas d'água	Sim	Sim
Geração de TOC	Sim	Sim
Uso de memória	Alto (DOM completo em memória)	Moderado (saída em streaming)

Recursos Específicos do mPDF e Equivalentes no TCPDF-Next

Tags HTML Personalizadas

O mPDF define tags HTML não-padrão. Estas requerem adaptação:

Tag Personalizada mPDF	Equivalente 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 padrão)
<bookmark content="...">	$pdf->addBookmark('...')
<watermarktext content="DRAFT">	$pdf->setWatermark(Watermark::text('DRAFT'))
<watermarkimage src="...">	$pdf->setWatermark(Watermark::image('...'))

Cabeçalhos e Rodapés 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 (depois):

$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 WriteHTML

mPDF (antes):

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

TCPDF-Next (depois):

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

Marcas d'Água

mPDF (antes):

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

TCPDF-Next (depois):

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

Mapeamento de Configuração

Config mPDF	Equivalente TCPDF-Next
mode => 'utf-8'	Sempre UTF-8 (sem configuração necessária)
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	Sempre habilitado (UAX #9)
pdfaAuto	setPdfALevel(PdfALevel::PDF_A_4)

Métodos de Saída

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 (depois):

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

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

Redução de Dependências

Migrar do mPDF simplifica dramaticamente sua árvore de dependências:

Removidos (mPDF + transitivas):

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

Adicionado:

• yeee-fang/tcpdf-next (zero dependências de runtime)

Comparação de Performance

Métrica	mPDF	TCPDF-Next	Melhoria
PDF simples de 1 página	45,3 ms	8,2 ms	5,5x mais rápido
Documento de 100 páginas	3.210 ms	845 ms	3,8x mais rápido
Pico de memória (1 página)	18,4 MB	4,2 MB	4,4x menos
Pico de memória (100 páginas)	198,2 MB	28,6 MB	6,9x menos
Tamanho do arquivo de saída (1 página)	24,3 KB	12,4 KB	2,0x menor

Veja Benchmarks de Performance para metodologia completa e casos de teste.

Leitura Adicional

• Tabela de Mapeamento de API -- Mapeamento abrangente de métodos
• Benchmarks -- Comparação completa de performance com mPDF
• Referência da API -- Documentação completa da API do TCPDF-Next
• FAQ -- Perguntas frequentes sobre migração