Migrar desde bibliotecas heredadas: TCPDF, FPDF y similares

SpecSpec: ISO 32000-2ISO 32000-2SpecSpec: ISO 19005-4ISO 19005-4SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1

De un vistazo

Si los PDF se generan con TCPDF, FPDF, mPDF o dompdf, el código probablemente sigue funcionando. Por eso justamente es fácil que el problema pase desapercibido. La biblioteca se ejecuta, el archivo se abre, y la carencia solo aparece el día en que alguien pide un documento firmado, archivable o accesible y la respuesta es «desde aquí no podemos».

Esta página cuenta la historia de la migración: cuáles son esos muros, por qué son estructurales y no accidentales, y cómo NextPDF ofrece una salida por etapas para dejarlos atrás, incluida una superficie de compatibilidad con TCPDF que es una ayuda para migrar, no la promesa de un reemplazo directo byte a byte.

Por qué esto importa

Una biblioteca de PDF no es una llamada de representación que se hace una vez. Es una dependencia que los documentos heredan mientras existan. Cuando esa dependencia deja de avanzar, los documentos dejan de poder hacer cosas nuevas, y uno se entera en el peor momento posible: cuando un cliente, un auditor o un regulador pone el listón.

Los muros tienen este aspecto. El formato evolucionó: PDF 2.0 es la edición actual de la norma (SpecSpec: ISO 32000-2ISO 32000-2), y un escritor atascado en la estructura 1.x va por detrás del formato que el resto de la cadena de herramientas da por supuesto. La firma es escasa o añadida a posteriori, muy por debajo de los perfiles de base PAdES que hacen que una firma se sostenga (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4). La salida de archivo a la familia PDF/A, y la estructura etiquetada para la accesibilidad, están ausentes o son frágiles. Y la propia API no tiene tipos —orientaciones como cadenas, booleanos posicionales, valores por defecto que se descubren por accidente—, de modo que ni el compilador ni quien revisa el código pueden ayudar.

Ninguno de estos es un fallo que se pueda parchear sobre la marcha. Son la forma de una herramienta concebida para una década anterior, y varias de esas herramientas ya no avanzan activamente hacia las normas que los documentos ahora deben cumplir.

La versión corta

• Las bibliotecas heredadas de PHP para PDF en su mayoría siguen ejecutándose. El problema es lo que suelen no poder producir con plena conformidad moderna: PDF 2.0, firmas conformes con la base, PDF/A validado, accesibilidad etiquetada; el soporte en las bibliotecas mencionadas es limitado o inexistente.
• NextPDF es un motor PHP 8.4 que escribe PDF 2.0 por defecto, con tipos estrictos, perfiles de archivo y firma PAdES como salidas de primer nivel.
• No hay que reescribirlo todo el primer día. La superficie de compatibilidad con TCPDF permite que las llamadas conocidas sigan funcionando mientras se traslada la lógica documental que importa.
• Esa superficie es compatible con TCPDF, no idéntica byte a byte. Es un puente que cubre la migración, con diferencias de comportamiento documentadas, no la afirmación de que cada script se ejecute sin cambios.
• La prueba honesta es si las nuevas capacidades justifican el cambio. Para algunas cargas de trabajo no lo hacen, y lo decimos con claridad.

Cómo lo aborda NextPDF

El enfoque consiste en hacer de la migración una secuencia, no un salto. Se siguen produciendo documentos durante todo el camino, y se cambian las restricciones antiguas de una en una, en lugar de apostar una versión a una reescritura de golpe.

1. InventarioCatalogar lo que los documentos realmente necesitan emitir —firmas, perfiles de archivo, estructura etiquetada, fuentes—, no solo qué llamadas se hacen hoy.
2. PuenteAdoptar la superficie de compatibilidad con TCPDF para que los puntos de llamada existentes sigan produciendo archivos mientras el motor que está debajo pasa a ser NextPDF.
3. PortarTrasladar la lógica documental que importa a la API nativa con tipos, donde la intención es explícita y el compilador la verifica.
4. MejorarActivar las salidas que muchas bibliotecas heredadas no alcanzan con plena conformidad moderna: estructura PDF 2.0, PDF/A validado, firmas PAdES, accesibilidad etiquetada.
5. VerificarConfirmar el resultado contra un validador real, para que «archivable» o «firmado» signifique que una herramienta lo confirma, no solo que el archivo se abrió.

A staged migration off a legacy PDF library: start on the compatibility surface so existing calls keep working, then move document logic onto the typed native API, then turn on the standards-grade outputs (PDF 2.0, PDF/A, PAdES, accessibility) that many legacy libraries cannot produce with full modern conformance.

PDF 2.0 es la base, no un indicador de función. NextPDF escribe la edición actual del formato por defecto (SpecSpec: ISO 32000-2ISO 32000-2), y puede serializar estructuras más antiguas cuando un perfil las pide. Una biblioteca congelada en la estructura 1.x no puede acompañarte aquí; no es un ajuste que le falte, es una época que precede.

El archivo y la accesibilidad son propiedades del escritor. Producir un archivo que un validador acepte como PDF/A es algo que el motor tiene que hacer mientras escribe; no se puede grapar después (SpecSpec: ISO 19005-4ISO 19005-4). Lo mismo ocurre con la estructura etiquetada que hace accesible un PDF. NextPDF las construye durante la generación, que es precisamente el paso que muchas herramientas heredadas no pueden dar, o dan solo en parte, por debajo de lo que un validador acepta.

La firma supera el listón de la base. Las firmas electrónicas avanzadas en un PDF siguen los perfiles PAdES (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4), donde el resumen cubre un rango de bytes declarado y la firma porta los metadatos que un validador comprueba. Un auxiliar de firma añadido a posteriori rara vez alcanza ese listón. NextPDF lo trata como una salida de primer nivel, no como una ocurrencia tardía.

La superficie de compatibilidad es el puente, dicho con honestidad. La capa de compatibilidad con TCPDF existe para que los puntos de llamada existentes sigan produciendo documentos mientras se migran las partes que importan. Sigue el mismo modelo que cada guía de migración de NextPDF: compatible con la biblioteca de origen, no idéntica byte a byte, con las diferencias de comportamiento escritas. Esa honestidad es lo importante: una afirmación silenciosa de «reemplazo directo al 99 %» es justo el tipo de conjetura que este motor está construido para rechazar.

Human-factors note:Human-factors note

La razón para migrar rara vez es el código que se tiene hoy; es el documento que se pedirá mañana. La mantenibilidad es una propiedad de calidad con nombre propio: con qué facilidad un sistema puede analizarse y modificarse a medida que cambian las necesidades (SpecSpec: ISO/IEC 25010, §3.6ISO/IEC 25010 §3.6). Una dependencia que ha dejado de avanzar la erosiona en silencio, y el coste solo se siente cuando llega un requisito nuevo y la respuesta tiene que ser «desde aquí no». Una migración por etapas paga ese coste según el calendario propio, mientras los documentos siguen fluyendo, en lugar de todo a la vez bajo presión de plazos.

Ejemplo práctico

La forma de una migración es pequeña en el punto de llamada. El código antiguo sigue produciendo un archivo a través de la superficie de compatibilidad; el código nuevo declara la intención mediante la API nativa con tipos y pide una salida que la biblioteca heredada no alcanza, o alcanza solo con una conformidad limitada.

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use NextPDF\Contracts\Orientation;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

// 1) The bridge: a familiar TCPDF-shaped call keeps producing a file
//    while the engine underneath is already NextPDF. Behaviour is
//    compatible, not byte-identical — differences are documented.
$legacy = new TCPDF();
$legacy->AddPage();
$legacy->SetFont('helvetica', 'B', 16);
$legacy->Cell(0, 12, 'Migrated invoice', ln: 1);
$bridgedBytes = $legacy->Output('', 'S');

// 2) The destination: the same document expressed natively, where intent
//    is typed and the engine can emit what many legacy tools cannot.
$document = Document::createStandalone();
$document->setTitle('Migrated invoice');
$document->addPage(PageSize::a4(), Orientation::Portrait);
$document->setFont('helvetica', 'B', 16);
$document->cell(0, 12, 'Migrated invoice', newLine: true);

// Bytes only, no HTTP headers, no file side effect — stated, not inferred.
$nativeBytes = $document->output(dest: OutputDestination::String);

El primer bloque es el punto de apoyo: nada en la aplicación tiene que cambiar para que los documentos sigan fluyendo. El segundo es el destino: una llamada con tipos donde «vertical», «salida como cadena» y la fuente son explícitos, y donde el archivo, la firma y la accesibilidad pasan a ser salidas que se pueden activar en lugar de muros con los que tropezar.

Concepto erróneo habitual

La esperanza frecuente es «tiene que haber un indicador que haga que mi biblioteca antigua produzca PDF 2.0 y firmas». No lo hay. No son opciones que una biblioteca madura olvidó exponer; son capacidades en torno a las cuales su arquitectura nunca se construyó. No se puede llegar mediante configuración a una edición del formato ni a un perfil de firma que un escritor no implementa.

El concepto erróneo simétrico es creer que NextPDF es un reemplazo directo al 100 % de TCPDF, así que migrar sale gratis. No lo es, y no fingiremos lo contrario. La superficie de compatibilidad cubre una parte real y documentada de la API para llevarte a través del cambio; algunas llamadas se comportan de forma distinta y unas pocas quedan fuera de alcance. Trátala como un puente con un mapa publicado, no como la garantía de que cada script heredado se ejecute sin tocar.

Límites y fronteras

TCPDF-compatibility surface as a migration aid — edition availability

Edition	Availability
Core	○ La superficie de compatibilidad es compatible con TCPDF, no idéntica byte a byte. Cubre un subconjunto documentado de la API para mantener los puntos de llamada existentes produciendo archivos durante la migración. Es un puente, no un reemplazo directo: algunos comportamientos difieren y algunas llamadas no se admiten, todo ello listado en las páginas de cobertura de métodos y de migración. El destino es la API nativa con tipos, donde reside la salida con nivel de norma.
Pro	●Available
Enterprise	●Available

Migrar es un medio, no una virtud. Si los documentos son sencillos, la biblioteca sigue manteniéndose y nunca se necesitará PDF 2.0, firma, PDF/A ni accesibilidad, la respuesta honesta puede ser quedarse donde se está: el coste de cambiar es real, y una migración que no se necesita es una migración que no se debe hacer. La página sobre cuándo no usar NextPDF traza esa línea sin titubear.

Esta página describe el camino de la migración y los objetivos del motor. La cobertura exacta de la API, las diferencias de comportamiento y el procedimiento paso a paso residen en la documentación de compatibilidad, que es la autoridad sobre lo que hace cada llamada. Nada de lo aquí dicho promete que un script heredado arbitrario se ejecute sin cambios.

Documentos relacionados

• Qué cambió en PDF 2.0: la edición del formato que muchas bibliotecas heredadas no pueden emitir, y por qué importa.
• La superficie de compatibilidad con TCPDF: la guía con autoridad sobre lo que cubre el puente y dónde difiere.
• Cuándo no usar NextPDF: el límite honesto, para que una migración que no se necesita sea una que se pueda omitir.
• Un motor, todos los marcos de trabajo: dónde se conecta a la pila que ya se ejecuta el motor al que se migra.

Glosario

• PDF 2.0: la edición actual de la norma del Formato de Documento Portátil (ISO 32000-2). Desarrollado en su primer uso; el formato que NextPDF escribe por defecto.
• PDF/A: la familia de conformidad de archivo (la serie ISO 19005) que define qué hace que un PDF sea seguro de preservar a largo plazo. Una propiedad que el escritor debe producir, no una que quien lo llama pueda añadir después.
• PAdES: PDF Advanced Electronic Signatures, la familia de perfiles ETSI (EN 319 142) para incrustar firmas con nivel de norma en un PDF. Desarrollado en su primer uso; tratado en profundidad en las páginas de firma.
• Superficie de compatibilidad: una capa de API con la forma de una biblioteca de origen (aquí, TCPDF) que permite que los puntos de llamada existentes sigan funcionando durante la migración. Compatible con el original, no idéntica byte a byte: un puente, no un reemplazo directo.
• Reemplazo directo: un sustituto que ejecuta el código existente sin cambios. La superficie de compatibilidad con TCPDF deliberadamente no se describe así; es una ayuda de migración documentada con diferencias de comportamiento conocidas.