Integración de compat-legacy de NextPDF

En resumen

Esta página explica cómo conectar nextpdf/compat-legacy a una aplicación para que el código TCPDF 6.x existente se ejecute sobre el motor NextPDF. El paquete es una ayuda para la migración, no un adaptador permanente: el objetivo es retirarlo una vez adoptada la API moderna (ver /integrations/tcpdf-compat/migration/). Es una alternativa compatible con TCPDF, no un clon de sustitución directa: 94 de los ~120 métodos de TCPDF analizados delegan directamente. El resto tiene diferencias de comportamiento documentadas (ver /integrations/tcpdf-compat/method-coverage/).

Instalación

composer require nextpdf/compat-legacy:^3.0

Esto resuelve nextpdf/core ^3.0 de forma transitiva. Los requisitos completos y una comprobación de verificación están en /integrations/tcpdf-compat/install/.

Arranque y descubrimiento automático

No se realiza ninguna conexión global durante la autocarga. Incluir el paquete con require no crea un \TCPDF global. Se debe definir cómo resuelven la clase los puntos de llamada:

Recomendado (importaciones explícitas). Cambiar las líneas use/require a use NextPDF\Compat\Tcpdf\TCPDF; en cada archivo. No deja ambigüedad y es fácil de localizar con grep.
Alias globales opcionales. Llamar a LegacyBootstrap::enableAliases() una vez en el arranque para registrar \TCPDF y las cuatro clases auxiliares, solo si esos nombres no están ya ocupados. El mecanismo, la idempotencia y la regla de conflicto con el TCPDF real están en /integrations/tcpdf-compat/boot-and-discovery/.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

// One call at application bootstrap, before any \TCPDF use.
LegacyBootstrap::enableAliases();

Enlaces del contenedor

El paquete no incluye ningún proveedor de servicios ni bundle de framework. La integración es una capa ligera bajo responsabilidad de la aplicación. Enlazar una factoría que devuelva un adaptador nuevo para cada documento, nunca un singleton compartido, porque el estado del documento es por instancia (ver /integrations/tcpdf-compat/production-usage/ § Concurrencia).

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use Psr\Container\ContainerInterface;

// Pseudocode for a PSR-11-style container: bind a factory, not a shared instance.
$container->set(TCPDF::class, static function (ContainerInterface $c): TCPDF {
    return new TCPDF('P', 'mm', 'A4');
});

// Each resolution is an independent document context.
$pdf = $container->get(TCPDF::class);

En Symfony, registrar la factoría como un servicio no compartido. En Laravel, enlazarla con bind (no con singleton) para que cada resolución sea una instancia nueva. El paquete en sí permanece independiente del framework.

Publicar la configuración

No hay ningún archivo de configuración de framework publicable. Configurar mediante las constantes heredadas K_* / PDF_* (definirlas en su bootstrap antes de la primera construcción) o mediante el moderno objeto inmutable NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Ver /integrations/tcpdf-compat/configuration/.

Prueba de humo del proveedor de servicios / bundle

Tras la conexión, verificar que la integración produce un PDF válido. Esto refleja la superficie comprobada por 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->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Integration smoke test');

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

assert(str_starts_with($bytes, '%PDF'), 'Integration smoke test failed');
echo "Integration OK\n";

En contextos HTTP o de worker, usar Output(..., 'F') o 'S'. No depender de la salida en línea. La guía operativa completa está en /integrations/tcpdf-compat/production-usage/.

Puntos de entrada de la API pública

Punto de entrada	Propósito
`NextPDF\Compat\Tcpdf\TCPDF`	La fachada compatible con TCPDF. Construirla por documento.
`TCPDF::getDocument()`	Devuelve el `NextPDF\Core\Document` envuelto: la vía de escape hacia la API moderna.
`TCPDF::setStrictMode(bool)`	Interruptor de auditoría de migración (consulte /integrations/tcpdf-compat/configuration/).
`NextPDF\Compat\Tcpdf\LegacyBootstrap::enableAliases()`	Alias de clase globales opcionales.
`NextPDF\Compat\Tcpdf\Config\AdaptationConfig`	Objeto moderno de configuración inmutable.
`NextPDF\Compat\Contracts\CompatAdapterInterface`	Contrato de compatibilidad compartido.

Cobertura de la API de TCPDF

La matriz de cobertura de referencia, verificada con pruebas, es el archivo del repositorio docs/TCPDF_COVERAGE.md. El resumen orientado al lector —métodos reflejados, ignorados en silencio, no implementados y no aplicables— está en /integrations/tcpdf-compat/method-coverage/. No se afirma que sea una «sustitución directa» ni «100 % compatible». La descripción precisa es: una alternativa compatible con TCPDF, con una superficie conocida y probada y diferencias de comportamiento documentadas.

Véase también

docs/TCPDF_COVERAGE.md — fuente de cobertura de referencia (en el repositorio)
/integrations/tcpdf-compat/boot-and-discovery/ — exposición de la fachada y mecanismo de alias
/integrations/tcpdf-compat/method-coverage/ — comportamiento y carencias por método
/integrations/tcpdf-compat/migration/ — estrategia de migración por fases
/integrations/tcpdf-compat/production-usage/ — ejecución del adaptador bajo carga
tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — oráculo del comportamiento de salida