Boot e discovery in NextPDF compat-legacy

In sintesi

nextpdf/compat-legacy espone una facade compatibile con TCPDF — la classe NextPDF\Compat\Tcpdf\TCPDF — che delega al motore NextPDF. È uno strato di compatibilità, non un clone drop-in. Copre 94 dei circa 120 metodi TCPDF 6.x esaminati mediante delega diretta. I metodi restanti presentano differenze comportamentali documentate (vedere /integrations/tcpdf-compat/method-coverage/).

Non viene eseguito alcun cablaggio globale durante l’autoload. Per impostazione predefinita, richiedere il pacchetto non crea una classe globale \TCPDF. Occorre attivare esplicitamente gli alias globali oppure, opzione preferibile durante la migrazione, importare la classe adapter file per file.

Come viene esposta la facade TCPDF

La facade è una normale classe caricata in autoload tramite PSR-4:

Elemento	Valore
Classe facade	NextPDF\Compat\Tcpdf\TCPDF
Prefisso PSR-4	NextPDF\Compat\Tcpdf\ è mappato su src/Compat/Tcpdf/
Contratto condiviso	NextPDF\Compat\Contracts\CompatAdapterInterface
Via di fuga	TCPDF::getDocument() restituisce il NextPDF\Core\Document incapsulato

La classe è intenzionalmente non final: gli utenti di TCPDF legacy estendono di norma TCPDF per sovrascrivere Header() e Footer(), quindi l’adapter preserva quel punto di estensione. A livello interno, la classe è una facade. È composta da 25 trait a singola responsabilità e delega tutte le operazioni PDF a un’istanza Document costruita in fase di build.

Sequenza di boot

Diagram

L’unico passaggio di «boot» è la costruzione. Nel pacchetto stesso non c’è alcuna registrazione nel service container né alcun bootstrap del framework. L’integrazione con il framework è uno strato sottile aggiuntivo — vedere /integrations/tcpdf-compat/integration/.

LegacyDefaults::register() è idempotente: definisce una costante solo quando tale costante non è già definita. Le costanti definite dall’applicazione prevalgono sempre, purché siano definite prima della prima costruzione (vedere /integrations/tcpdf-compat/configuration/ § Ordine di risoluzione della configurazione).

Alias di classe globali opt-in

Se il codice chiama new \TCPDF(...) nel namespace globale e non è ancora possibile modificare quei punti di chiamata, registrare gli alias globali una sola volta al boot dell’applicazione:

examples/boot-aliases.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases() registra \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS e \TCPDF_IMAGES. Il comportamento, verificato da tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php, è il seguente:

• È idempotente — chiamarla due volte non solleva eccezioni e registra una sola volta.
• LegacyBootstrap::isRegistered() indica se la registrazione è stata eseguita.
• Un new \TCPDF() dopo la registrazione è un’istanza dell’adapter.

Come evitare conflitti con un’installazione reale di TCPDF

È la regola in assoluto più importante di questa pagina.

enableAliases() registra un alias solo se non esiste già una classe con quel nome (class_exists($alias, autoload: false)). Pertanto:

• Se tecnickcom/tcpdf è installato e il suo \TCPDF viene caricato per primo, l’alias viene saltato silenziosamente e il codice continua a usare TCPDF legacy — non l’adapter.
• Eseguire entrambe le librerie con gli alias globali abilitati nello stesso processo non è supportato e produce un comportamento ambiguo.

Durante la migrazione, preferire gli import espliciti per file (use NextPDF\Compat\Tcpdf\TCPDF;). Si individuano con grep e sono privi di ambiguità. Rimuovere tecnickcom/tcpdf una volta superato l’audit in modalità strict (vedere /integrations/tcpdf-compat/migration/ Stage 5). Quando \TCPDF viene risolto alla classe sbagliata, /integrations/tcpdf-compat/troubleshooting/ fornisce la diagnostica.

Binding del container

Il pacchetto non include alcun binding del container del framework. Se si registra la facade in un container, registrare una factory che restituisca una nuova istanza di NextPDF\Compat\Tcpdf\TCPDF per ogni documento. Lo stato del documento appartiene alla singola istanza e non deve essere condiviso tra documenti non correlati (vedere /integrations/tcpdf-compat/production-usage/ § Concorrenza). Un binding tipico è mostrato in /integrations/tcpdf-compat/integration/.

Ordine di risoluzione della configurazione

In fase di costruzione, l’adapter risolve la configurazione in quest’ordine: prima gli argomenti del costruttore, poi le eventuali costanti legacy preesistenti definite dall’applicazione e infine i valori predefiniti di LegacyDefaults di TCPDF 6.2.13 per ogni costante non ancora definita. Per i dettagli completi e per il moderno oggetto AdaptationConfig, vedere /integrations/tcpdf-compat/configuration/.

Diagnostica

Per verificare che la facade sia cablata correttamente e che il collegamento con il motore venga risolto, costruire un adapter e produrre un PDF di una pagina, quindi controllare il prefisso %PDF. È la stessa superficie verificata dai test di output del pacchetto. Il controllo eseguibile si trova in /integrations/tcpdf-compat/install/ § Verificare l’installazione.

Per rilevare un conflitto con TCPDF reale prima di abilitare gli alias, verificare se esiste già un \TCPDF globale nel punto in cui si chiamerebbe enableAliases(). In tal caso un alias verrà saltato, perciò risolvere il conflitto (usare import espliciti oppure rimuovere il TCPDF reale) prima di affidarsi all’adapter.

Copertura dell’API TCPDF

La matrice di copertura autorevole e verificata dai test è contenuta nel file del repository docs/TCPDF_COVERAGE.md. Il riepilogo rivolto al lettore, comprese le liste dei metodi ignorati silenziosamente e dei metodi non implementati, è /integrations/tcpdf-compat/method-coverage/. Questo pacchetto non si dichiara un «sostituto drop-in» né «100% compatibile con TCPDF»; è un’alternativa compatibile con TCPDF, con una superficie di compatibilità nota e testata e differenze comportamentali documentate.

Vedere anche

• docs/TCPDF_COVERAGE.md — fonte di copertura autorevole (nel repository)
• /integrations/tcpdf-compat/integration/ — cablaggio della facade in un’applicazione/framework
• /integrations/tcpdf-compat/method-coverage/ — comportamento per metodo e lacune
• /integrations/tcpdf-compat/migration/ — strategia di migrazione a fasi
• /integrations/tcpdf-compat/troubleshooting/ — diagnosi del conflitto alias/real-TCPDF
• tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php — riferimento autorevole per il comportamento degli alias