Integrazione di NextPDF compat-legacy

In breve

Questa pagina spiega come collegare nextpdf/compat-legacy a un’applicazione, così che il codice TCPDF 6.x esistente venga eseguito sul motore NextPDF. Il pacchetto è un ausilio alla migrazione, non uno shim permanente — l’obiettivo è rimuoverlo dopo l’adozione dell’API moderna (vedere /integrations/tcpdf-compat/migration/). È un’alternativa compatibile con TCPDF, non un clone sostitutivo immediato: 94 dei ~120 metodi TCPDF esaminati delegano direttamente. I metodi restanti presentano differenze di comportamento documentate (vedere /integrations/tcpdf-compat/method-coverage/).

Installazione

composer require nextpdf/compat-legacy:^3.0

Questo risolve nextpdf/core ^3.0 in modo transitivo. Per i requisiti completi e una verifica di controllo, vedere /integrations/tcpdf-compat/install/.

Avvio e individuazione automatica

Non viene creato alcun collegamento globale al momento dell’autoload. L’inclusione del pacchetto non crea un \TCPDF globale. Spetta a chi sviluppa decidere come i punti di chiamata risolvono la classe:

Consigliato (import espliciti). Modificare le righe use/require in use NextPDF\Compat\Tcpdf\TCPDF; in ogni file. È una scelta non ambigua e ricercabile con grep.
Alias globali opzionali. Chiamare LegacyBootstrap::enableAliases() una sola volta all’avvio per registrare \TCPDF e le quattro classi helper — solo se quei nomi non sono già occupati. Per meccanismo, idempotenza e regola di conflitto con il TCPDF reale, vedere /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();

Binding del container

Il pacchetto non include alcun service provider o bundle di framework. L’integrazione è un livello sottile, sotto il pieno controllo di chi sviluppa. Registrare una factory che restituisca un nuovo adapter per ogni documento — mai un singleton condiviso, perché lo stato del documento è per istanza (vedere /integrations/tcpdf-compat/production-usage/ § Concorrenza).

<?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);

Per Symfony, registrare la factory come servizio non condiviso. Per Laravel, registrarla con bind (non singleton) in modo che ogni risoluzione sia una nuova istanza. Il pacchetto stesso rimane indipendente dal framework.

Pubblicazione della configurazione

Non esiste alcun file di configurazione di framework da pubblicare. Configurare tramite le costanti legacy K_* / PDF_* (definendole nel bootstrap prima della prima costruzione) oppure tramite il moderno oggetto immutabile NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Vedere /integrations/tcpdf-compat/configuration/.

Smoke test del service provider / bundle

Dopo il collegamento, verificare che l’integrazione produca un PDF valido. Il controllo rispecchia la superficie verificata da 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";

In un contesto HTTP o worker, usare Output(..., 'F') o 'S'. Non fare affidamento sul percorso inline. Le indicazioni operative complete sono disponibili in /integrations/tcpdf-compat/production-usage/.

Punti di ingresso dell’API pubblica

Punto di ingresso	Scopo
`NextPDF\Compat\Tcpdf\TCPDF`	Facade compatibile con TCPDF. Istanziare una volta per ogni documento.
`TCPDF::getDocument()`	Restituisce il `NextPDF\Core\Document` incapsulato — la via di fuga verso l’API moderna.
`TCPDF::setStrictMode(bool)`	Interruttore di audit della migrazione (vedere /integrations/tcpdf-compat/configuration/).
`NextPDF\Compat\Tcpdf\LegacyBootstrap::enableAliases()`	Alias di classe globali opzionali.
`NextPDF\Compat\Tcpdf\Config\AdaptationConfig`	Oggetto di configurazione moderno e immutabile.
`NextPDF\Compat\Contracts\CompatAdapterInterface`	Contratto di compatibilità condiviso.

Copertura dell’API TCPDF

La matrice di copertura autorevole, verificata dai test, è il file docs/TCPDF_COVERAGE.md presente nel repository. Il riepilogo destinato a chi legge — metodi rispecchiati, ignorati in silenzio, non implementati e non applicabili — si trova in /integrations/tcpdf-compat/method-coverage/. Non viene fatta alcuna affermazione di «sostituto immediato» o «100% compatibile». La descrizione accurata è quella di un’alternativa compatibile con TCPDF, con una superficie nota e testata e differenze di comportamento documentate.

Vedere anche

docs/TCPDF_COVERAGE.md — fonte di copertura autorevole (nel repository)
/integrations/tcpdf-compat/boot-and-discovery/ — esposizione della facade e meccanismo degli alias
/integrations/tcpdf-compat/method-coverage/ — comportamento e lacune per ogni metodo
/integrations/tcpdf-compat/migration/ — strategia di migrazione per fasi
/integrations/tcpdf-compat/production-usage/ — esecuzione dell’adapter sotto carico
tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — oracolo del comportamento di output