Migrar do TCPDF

Este guia orienta você na migração de um projeto existente do TCPDF legado (tecnickcom/tcpdf) para o TCPDF-Next. O TCPDF-Next é uma reescrita completa e não é um substituto drop-in, mas o processo de migração é sistemático e bem definido.

Diferenças Principais

Recurso	TCPDF (Legado)	TCPDF-Next
Versão PHP	5.3+	8.5+
Versão PDF	PDF 1.7	PDF 2.0
Arquitetura	Classe monolítica única (~27.000 linhas)	17 namespaces modulares, 142 classes
Estilo da API	Procedural, métodos PascalCase	Builder fluente, métodos camelCase
Segurança de tipos	Sem tipos	`declare(strict_types=1)`, enums, readonly
Análise estática	Nenhuma	PHPStan Level 10, zero erros
Criptografia	RC4, AES-128, AES-256	Apenas AES-256 (PDF 2.0 Revision 6)
Assinaturas	PKCS#7 básico	PAdES B-B até B-LTA
PDF/A	PDF/A-1b (parcial)	PDF/A-4 (ISO 19005-4 completo)
Referências cruzadas	Tabelas xref legadas	Cross-reference streams
Manipulação de fontes	Formato binário proprietário	TTF/OTF padrão, subsetting automático
Parsing HTML	Baseado em regex (limitado)	Engine baseada em DOM (suporte CSS melhorado)
Dependências	Zero	Zero

Mapeamento de API: Método Antigo para Método Novo

A mudança mais visível é a superfície da API. O TCPDF-Next usa camelCase, parâmetros nomeados, value objects e builders fluentes:

TCPDF Legado	TCPDF-Next	Notas
`new TCPDF()`	`Document::create()`	Builder fluente, parâmetros nomeados
`$pdf->Cell()`	`$pdf->cell()`	camelCase
`$pdf->MultiCell()`	`$pdf->multiCell()`	camelCase
`$pdf->SetFont()`	`$pdf->setFont()`	camelCase
`$pdf->SetDrawColor()`	`$pdf->setDrawColor()`	camelCase
`$pdf->Output('file.pdf', 'F')`	`$pdf->save('file.pdf')`	Método explícito
`$pdf->Output('file.pdf', 'I')`	`$pdf->output('file.pdf', OutputDestination::Inline)`	Baseado em enum

Criação do Documento

php

$pdf = new TCPDF('P', 'mm', 'A4', true, 'UTF-8', false); 
$pdf->SetCreator('My App'); 
$pdf->SetAuthor('John Doe'); 
$pdf->SetTitle('Invoice #12345'); 
$pdf->SetKeywords('invoice, payment, monthly'); 
$pdf->setPrintHeader(false); 
$pdf->setPrintFooter(false); 
$pdf->SetMargins(15, 15, 15); 
$pdf->SetAutoPageBreak(true, 15); 
$pdf->AddPage(); 
use YeeeFang\TcpdfNext\Document\PdfDocument; 
use YeeeFang\TcpdfNext\Document\PageFormat; 
use YeeeFang\TcpdfNext\Document\Orientation; 
use YeeeFang\TcpdfNext\Document\Margins; 
$pdf = PdfDocument::create() 
    ->setCreator('My App') 
    ->setAuthor('John Doe') 
    ->setTitle('Invoice #12345') 
    ->setKeywords(['invoice', 'payment', 'monthly']) 
    ->setPageFormat(PageFormat::A4) 
    ->setOrientation(Orientation::PORTRAIT) 
    ->setMargins(Margins::uniform(15)) 
    ->setAutoPageBreak(true, bottomMargin: 15) 
    ->build(); 
$page = $pdf->addPage();

Mudanças de Configuração: Constantes para Enums

O TCPDF legado usava constantes inteiras e strings mágicas. O TCPDF-Next usa enums do PHP 8.1+:

php

// TCPDF: Magic integers for encryption mode
$pdf->SetProtection(['print', 'copy'], 'user', 'owner', 3); 

// TCPDF-Next: Type-safe enums
$pdf->setEncryption() 
    ->setAlgorithm(EncryptionAlgorithm::AES256) 
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY | Permissions::COPY) 
    ->setUserPassword('user') 
    ->setOwnerPassword('owner') 
    ->apply();

Manipulação de Cores: Arrays para Value Objects Color

php

// TCPDF: Bare integer arrays
$pdf->SetDrawColor(255, 0, 0); 
$pdf->SetFillColor(0, 128, 255); 

// TCPDF-Next: Color value objects
use YeeeFang\TcpdfNext\Color\Color; 
$canvas->setStrokeColor(Color::rgb(255, 0, 0)); 
$canvas->setFillColor(Color::rgb(0, 128, 255)); 
$canvas->setFillColor(Color::hex('#0080FF')); 
$canvas->setFillColor(Color::cmyk(100, 50, 0, 0));

Tamanho de Página: Strings para Value Objects PageSize

php

// TCPDF: Magic strings
$pdf = new TCPDF('P', 'mm', 'A4'); 
$pdf->AddPage('L', 'LETTER'); 

// TCPDF-Next: Type-safe enums and value objects
use YeeeFang\TcpdfNext\Document\PageFormat; 
use YeeeFang\TcpdfNext\Document\Orientation; 
$pdf = PdfDocument::create() 
    ->setPageFormat(PageFormat::A4) 
    ->build(); 
$page = $pdf->addPage(PageFormat::LETTER, Orientation::LANDSCAPE); 
$custom = $pdf->addPage(PageFormat::custom(100, 200)); // mm

Criptografia: RC4/AES-128 para Apenas AES-256

O TCPDF-Next remove todos os algoritmos de criptografia legados. Se sua aplicação usa criptografia RC4 ou AES-128, você deve atualizar para AES-256:

php

// TCPDF: Multiple algorithms (including insecure ones)
$pdf->SetProtection(['print'], 'user', 'owner', 0); // RC4-40 -- INSECURE
$pdf->SetProtection(['print'], 'user', 'owner', 1); // RC4-128 -- INSECURE
$pdf->SetProtection(['print'], 'user', 'owner', 2); // AES-128
$pdf->SetProtection(['print'], 'user', 'owner', 3); // AES-256

// TCPDF-Next: AES-256 only (the only secure option)
$pdf->setEncryption() 
    ->setAlgorithm(EncryptionAlgorithm::AES256) // Only option
    ->setUserPassword('user') 
    ->setOwnerPassword('owner') 
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY) 
    ->apply();

WARNING

PDFs criptografados com RC4 ou AES-128 pelo TCPDF legado devem ser re-criptografados com AES-256. A criptografia RC4 não fornece segurança significativa -- existem ferramentas para quebrá-la em segundos.

Checklist de Breaking Changes

Revise esta checklist antes de iniciar sua migração:

[ ] PHP 8.5+ necessário -- Atualize seu runtime PHP. PHP 7.x e 8.0-8.4 não são suportados.
[ ] Mudança de namespace -- Substitua referências à classe TCPDF por namespaces YeeeFang\TcpdfNext\....
[ ] Métodos camelCase -- SetFont() se torna setFont(), MultiCell() se torna multiCell(), etc.
[ ] Construtor substituído -- new TCPDF(...) se torna PdfDocument::create()->...->build().
[ ] Método Output substituído -- Output('file.pdf', 'F') se torna save('file.pdf').
[ ] Mudança de formato de fonte -- Substitua arquivos de fonte binários do TCPDF (.php + .z) por arquivos TTF/OTF originais.
[ ] Métodos Header/Footer -- Substitua herança de classe (extends TCPDF) por callbacks de evento (onPageHeader()).
[ ] Upgrade de criptografia -- RC4 e AES-128 foram removidos. Migre para AES-256.
[ ] Arrays de cor -- Substitua arrays simples [255, 0, 0] por Color::rgb(255, 0, 0).
[ ] Tamanhos de página string -- Substitua strings 'A4' por valores enum PageFormat::A4.
[ ] Formato de keywords -- Altere string separada por vírgula para array: 'a, b' se torna ['a', 'b'].
[ ] Parâmetro unit removido -- O TCPDF-Next usa milímetros por padrão (configurável por documento).
[ ] Tipos de retorno -- Muitos métodos agora retornam resultados tipados em vez de void. Use valores de retorno #[\NoDiscard].

Camada de Compatibilidade (Migração Gradual)

Para codebases grandes, o TCPDF-Next fornece uma camada de compatibilidade que mapeia a maioria das chamadas de métodos legados:

php

// Replace your import — existing code continues to work
use YeeeFang\TcpdfNext\Compat\TcpdfCompat as TCPDF;

A camada de compatibilidade cobre aproximadamente 80% da API pública do TCPDF. Métodos não suportados lançam DeprecatedMethodException com orientação sobre o equivalente moderno.

WARNING

A camada de compatibilidade é um auxílio de migração, não uma solução permanente. Ela adiciona overhead e não expõe os recursos avançados do TCPDF-Next (assinaturas PAdES, PDF/A-4, cross-reference streams). Planeje completar sua migração para a API nativa.

Mapeamento Completo da API

Para uma referência abrangente método a método cobrindo mais de 30 métodos, veja a Tabela de Mapeamento de API.

Leitura Adicional

Tabela de Mapeamento de API -- Mapeamento completo método a método
Visão Geral de Segurança -- Correções de CVE abordadas na migração
Referência da API -- Documentação completa da API do TCPDF-Next
FAQ -- Perguntas frequentes sobre migração

Migrar do TCPDF ​

Diferenças Principais ​

Mapeamento de API: Método Antigo para Método Novo ​

Criação do Documento ​

Mudanças de Configuração: Constantes para Enums ​

Manipulação de Cores: Arrays para Value Objects Color ​

Tamanho de Página: Strings para Value Objects PageSize ​

Criptografia: RC4/AES-128 para Apenas AES-256 ​

Checklist de Breaking Changes ​

Camada de Compatibilidade (Migração Gradual) ​

Mapeamento Completo da API ​

Leitura Adicional ​