Migrar desde TCPDF

Esta guía te acompaña en la migración de un proyecto existente desde TCPDF legacy (tecnickcom/tcpdf) a TCPDF-Next. TCPDF-Next es una reescritura completa y no es un reemplazo directo, pero el proceso de migración es sistemático y bien definido.

Diferencias clave

Característica	TCPDF (Legacy)	TCPDF-Next
Versión de PHP	5.3+	8.5+
Versión de PDF	PDF 1.7	PDF 2.0
Arquitectura	Clase monolítica única (~27,000 líneas)	17 namespaces modulares, 142 clases
Estilo de API	Procedural, métodos PascalCase	Builder fluent, métodos camelCase
Seguridad de tipos	Sin tipos	`declare(strict_types=1)`, enums, readonly
Análisis estático	Ninguno	PHPStan Level 10, cero errores
Cifrado	RC4, AES-128, AES-256	Solo AES-256 (PDF 2.0 Revision 6)
Firmas	PKCS#7 básico	PAdES B-B hasta B-LTA
PDF/A	PDF/A-1b (parcial)	PDF/A-4 (ISO 19005-4 completo)
Referencias cruzadas	Tablas xref legacy	Cross-reference streams
Manejo de fuentes	Formato binario propietario	TTF/OTF estándar, subsetting automático
Parseo HTML	Basado en regex (limitado)	Motor basado en DOM (soporte CSS mejorado)
Dependencias	Cero	Cero

Mapeo de API: Método antiguo a método nuevo

El cambio más visible es la superficie de API. TCPDF-Next usa camelCase, parámetros nombrados, value objects y builders fluent:

TCPDF Legacy	TCPDF-Next	Notas
`new TCPDF()`	`Document::create()`	Builder fluent, params nombrados
`$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)`	Basado en enum

Creación de 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();

Cambios de configuración: Constantes a enums

TCPDF legacy usaba constantes enteras y strings mágicos. TCPDF-Next usa enums de PHP 8.1+:

php

// TCPDF: Enteros mágicos para modo de cifrado
$pdf->SetProtection(['print', 'copy'], 'user', 'owner', 3); 

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

Manejo de colores: Arrays a value objects Color

php

// TCPDF: Arrays de enteros
$pdf->SetDrawColor(255, 0, 0); 
$pdf->SetFillColor(0, 128, 255); 

// TCPDF-Next: Value objects Color
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));

Tamaño de página: Strings a value objects PageSize

php

// TCPDF: Strings mágicos
$pdf = new TCPDF('P', 'mm', 'A4'); 
$pdf->AddPage('L', 'LETTER'); 

// TCPDF-Next: Enums y value objects type-safe
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

Cifrado: RC4/AES-128 a solo AES-256

TCPDF-Next elimina todos los algoritmos de cifrado legacy. Si tu aplicación usa cifrado RC4 o AES-128, debes actualizar a AES-256:

php

// TCPDF: Múltiples algoritmos (incluyendo inseguros)
$pdf->SetProtection(['print'], 'user', 'owner', 0); // RC4-40 -- INSEGURO
$pdf->SetProtection(['print'], 'user', 'owner', 1); // RC4-128 -- INSEGURO
$pdf->SetProtection(['print'], 'user', 'owner', 2); // AES-128
$pdf->SetProtection(['print'], 'user', 'owner', 3); // AES-256

// TCPDF-Next: Solo AES-256 (la única opción segura)
$pdf->setEncryption() 
    ->setAlgorithm(EncryptionAlgorithm::AES256) // Only option
    ->setUserPassword('user') 
    ->setOwnerPassword('owner') 
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY) 
    ->apply();

WARNING

Los PDFs cifrados con RC4 o AES-128 por TCPDF legacy deben re-cifrarse con AES-256. El cifrado RC4 no proporciona seguridad significativa -- existen herramientas que pueden romperlo en segundos.

Checklist de cambios incompatibles

Revisa esta checklist antes de iniciar tu migración:

[ ] PHP 8.5+ requerido — Actualiza tu runtime PHP. PHP 7.x y 8.0-8.4 no son soportados.
[ ] Cambio de namespace — Reemplaza las referencias a la clase TCPDF con namespaces YeeeFang\TcpdfNext\....
[ ] Métodos camelCase — SetFont() se convierte en setFont(), MultiCell() en multiCell(), etc.
[ ] Constructor reemplazado — new TCPDF(...) se convierte en PdfDocument::create()->...->build().
[ ] Método Output reemplazado — Output('file.pdf', 'F') se convierte en save('file.pdf').
[ ] Cambio de formato de fuentes — Reemplaza los archivos de fuentes binarios de TCPDF (.php + .z) con archivos TTF/OTF originales.
[ ] Métodos Header/Footer — Reemplaza la herencia de clase (extends TCPDF) con callbacks de eventos (onPageHeader()).
[ ] Actualización de cifrado — RC4 y AES-128 fueron eliminados. Migra a AES-256.
[ ] Arrays de color — Reemplaza arrays [255, 0, 0] con Color::rgb(255, 0, 0).
[ ] Tamaños de página string — Reemplaza strings 'A4' con valores enum PageFormat::A4.
[ ] Formato de keywords — Cambia string separado por comas a array: 'a, b' se convierte en ['a', 'b'].
[ ] Parámetro de unidad eliminado — TCPDF-Next usa milímetros por defecto (configurable por documento).
[ ] Tipos de retorno — Muchos métodos ahora retornan resultados tipados en lugar de void. Usa los valores de retorno #[\NoDiscard].

Capa de compatibilidad (migración gradual)

Para códigos base grandes, TCPDF-Next proporciona una capa de compatibilidad que mapea la mayoría de las llamadas a métodos legacy:

php

// Reemplaza tu import — el código existente continúa funcionando
use YeeeFang\TcpdfNext\Compat\TcpdfCompat as TCPDF;

La capa de compatibilidad cubre aproximadamente el 80% de la API pública de TCPDF. Los métodos no soportados lanzan DeprecatedMethodException con orientación sobre el equivalente moderno.

WARNING

La capa de compatibilidad es una ayuda de migración, no una solución permanente. Añade overhead y no expone las funcionalidades avanzadas de TCPDF-Next (firmas PAdES, PDF/A-4, cross-reference streams). Planifica completar tu migración a la API nativa.

Mapeo completo de API

Para una referencia completa método por método que cubre más de 30 métodos, consulta la Tabla de mapeo de API.

Lectura adicional

Tabla de mapeo de API — Mapeo completo método por método
Resumen de seguridad — CVEs corregidos en la migración
Referencia de API — Documentación completa de la API de TCPDF-Next
FAQ — Preguntas frecuentes sobre migración

Migrar desde TCPDF ​

Diferencias clave ​

Mapeo de API: Método antiguo a método nuevo ​

Creación de documento ​

Cambios de configuración: Constantes a enums ​

Manejo de colores: Arrays a value objects Color ​

Tamaño de página: Strings a value objects PageSize ​

Cifrado: RC4/AES-128 a solo AES-256 ​

Checklist de cambios incompatibles ​

Capa de compatibilidad (migración gradual) ​

Mapeo completo de API ​

Lectura adicional ​