Inicio rápido con compat-legacy

Visión general

Esta página guía desde un paquete instalado hasta un PDF terminado y, a continuación, hasta la auditoría en modo estricto que se ejecuta antes de migrar. Cada bloque de código refleja un comportamiento verificado por la suite de pruebas del paquete, de modo que la salida mostrada aquí coincide con la que comprueban las pruebas.

Antes de empezar

Instalar el paquete y confirmar el enlace con el motor según /integrations/tcpdf-compat/install/. Se requiere PHP 8.4 y que nextpdf/core ^3.0 esté resuelto.

1. Generar el primer documento

Cambiar la importación y conservar las llamadas al estilo de TCPDF. Esta es la superficie exacta que verifica tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

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

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

Ejecutarlo:

php examples/quickstart-first.php

El archivo quickstart.pdf es un PDF 2.0 válido. La suite de pruebas verifica que la salida equivalente como cadena empieza por %PDF para los destinos S, F y E y para getPDFData().

Destinos de salida

Output($name, $dest) asigna los códigos de destino de TCPDF mediante un puente de salida seguro. Este es el comportamiento que cubre la suite de pruebas:

`$dest`	Comportamiento	Devuelve
`'S'`	Devuelve el PDF como cadena	los bytes del PDF (`%PDF…`)
`'F'`	Escribe el PDF en la ruta indicada	cadena vacía
`'E'`	Devuelve un cuerpo MIME en base64	un bloque `Content-Type: application/pdf`
`'I'`	En línea (predeterminado)	según el puente de salida
`'D'`	Descarga	según el puente de salida

A diferencia de TCPDF heredado, Output() no escribe directamente en el búfer de salida activo, por lo que se puede llamar de forma segura dentro de un trabajador de cola o de un controlador HTTP que gestiona su propia respuesta. Consultar /integrations/tcpdf-compat/production-usage/.

2. Ejecutar código TCPDF existente sin cambios

Para una migración real, ejecutar primero el código existente cambiando únicamente la importación o el alias. Si la base de código llama a new \TCPDF(...) contra el espacio de nombres global, habilitar los alias opcionales una sola vez durante el arranque (se trata en /integrations/tcpdf-compat/boot-and-discovery/):

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

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

LegacyBootstrap::enableAliases() es idempotente. Registra \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS y \TCPDF_IMAGES únicamente si esas clases aún no existen. La prueba del paquete tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php verifica que los alias se registran, que la llamada es idempotente y que new \TCPDF() es una instancia del adaptador. No habilitar los alias si la biblioteca real de TCPDF está cargada en el mismo proceso: consultar /integrations/tcpdf-compat/troubleshooting/.

3. Auditar con el modo estricto

Este paso es lo que hace segura una migración. Con el modo estricto desactivado (el valor predeterminado), los métodos que no pueden reproducir el comportamiento de TCPDF se degradan silenciosamente. Con el modo estricto activado, lanzan TcpdfNotImplementedException con la lista exacta de parámetros ignorados. Ejecutar esto en una pasada de auditoría dedicada, nunca en producción.

<?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 {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

La prueba del paquete tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php verifica que esta llamada exacta lanza una excepción en modo estricto, permanece en silencio en el modo predeterminado y que el mensaje contiene el nombre del método y los parámetros ignorados. Usar las excepciones recopiladas como lista de tareas de migración: consultar /integrations/tcpdf-compat/migration/.

4. Acceder a la API moderna cuando sea necesario

Cada instancia del adaptador expone el documento subyacente del motor. Usarlo para llamar a métodos modernos de NextPDF que no tienen equivalente en TCPDF:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument() devuelve el NextPDF\Core\Document envuelto por el adaptador. Esta es la vía de salida recomendada: migrar los puntos de llamada a la API moderna uno a uno, hasta que se pueda eliminar el adaptador.

Diferencias de comportamiento esperables de inmediato

MultiCell() devuelve 1, no el número de celdas representadas. El código que se ramifica según el valor devuelto por MultiCell() necesita ajustes.
Error() lanza RuntimeException en lugar de llamar a die(). El código que dependía de que el proceso finalizara debe capturar la excepción.
Los bytes exactos del PDF difieren de la salida de TCPDF. Restablecer la línea base de las aserciones de prueba a nivel de bytes para que, en su lugar, verifiquen el contenido representado.

La lista completa por método se encuentra en /integrations/tcpdf-compat/method-coverage/.

Próximos pasos

/integrations/tcpdf-compat/migration/ — la estrategia de migración completa archivo por archivo.
/integrations/tcpdf-compat/configuration/ — modo estricto, valores predeterminados y el objeto de configuración moderno.
/integrations/tcpdf-compat/production-usage/ — trabajadores, búferes de salida y rendimiento.
/integrations/tcpdf-compat/security-and-operations/ — postura de cifrado y firma.

Véase también

tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — oráculo para el comportamiento de salida
tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — oráculo para el modo estricto
docs/TCPDF_COVERAGE.md — matriz de cobertura canónica