Cobertura de métodos TCPDF en NextPDF compat-legacy

De un vistazo

nextpdf/compat-legacy es una capa de compatibilidad, no un fork de TCPDF ni una réplica con comportamiento garantizado. Expone los nombres de método públicos, el orden de los parámetros y los valores por defecto de TCPDF 6.x sobre el motor central de NextPDF. La mayoría de las llamadas se asignan directamente a una operación Document de NextPDF. Una minoría definida acepta parámetros heredados que NextPDF no tiene en cuenta o no produce ningún efecto.

Esta página resume, para consulta, la auditoría por método. La matriz de cobertura autoritativa y verificada por pruebas se encuentra en el repositorio, en docs/TCPDF_COVERAGE.md. Cuando esta página y la matriz del repositorio discrepan, prevalece la matriz del repositorio, porque está respaldada por el conjunto de pruebas.

Esta página sirve para responder una pregunta antes de migrar: para cada método de TCPDF que invoca la base de código, ¿qué hace realmente el adaptador?

Resumen de cobertura

La auditoría revisó alrededor de 120 métodos públicos de TCPDF 6.x. Cada uno se ubicó en exactamente una de cuatro categorías.

Categoría	Recuento	Qué implica
Reflejados — delegación completa	94	La llamada se asigna directamente a un método `Document` de NextPDF. El comportamiento es compatible para los parámetros documentados.
Ignorado-silencioso — parcial	15	El método se ejecuta y produce salida, pero uno o más parámetros de TCPDF no surten efecto. Es una diferencia de comportamiento documentada.
No implementados — cuerpo vacío	4	El método existe por compatibilidad de código fuente, pero no hace nada.
No aplicable	7	El método de TCPDF no tiene efecto en la salida PDF; se excluye de forma intencionada.
Métodos de deriva de la API moderna añadidos	17	Métodos de Document de NextPDF v5.1+ expuestos en el adaptador para que el código de API mixta compile. Sin equivalente en TCPDF 6.x.

Estas cifras provienen de docs/TCPDF_COVERAGE.md §Summary. La matriz se verifica mediante tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php y tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php.

Nota sobre la redacción. Este paquete no afirma ser un «reemplazo directo (drop-in)» ni «100 % compatible con TCPDF». Cubre 94 de los ~120 métodos de TCPDF revisados mediante delegación directa; los métodos restantes presentan diferencias de comportamiento documentadas que se describen más abajo. La formulación precisa es alternativa compatible con TCPDF con una superficie de compatibilidad conocida y probada.

Una nota sobre los recuentos de métodos

El adaptador se construye a partir de 25 traits de responsabilidad única (src/Compat/Tcpdf/Concerns/) que exponen 273 métodos públicos en total, además de un pequeño número de métodos de ciclo de vida y de escape en la propia clase TCPDF. Las categorías de cobertura anteriores cuentan métodos distintos de la superficie de la API de TCPDF 6.x (~120), no el recuento total de métodos públicos del adaptador. Los dos números miden cosas distintas: cobertura de la superficie de la API frente a tamaño de la implementación. Si en el README.md del paquete aparece un recuento menor de traits o de métodos, considerar docs/TCPDF_COVERAGE.md y esta página como fuentes autoritativas: el resumen del README es anterior al trait AdaptsDriftV51.

1. Métodos reflejados — delegación compatible

Noventa y cuatro métodos se asignan directamente a la instancia subyacente NextPDF\Core\Document. Los nombres PascalCase de TCPDF se asignan a nombres camelCase de NextPDF cuando el motor usa camelCase; el adaptador acepta ambas grafías por compatibilidad hacia adelante y hacia atrás.

Grupos representativos (tabla completa: docs/TCPDF_COVERAGE.md §1):

Área de TCPDF	Métodos de ejemplo	Trait del adaptador
Ciclo de vida	`Output()`, `Close()`, `getPDFData()`	`AdaptsLifecycle`
Páginas	`AddPage()`, `getNumPages()`, `deletePage()`	`AdaptsPageManagement`
Texto	`Cell()`, `MultiCell()`, `Write()`, `Text()`, `Ln()`	`AdaptsTextOutput`
Fuentes	`SetFont()`, `SetFontSize()`, `AddFont()`	`AdaptsFonts`
Colores	`SetTextColor()`, `SetDrawColor()`, `SetFillColor()`	`AdaptsColors`
Dibujo	`Line()`, `Rect()`, `Circle()`, `Polygon()`, `Arrow()`	`AdaptsDrawing`
Transformaciones	`Rotate()`, `Scale()`, `Translate()`, `Skew()`, `Mirror*()`	`AdaptsTransforms`
Navegación	`AddLink()`, `Annotation()`, `addTOC()`	`AdaptsNavigation`

Para estos métodos, el comportamiento observado es compatible con TCPDF 6.x para los parámetros documentados por NextPDF. El adaptador no garantiza una salida PDF idéntica byte a byte. El motor subyacente es una implementación independiente de PDF 2.0, por lo que los bytes generados difieren aunque el resultado visible sea equivalente. Si las pruebas validan los bytes exactos del PDF en lugar del contenido representado, es probable que esas aserciones necesiten una nueva línea base. Consultar /integrations/tcpdf-compat/migration/ para la estrategia de nueva línea base recomendada.

2. Métodos de ignorado-silencioso — diferencias de comportamiento documentadas

Estos 15 métodos se ejecutan y producen salida, pero al menos un parámetro de TCPDF se acepta por compatibilidad de código fuente y luego se ignora. Esta es la sección más importante antes de migrar, porque la llamada no falla: en silencio, hace menos que el original de TCPDF.

Método de TCPDF	Parámetros ignorados	Alternativa compatible
`Image()`	type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs	`image()` de NextPDF recibe file, x, y, width, height. Para una imagen en la que se pueda hacer clic, dibujar la imagen y luego añadir `Document::link()` sobre el mismo rectángulo. El enmascaramiento de imágenes y las imágenes alternativas no son compatibles.
`writeHTML()`	ln, fill, reseth, cell, align	`writeHtml()` de NextPDF es solo de contenido. Envolver el HTML en un bloque posicionado mediante la API moderna para controlar el diseño.
`writeHTMLCell()`	border (forma de cadena), ln, fill, reseth, autopadding	Se respetan el ancho, el alto, la posición y un borde booleano; el diseño de celdas más rico no tiene asignación.
`ImageEps()`	link, useBoundingBox, align, palign, border, fitonpage, fixoutvals	Solo posición y tamaño.
`ImageSVG()`	link, align, palign, border, fitonpage	Solo posición y tamaño.
`SetProtection()`	mode (distinto de cero), pubkeys (no vacío)	NextPDF siempre usa AES-256 para el gestor estándar. Para el cifrado basado en certificados, usar el moderno `setPublicKeyEncryption()` expuesto en el adaptador (consultar /integrations/tcpdf-compat/security-and-operations/).
`Bookmark()`	style, color, x, isNamedDest	Se respetan el título, el nivel y la posición y.
`setDestination()`	page, x	Se respetan el nombre y la posición y.
`Link()`	spaces	Seguimiento interno de espacios en blanco de TCPDF; sin equivalente en el motor.
`Annotation()`	claves de opción más allá de Subtype, spaces	Se respetan el tipo, la posición y el texto.
`SetLineStyle()`	detalle del patrón de guiones más allá del ancho	Se asignan las propiedades de línea principales.
`setAlpha()`	mapa parcial de modos de fusión	Algunos nombres de modo de fusión no tienen equivalente en el motor.
`Polycurve()`	lista completa de parámetros	Sin operación en el modo por defecto; sin equivalente en el motor.
`PieSectorXY()`	lista completa de parámetros	Asignación parcial (las líneas del centro al borde difieren).
`RoundedRectXY()`	radio por esquina	Solo radio de esquina uniforme.

La forma en que el adaptador hace aflorar estas diferencias depende del modo estricto (consultar /integrations/tcpdf-compat/configuration/). Con el modo estricto desactivado (el valor por defecto retrocompatible), estas llamadas se degradan en silencio. Con el modo estricto activado, cada llamada que ignora un parámetro lanza TcpdfNotImplementedException con la lista exacta de parámetros ignorados y una sugerencia de migración. El modo estricto es una herramienta de auditoría, no un ajuste de producción.

El diseño del modo estricto sigue el principio de que quien hace la llamada debe poder observar cuándo no se ha respetado su intención. OWASP ASVS 5.0 §16.5.3 establece que una aplicación debe fallar de forma elegante y segura, y evitar las condiciones de fallo-abierto (fail-open). La pérdida silenciosa de parámetros es una trampa para la experiencia de desarrollo más que una vulnerabilidad, pero se aplica el mismo principio de fallar de forma explícita. El resumen de cláusulas fijado está en el front-matter de la página, en citations.

3. Métodos no implementados — cuerpos vacíos

Cuatro métodos existen para que el código fuente heredado pueda compilar, pero sus cuerpos no hacen nada. Con el modo estricto activado, tres de ellos lanzan TcpdfNotImplementedException. El cuarto (Open()) es una operación nula segura y deliberada que nunca lanza, porque eliminarlo del código heredado siempre es seguro.

Método de TCPDF	Comportamiento	Reemplazo
`setSignature()`	Operación nula (no almacena nada procesable). Lanza en modo estricto.	La firma digital requiere una edición comercial de NextPDF. Usar la API de firma moderna con un objeto de valor `CertificateInfo` — consultar /integrations/tcpdf-compat/security-and-operations/.
`addEmptySignatureAppearance()`	Operación nula. Lanza en modo estricto.	La misma restricción de edición comercial que `setSignature()`.
`endPage()`	Operación nula. Lanza en modo estricto.	NextPDF gestiona el ciclo de vida de las páginas automáticamente. Eliminar la llamada.
`Open()`	Operación nula segura. Nunca lanza.	NextPDF abre el documento automáticamente. Eliminar la llamada siempre es seguro.

La firma no está disponible en el motor central a través de este adaptador. El adaptador expone un punto de entrada de firma moderno que delega en el motor; la compatibilidad básica de firma está restringida a una edición comercial. Esta documentación no afirma nada sobre los perfiles de firma de validación a largo plazo o con marca de tiempo para ninguna edición — consultar /integrations/tcpdf-compat/security-and-operations/ para la formulación exacta y conservadora.

4. Métodos no aplicables

Siete métodos de TCPDF no tienen efecto en la salida PDF y se excluyen de forma intencionada. Llamarlos es inofensivo.

Método de TCPDF	Por qué se excluye
`setDocCreationTimestamp()` / `setDocModificationTimestamp()`	El estado se conserva en el adaptador pero no se conecta a los metadatos XMP del documento. No es visible en la salida.
`setSRGBmode()`	La gestión de color de NextPDF es independiente de este indicador.
`setPDFVersion()`	NextPDF selecciona la versión de PDF a partir de su perfil de conformance/output; no hay un setter directo. El adaptador emite un aviso y continúa.
`setDocInfoUnicode()`	NextPDF siempre es Unicode; el indicador es una operación nula por diseño.
`setDefaultMonospacedFont()`	Sin equivalente en el motor; en su lugar se aplica el estilo HTML/CSS.
`setFontSubsetting()`	NextPDF siempre crea subconjuntos de las fuentes incrustadas; el indicador está, en la práctica, siempre activado.

La versión de PDF la fija el motor. La salida se escribe como PDF 2.0 (ISO 32000-2). ISO 32000-2 §7.5.2 especifica que un escritor conforme identifica la versión del documento — en la cabecera del archivo o en la entrada Version del catálogo — como 2.0. También especifica que la versión de un archivo no se rebaja a una versión anterior al guardar. Esto es coherente con el comportamiento del adaptador: llamadas como setPDFVersion('1.4') no pueden fijar como destino una versión de PDF anterior a través de este adaptador. El resumen de cláusulas fijado está en el front-matter de la página, en citations.

5. Métodos de deriva de la API moderna

Diecisiete métodos del núcleo de NextPDF v5.1+ se exponen en el adaptador (trait AdaptsDriftV51) para que el código que mezcla la API de TCPDF con la API moderna siga compilando. Estos no tienen equivalente en TCPDF 6.x. Ejemplos: getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode(). Deben tratarse como API moderna, no como parte del contrato de compatibilidad con TCPDF.

6. Orientación sobre obsolescencia y reemplazo

Si el código llama a…	Estado	Alternativa recomendada
`Error()`	Comportamiento cambiado (reforzado)	El `die()` de TCPDF se reemplaza por una `RuntimeException` lanzada. Envolver las llamadas arriesgadas en `try`/`catch`; no confiar en la terminación del proceso.
`setPDFVersion()`	No aplicable	Eliminarlo. La salida siempre es PDF 2.0.
`setUserRights()`	Obsoleto en PDF 2.0	Eliminarlo. La llamada emite un aviso `E_USER_DEPRECATED` y se ignora.
`setSignature()`	No implementado en el núcleo	Migrar a la API de firma moderna en una edición comercial.
`Image(...)` con parámetros adicionales	Ignorado-silencioso	Reducirlo a file, x, y, w, h; añadir `Document::link()` para imágenes en las que se pueda hacer clic.
`endPage()` / `Open()`	No implementado / operación nula	Eliminarlo.

7. Pasos para una migración segura

Instalar el paquete y ejecutar el conjunto de pruebas existente contra el adaptador sin cambios de código — consultar /integrations/tcpdf-compat/install/ y /integrations/tcpdf-compat/quickstart/.
Activar el modo estricto en una ejecución de auditoría dedicada (no en producción): $pdf->setStrictMode(true);. Recopilar cada TcpdfNotImplementedException. Cada una nombra los parámetros ignorados exactos y una sugerencia de migración.
Para cada sitio de llamada, elegir: descartar el parámetro ignorado, o migrar esa llamada a la API moderna mediante $pdf->getDocument().
Restablecer la línea base de cualquier prueba que valide los bytes exactos del PDF; validar en su lugar el contenido representado o propiedades estructurales.
Desactivar el modo estricto y desplegar la ruta de código auditada. Mantener un trabajo periódico de CI en modo estricto para detectar regresiones a medida que se refactoriza.

Procedimiento completo con código: /integrations/tcpdf-compat/migration/.

Véase también

docs/TCPDF_COVERAGE.md — matriz de cobertura autoritativa y verificada por pruebas (en el repositorio)
/integrations/tcpdf-compat/migration/ — estrategia integral de migración de TCPDF a NextPDF
/integrations/tcpdf-compat/configuration/ — modo estricto y configuración del adaptador
/integrations/tcpdf-compat/security-and-operations/ — postura de cifrado y firma
/integrations/tcpdf-compat/integration/ — integración del adaptador en una aplicación
/integrations/tcpdf-compat/boot-and-discovery/ — registro de alias de clase y exposición de la fachada