Referencia de la API de compatibilidad con TCPDF

De un vistazo

El paquete nextpdf/compat-legacy expone una clase principal, NextPDF\Compat\Tcpdf\TCPDF, que refleja la API pública de TCPDF 6.x y renderiza mediante el motor moderno de NextPDF. También proporciona un conjunto reducido de componentes de soporte: un LegacyBootstrap para los alias de clases globales, la superficie de configuración AdaptationConfig/LegacyDefaults, clases puente internas (salida, constructor, color, unidad, formato de página) y excepciones de compatibilidad. Es una ayuda para la migración, no una dependencia permanente. El estado completo de los métodos heredados se encuentra en la tabla de cobertura de métodos. Esta página documenta las superficies de las que el código de la aplicación debería depender de forma intencionada.

Punto de partida: para empezar con este paquete, basta con construir NextPDF\Compat\Tcpdf\TCPDF, realizar las llamadas TCPDF habituales (AddPage(), SetFont(), Cell()) y terminar con Output($name, $dest). Esa única clase es el punto de entrada para casi todo lo que aparece a continuación. Ver Tareas comunes para encontrar puntos de partida ejecutables.

Tareas comunes

Estas son las tareas prácticas más habituales con este paquete. Cada bloque se ha verificado contra el código fuente del adaptador y se puede ejecutar tal cual.

Generar un PDF con llamadas TCPDF conocidas y capturarlo como una cadena (para una cola, una respuesta HTTP o almacenamiento):

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetTitle('Invoice 1234');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$bytes = $pdf->Output('invoice.pdf', 'S');

Qué hace: construye un documento PDF 2.0 mediante el adaptador con interfaz de TCPDF y devuelve los bytes sin procesar (%PDF...) porque el destino 'S' se enruta a través de OutputBridge hacia Document::getPdfData() en lugar de imprimirlos; esto resulta seguro dentro de un worker o un controlador.

Ejecutar código new \TCPDF(...) existente sin editar el código fuente registrando los alias globales una vez en el arranque:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

$pdf = new \TCPDF('P', 'mm', 'A4'); // resolves to the adapter
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/legacy.pdf', 'F');

Qué hace: enableAliases() registra de forma idempotente \TCPDF (y los ayudantes \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES) solo cuando esos nombres aún no están definidos, de modo que el código heredado se ejecuta sin cambios sobre el adaptador.

Auditar una migración sacando a la luz cada parámetro de TCPDF que se descarta de forma silenciosa:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter
}

Qué hace: con setStrictMode(true), una llamada que no puede reproducir el comportamiento de TCPDF lanza TcpdfNotImplementedException e indica por nombre los parámetros ignorados. Esto convierte la degradación silenciosa en una lista de trabajo de migración (usar solo en una pasada de auditoría, nunca en producción).

Adaptador principal

Esta tabla define la superficie canónica del adaptador. Conviene consultarla para ubicar la clase que se construye (TCPDF), sus métodos de modo estricto, sus puntos de escape y el contrato que implementa.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
NextPDF\Compat\Tcpdf\TCPDF	Los parámetros del constructor siguen la firma heredada de TCPDF a través de ConstructorBridge.	Crea un adaptador respaldado por un documento NextPDF.	TCPDF	Excepciones de validación del constructor o de funcionalidad no admitida.	Usar durante la migración, no para código nativo nuevo de NextPDF.
TCPDF::getDocument()	ninguno.	Devuelve el documento NextPDF subyacente.	NextPDF\Core\Document	ninguna esperada.	Punto de escape para código de migración que debe mezclar llamadas heredadas y nativas.
TCPDF::getUnitConverter()	ninguno.	Devuelve el convertidor creado a partir de la unidad heredada.	UnitConverter	ninguna esperada.	Usar para diagnósticos de migración, no para código de aplicación normal.
TCPDF::setStrictMode(bool $enabled)	Indicador de modo estricto.	Habilita o deshabilita el fallo explícito ante comportamientos de compatibilidad no admitidos.	static	ninguna esperada.	Mantener habilitado durante las auditorías de migración.
TCPDF::isStrictMode()	ninguno.	Devuelve el indicador actual de modo estricto.	bool	ninguna esperada.	Útil en aserciones de pruebas.
TCPDF métodos heredados	Varía según el método.	Los métodos admitidos se asignan a llamadas del documento del core; los métodos no admitidos fallan de forma explícita.	Varía según el método.	TcpdfNotImplementedException o UnsupportedFeatureException.	Consultar la cobertura de métodos antes de depender de un método.
CompatAdapterInterface::getDocument()	ninguno.	Método del contrato implementado por TCPDF.	Document	ninguna esperada.	Permite que las herramientas accedan al documento nativo.
CompatAdapterInterface::Output(string $name = '', string $dest = '')	Nombre de archivo y destino heredado.	Delega en el puente de salida.	string	Errores de escritura del core o de destino no admitido.	Refleja el punto de entrada de salida heredado de TCPDF; el TCPDF::Output concreto aporta los valores predeterminados 'doc.pdf'/'I'.

Grupos de métodos heredados

Esta tabla mapea las familias de métodos de TCPDF que cubre el adaptador. Sirve para ubicar, de forma aproximada, una llamada heredada concreta antes de comprobar su estado exacto en la cobertura de métodos.

Grupo	Símbolos representativos	Comportamiento predeterminado	Notas
Ciclo de vida y salida	Open(), Close(), Output(), getPDFData()	Mantiene el ciclo de vida del documento con interfaz de TCPDF sobre un documento nativo.	Preferir las APIs de salida nativas después de la migración.
Metadatos	SetTitle(), SetAuthor(), SetSubject(), SetKeywords(), SetCreator()	Asigna los setters de metadatos al documento subyacente.	Mantener la normalización de metadatos en el código de la aplicación.
Páginas y posicionamiento	AddPage(), setPage(), lastPage(), GetX(), SetXY()	Convierte unidades y coordenadas heredadas en operaciones nativas de página.	Verificar visualmente el posicionamiento absoluto después de la migración.
Márgenes y diseño	SetMargins(), SetAutoPageBreak(), setCellPaddings(), getMargins()	Almacena el estado de compatibilidad y asigna los valores admitidos.	El comportamiento complejo de salto de página de TCPDF puede requerir revisión manual.
Fuentes y texto	SetFont(), AddFont(), Cell(), MultiCell(), Write(), Text()	Enruta las operaciones de texto comunes a las APIs nativas de fuentes y texto.	Comprobar el comportamiento de CJK y de codificación con fuentes de producción.
HTML	writeHTML(), writeHTMLCell(), fixHTMLCode()	Envía el HTML admitido a la pipeline HTML nativa.	El renderer nativo no es un clon completo del HTML de TCPDF.
Imágenes y dibujo	Image(), Line(), Rect(), Circle(), SetDrawColor()	Asigna las operaciones gráficas admitidas a través de los componentes del adaptador.	Los formatos vectoriales o especiales no admitidos fallan de forma explícita.
Navegación y anotaciones	Bookmark(), AddLink(), SetLink(), Annotation()	Conserva las llamadas de navegación comunes cuando tienen asignación.	Validar los esquemas y los enlaces generados.
Seguridad y firmas	SetProtection(), setSignature(), setTimeStamp(), setUserRights()	Conecta las llamadas de seguridad heredadas admitidas con las funcionalidades nativas.	Tratar la salida criptográfica como una compuerta de verificación independiente.
Formularios, plantillas y transformaciones	TextField(), startTemplate(), StartTransform(), Rotate(), Scale()	Implementa los subconjuntos admitidos y falla de forma ruidosa ante comportamientos no admitidos.	Auditar cada llamada contra la cobertura de métodos antes de su puesta en producción.

Bootstrap y configuración

Usar esta tabla al integrar el adaptador en una ruta de arranque de la aplicación: al registrar los alias globales y al elegir entre las constantes heredadas y el moderno AdaptationConfig.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
LegacyBootstrap::enableAliases()	ninguno.	Registra los alias de compatibilidad una sola vez.	void	Errores de autoload o de entorno.	Usar solo cuando el código heredado espera que los nombres de TCPDF existan de forma global.
LegacyBootstrap::isRegistered()	ninguno.	Informa de si los alias se han registrado.	bool	ninguna esperada.	Útil en pruebas de bootstrap.
LegacyBootstrap::resetForTesting()	ninguno.	Limpia el estado de registro para las pruebas.	void	ninguna esperada.	Ayudante solo para pruebas.
AdaptationConfig	Indicadores del adaptador y controles de migración.	Usa los valores predeterminados del paquete cuando se omite.	AdaptationConfig	Valores de opción no válidos.	Mantener la configuración explícita durante las auditorías de migración.
AdaptationConfig::fromLegacyConstants()	ninguno.	Lee las constantes heredadas conocidas y construye la configuración.	AdaptationConfig	Valores de constante heredada no válidos.	Ayudante de transición para aplicaciones heredadas grandes.
LegacyDefaults	ninguno.	Proporciona los valores heredados predeterminados.	Conjunto de valores predeterminados.	ninguna esperada.	Punto central para los valores predeterminados de compatibilidad.

Puentes y ayudantes

Estas son las clases de conversión internas que usa el adaptador. Conviene consultar esta tabla principalmente al contribuir a la cobertura del adaptador o al diagnosticar cómo se tradujo un argumento heredado, no para el código de aplicación cotidiano.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
ConstructorBridge	Lista de argumentos del constructor heredado.	Normaliza las opciones heredadas en configuración de NextPDF.	Datos del constructor.	Valores de argumento heredado no válidos.	Lo utiliza internamente el adaptador.
CellParameterAdapter	Parámetros de celda de TCPDF.	Asigna los argumentos posicionales heredados a las opciones de diseño de texto del core.	Parámetros adaptados.	Dimensiones o alineación no válidas.	Preferir los métodos nativos del core en el código nuevo.
OutputBridge::dispatch(Document $document, string $filename, string $dest)	Documento nativo, nombre de archivo y destino heredado.	Asigna el comportamiento de inline, download o guardado a las APIs de salida de NextPDF.	string	Errores de escritura del core; destino no admitido.	Validar los nombres de archivo y las raíces de almacenamiento antes de la salida.
OutputBridge::resolveDestination(string $dest)	Código de destino heredado.	Convierte el destino en un destino de salida nativo.	OutputDestination	Errores de destino no admitido.	Mantiene centralizada la asignación de destinos.
ColorTranslator	Argumentos de color de TCPDF.	Normaliza las formas de color heredadas.	Valor de color del core.	Valores de color no válidos.	Lo utilizan los componentes de color y dibujo.
PageFormatResolver	Entrada de formato de página heredado.	Asigna los nombres conocidos a los tamaños de página del core.	Valor de formato de página.	Formato desconocido.	Usar tamaños de página nativos explícitos después de la migración.
UnitConverter	Valores de medida y unidades heredados.	Convierte a unidades del core.	Valor numérico.	Unidad no válida.	Ayuda a preservar el comportamiento de diseño heredado.

Excepciones

Usar esta tabla cuando una llamada de migración falla de forma ruidosa. Indica qué excepción significa «no implementado» frente a «conocido pero no admitido» y cómo recuperarse de cada una.

Símbolo	Significado	Recuperación
TcpdfNotImplementedException	El adaptador no implementa de forma intencionada el método heredado solicitado.	Reemplazar la llamada por la API nativa de NextPDF o eliminar la dependencia.
TcpdfNotImplementedException::forSilentIgnore()	Una llamada heredada que antes se habría ignorado pero que ahora se expone para mayor claridad en la migración.	Decidir si un comportamiento de no-op explícito es aceptable.
TcpdfNotImplementedException::forUnimplemented()	Una llamada heredada que no tiene ninguna ruta de adaptador implementada.	Reemplazar la llamada o aislarla detrás de código de migración.
UnsupportedFeatureException	La funcionalidad heredada es conocida, pero no está admitida dentro de los límites del adaptador.	Consultar la guía de migración y aislar la funcionalidad detrás de un adaptador de la aplicación.
UnsupportedFeatureException::forMethod()	Crea un error de funcionalidad no admitida específico de un método.	Usar en las contribuciones de compatibilidad para preservar mensajes de fallo coherentes.

Notas de desarrollo

• Tratar el adaptador como una herramienta de migración. El código nuevo debería apuntar directamente a las APIs del core de NextPDF.
• El comportamiento no admitido debería fallar de forma ruidosa. No capturar las excepciones de compatibilidad para continuar con un documento parcial, salvo que la aplicación acepte ese riesgo de forma explícita.
• Mantener los cambios de migración pequeños y verificar cada método heredado con la tabla de cobertura.