Guía para desarrolladores sobre la compatibilidad con TCPDF

De un vistazo

El adaptador de compatibilidad es una capa de migración. Debe hacer visible el comportamiento heredado, no ocultarlo. Usarlo para mantener una aplicación en funcionamiento mientras se migran las rutas de alto valor a las API nativas de NextPDF.

Usar esta guía al mantener código heredado con forma de TCPDF, añadir cobertura del adaptador o planificar una migración por etapas a las API nativas de NextPDF.

Límite arquitectónico

Capa	Propietario	Responsabilidad	No incluir aquí
Aplicación heredada	Aplicación	Mantener operativas las llamadas con forma de TCPDF durante la migración.	Nuevas funciones de PDF que deben usar las API nativas de NextPDF.
Shell del adaptador	nextpdf/compat-legacy	Exponer la clase con forma de TCPDF y el estado de compatibilidad compartido.	Familias de métodos extensas o lógica de conversión.
Traits de concern	nextpdf/compat-legacy	Agrupar las familias de métodos heredados: texto, fuentes, imágenes, seguridad, formularios y páginas.	Política de salida entre familias.
Clases puente	nextpdf/compat-legacy	Convertir argumentos, destinos, colores, unidades y formatos heredados.	Comportamiento específico del negocio.
Motor central	nextpdf/nextpdf	Producir el documento nativo.	Garantías de compatibilidad con código heredado.

Ciclo de vida en tiempo de ejecución

Etapa	Comportamiento	Acción del desarrollador
Arranque	El arranque heredado opcional expone los nombres de compatibilidad.	Usarlo solo donde el código heredado espere símbolos de TCPDF.
Construcción	Los argumentos del constructor heredado se adaptan a la configuración del documento central.	Mantener estables las entradas del constructor durante la migración.
Llamada a método	Los métodos admitidos se asignan al comportamiento de NextPDF a través de concerns y puentes.	Comprobar la cobertura de métodos antes de suponer que hay paridad.
Función no admitida	El comportamiento no admitido lanza excepciones de compatibilidad explícitas.	Sustituir la llamada o aislarla detrás del código de la aplicación.
Salida	El puente de salida asigna el comportamiento de los destinos heredados a la salida de NextPDF.	Validar los nombres de archivo y las raíces de almacenamiento.

Inventario de migración

Empezar por recopilar cada llamada a un método de TCPDF en la aplicación. Clasificar cada llamada antes de cambiar el comportamiento.

Clasificación	Significado	Acción
Método del adaptador admitido	El método está documentado como admitido y tiene pruebas.	Mantenerlo temporalmente y migrarlo al modificar esa área.
Método del adaptador parcial	El método existe, pero el comportamiento no coincide del todo con el de TCPDF heredado.	Añadir pruebas con fixtures y validar la salida manualmente.
Método explícitamente no admitido	El adaptador lanza una excepción de compatibilidad.	Sustituirlo por NextPDF nativo o eliminar la función.
Envoltorio específico del negocio	La aplicación ya envuelve las llamadas de TCPDF.	Migrar primero las partes internas del envoltorio.
Llamada sensible al cumplimiento	Flujo de firma, cifrado, etiquetado, PDF/A, accesibilidad o factura.	Migrar a las API nativas de NextPDF con una verificación dedicada.

Patrón de contribución al adaptador

Añadir la compatibilidad en la familia de métodos más pequeña que sea responsable del comportamiento.

Tipo de cambio	Dónde implementarlo	Prueba requerida
Método de salida de texto	Concerns\AdaptsTextOutput o concern de fuentes.	Fixture heredado y aserción de la salida nativa.
Método de página o margen	Concern de página, posicionamiento o margen.	Prueba de conversión de coordenadas y de estado de página.
Método de imagen o dibujo	Concern de imagen, dibujo, color o degradado.	Validación de entrada y prueba de salida visual/estructural.
Destino de salida	OutputBridge.	Prueba de asignación de destinos y de rutas no seguras.
Función no admitida	Fábrica de excepciones o tabla de cobertura de métodos.	Prueba del tipo de excepción y del mensaje.

No añadir un método grande directamente al shell del adaptador cuando la familia pertenezca a un trait de concern.

Patrón de migración nativa

Usar el adaptador para estabilizar y luego mover los flujos de trabajo estables a las API nativas.

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

Tratar la migración como una secuencia de pequeños movimientos de comportamiento. Una página todavía puede usar el adaptador mientras una sección de alto riesgo se mueve a las API nativas.

Puntos de extensión

Punto de extensión	Usarlo para	Restricción
AdaptationConfig	Controlar el comportamiento del adaptador durante la migración.	Mantén los valores predeterminados revisados y explícitos.
Traits de concern	Agrupar familias de métodos como texto, formularios, imágenes o seguridad.	Añadir los métodos al concern apropiado, no al shell del adaptador.
Clases puente	Convertir las formas de los argumentos heredados en valores centrales.	Mantener el comportamiento del puente cubierto por las pruebas de migración.
CompatAdapterInterface	Abstracción a nivel del adaptador para el tooling.	No usarlo como sustituto de los contratos centrales nativos en código nuevo.
Tabla de cobertura de métodos	Registro de compatibilidad orientado a desarrolladores.	Actualizarla cuando cambie el estado de compatibilidad.

Flujo de trabajo de migración

1. Instalar el adaptador y ejecutar el conjunto de pruebas heredado sin cambios.
2. Abrir la cobertura de métodos y clasificar cada método llamado.
3. Sustituir primero los métodos no admitidos.
4. Mover las rutas de alto volumen o sensibles al cumplimiento a las API centrales nativas.
5. Añadir cobertura con fixtures para cada familia de métodos migrada.
6. Eliminar los alias de arranque una vez que ningún punto de entrada de la aplicación dependa de ellos.

Gestión de fallos

Fallo	Dónde debe gestionarse	Respuesta recomendada
Método no admitido	Excepción del adaptador.	Sustituir la llamada o aislarla detrás de un adaptador de la aplicación.
Paridad parcial del diseño	Pruebas de migración y revisión visual.	Documentar la diferencia aceptada antes del lanzamiento.
Destino de salida no seguro	OutputBridge y la política de almacenamiento de la aplicación.	Rechazar las rutas no seguras y preferir las API de salida nativas.
Discrepancia de funciones de seguridad	Plan de migración nativa.	No publicar comportamiento solo de compatibilidad para salidas reguladas.
Colisión de alias de arranque	Arranque de la aplicación.	Eliminar los alias globales o acotarlos a los puntos de entrada heredados.

Valores predeterminados seguros

Concern	Valor predeterminado	Cuándo anularlo
Métodos no admitidos	Lanzar una excepción explícita.	No debilitarlo en producción.
Valores predeterminados heredados	Centralizados en LegacyDefaults.	Anularlos solo para comportamiento de migración conocido.
Asignación de salida	Pasa por OutputBridge.	Usar las API de salida nativas después de la migración.
Fuente de la cobertura	Página de cobertura de métodos y pruebas.	Volver a ejecutar las comprobaciones de cobertura después de cada actualización del adaptador.
Modo estricto	Mantenerlo habilitado durante las auditorías de migración.	Desactivarlo solo durante una ventana de compatibilidad con código heredado documentada.

Lista de comprobación de pruebas

• Mantener un fixture heredado para cada familia de métodos migrada.
• Añadir una prueba nativa de NextPDF antes de sustituir un método heredado.
• Verificar que los métodos no admitidos lanzan la excepción documentada.
• Comparar la estructura de la salida cuando la igualdad exacta byte a byte no sea un objetivo de migración realista.
• Ejecutar las comprobaciones de cobertura de métodos después de añadir o cambiar métodos del adaptador.
• Añadir pruebas de ruta de almacenamiento para cada destino de salida usado por el código heredado.