Migrar do DomPDF
Este guia ajuda você a migrar do DomPDF (dompdf/dompdf) para o TCPDF-Next. As duas bibliotecas têm filosofias de design fundamentalmente diferentes -- o DomPDF é um renderizador de HTML/CSS para PDF, enquanto o TCPDF-Next é uma biblioteca PDF-nativa com uma poderosa engine de renderização HTML.
Abordagem DomPDF vs Abordagem TCPDF-Next
O DomPDF trata a geração de PDF como renderização HTML. Você escreve HTML e CSS, e o DomPDF converte em um PDF. Isso é conveniente, mas limita você ao que o CSS pode expressar, sem acesso a recursos nativos do PDF como assinaturas digitais, criptografia ou conformidade PDF/A.
O TCPDF-Next oferece duas abordagens:
| Abordagem | Descrição | Melhor Para |
|---|---|---|
| API Core | Construção direta de PDF via métodos PHP | Layouts precisos, formulários, gráficos, assinaturas |
| Artisan HTML Renderer | Renderizador HTML/CSS baseado em DOM (HtmlRenderer) | Conteúdo pesado em HTML, migração do DomPDF |
Para a maioria das migrações do DomPDF, use o Artisan HTML Renderer -- ele aceita seus templates HTML existentes com alterações mínimas.
Mapeamento de API
| DomPDF | TCPDF-Next | Notas |
|---|---|---|
new Dompdf($options) | PdfDocument::create()->build() | Builder fluente |
$dompdf->loadHtml($html) | $renderer->writeHtml($html) | O mesmo HTML funciona |
$dompdf->loadHtmlFile($url) | $renderer->writeHtmlFile($path) | Apenas arquivos locais por padrão |
$dompdf->setPaper('A4', 'portrait') | ->setPageFormat(PageFormat::A4) | Baseado em enum |
$dompdf->render() | Automático no save() / toString() | Sem passo explícito de render |
$dompdf->output() | $pdf->toString() | Retorna string binária |
$dompdf->stream('file.pdf') | Helpers de resposta do framework | Veja exemplos abaixo |
$options->set('defaultFont', ...) | $renderer->setDefaultFont(...) | |
$options->set('isRemoteEnabled', true) | ResourcePolicy::allowDomain(...) | Lista de permissão explícita |
$options->set('chroot', $dir) | ResourcePolicy::allowLocalDirectory(...) | Controle mais granular |
Exemplo Básico de Migração
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 (depois):
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');Comparação de Suporte CSS
| Recurso CSS | DomPDF | TCPDF-Next |
|---|---|---|
| Box model (margin, padding, border) | Sim | Sim |
| Floats | Parcial | Parcial |
| Flexbox | Não | Não |
| Grid | Não | Não |
position: absolute/relative | Parcial | Sim |
@font-face | Sim | Sim |
page-break-before/after | Sim | Sim |
background-image | Parcial | Sim |
border-radius | Não | Sim |
opacity | Sim | Sim |
Variáveis CSS (--custom) | Não | Não |
| Media queries | Não | Apenas @media print |
Layout table | Sim | Sim (melhorado) |
TIP
O renderizador HTML do TCPDF-Next suporta a maioria das propriedades CSS 2.1 e propriedades CSS 3 selecionadas. Flexbox e Grid não são suportados -- use tabelas para layouts complexos. Se encontrar diferenças de renderização CSS, consulte a documentação do HTML Renderer.
Quando Usar Core vs Artisan
| Cenário | Abordagem Recomendada |
|---|---|
| Migrar templates HTML existentes | Artisan HTML Renderer |
| Layouts pixel-perfect (faturas, certificados) | API Core |
| Assinaturas digitais necessárias | API Core (assinatura funciona com ambos, mas Core dá mais controle) |
| Conformidade PDF/A | Ambos (ambos suportam PDF/A-4) |
| Códigos de barras / QR codes | API Core (renderização vetorial nativa) |
| Formulários com campos preenchíveis | API Core |
| Relatórios simples a partir de HTML | Artisan HTML Renderer |
Comparação de Performance
| Métrica | DomPDF | TCPDF-Next | Melhoria |
|---|---|---|---|
| PDF simples de 1 página | 62,1 ms | 8,2 ms | 7,6x mais rápido |
| Relatório de 20 páginas | 891 ms | 187 ms | 4,8x mais rápido |
| Pico de memória (1 página) | 22,1 MB | 4,2 MB | 5,3x menos |
| Pico de memória (20 páginas) | 89,7 MB | 12,4 MB | 7,2x menos |
| Tamanho do arquivo de saída (1 página) | 31,8 KB | 12,4 KB | 2,6x menor |
Veja Benchmarks de Performance para metodologia detalhada e casos de teste adicionais.
Novos Recursos Após a Migração
Recursos disponíveis no TCPDF-Next que o DomPDF não suporta:
- Assinaturas digitais -- PAdES B-B até B-LTA com suporte a módulo de segurança de hardware.
- Criptografia AES-256 -- Proteção de documento baseada em senha e certificado.
- PDF/A-4 -- Conformidade total de arquivamento (ISO 19005-4).
- PDF com tags / PDF/UA -- Acessibilidade para leitores de tela.
- Códigos de barras nativos -- QR, Data Matrix, Code 128, EAN e mais como gráficos vetoriais.
- Campos de formulário -- Campos de texto preenchíveis, checkboxes, dropdowns.
- Cross-reference streams -- Tamanhos de arquivo menores com estrutura PDF moderna.
Leitura Adicional
- Tabela de Mapeamento de API -- Mapeamento detalhado de métodos
- Benchmarks -- Comparação completa de performance
- Visão Geral de Segurança -- Melhorias de segurança em relação ao DomPDF
- Referência da API -- Documentação completa da API do TCPDF-Next