Riferimento API di compatibilità TCPDF

In breve

Il pacchetto nextpdf/compat-legacy espone una classe principale, NextPDF\Compat\Tcpdf\TCPDF, che rispecchia l’API pubblica di TCPDF 6.x, ma usa il moderno motore NextPDF per il rendering. Espone anche un insieme ridotto di componenti di supporto: un LegacyBootstrap per gli alias di classe globali, una superficie di configurazione AdaptationConfig/LegacyDefaults, classi bridge interne (output, costruttore, colore, unità, formato pagina) ed eccezioni di compatibilità. È uno strumento di migrazione, non una dipendenza permanente. Lo stato completo dei metodi legacy è riportato nella tabella di copertura dei metodi. Questa pagina documenta le superfici dalle quali il codice applicativo dovrebbe dipendere intenzionalmente.

Inizio: per iniziare con questo pacchetto, costruire NextPDF\Compat\Tcpdf\TCPDF, effettuare le consuete chiamate TCPDF (AddPage(), SetFont(), Cell()) e concludere con Output($name, $dest). Questa singola classe è il punto di ingresso per quasi tutto ciò che segue. Vedere Attività comuni per punti di partenza eseguibili.

Attività comuni

Di seguito sono riportate le attività pratiche più frequenti per questo pacchetto. Ogni blocco è stato verificato sul codice sorgente rispetto all’adapter ed è eseguibile così com’è.

Generare un PDF con le consuete chiamate TCPDF e acquisirne il contenuto come stringa (per una coda, una risposta HTTP o l’archiviazione):

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

Cosa fa: genera un documento PDF 2.0 tramite l’adapter con interfaccia TCPDF e restituisce i byte grezzi (%PDF...), perché la destinazione 'S' passa da OutputBridge a Document::getPdfData() invece di inviarli in output; è quindi sicuro all’interno di un worker o di un controller.

Eseguire senza modifiche al sorgente il codice esistente new \TCPDF(...), registrando gli alias globali una sola volta all’avvio:

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

Cosa fa: enableAliases() registra in modo idempotente \TCPDF (e gli helper \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES) solo quando tali nomi non sono già definiti; il codice legacy invariato viene così eseguito sull’adapter.

Verificare una migrazione rendendo visibile ogni parametro TCPDF che verrebbe ignorato silenziosamente:

<?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
}

Cosa fa: con setStrictMode(true) una chiamata che non può riprodurre il comportamento di TCPDF solleva TcpdfNotImplementedException indicando i parametri ignorati. In questo modo la degradazione silenziosa si trasforma in un elenco di attività di migrazione (da usare solo in fase di verifica, mai in produzione).

Adapter principale

Questa tabella descrive la superficie canonica dell’adapter. Da consultare quando servono la classe da costruire (TCPDF), i relativi metodi di modalità strict e di escape hatch e il contratto che implementa.

Simbolo	Parametri	Comportamento predefinito	Valori restituiti	Solleva o fallisce con	Note
NextPDF\Compat\Tcpdf\TCPDF	I parametri del costruttore seguono la forma legacy di TCPDF tramite ConstructorBridge.	Crea un adapter basato su un documento NextPDF.	TCPDF	Eccezioni per convalida del costruttore o funzionalità non supportata.	Da usare durante la migrazione, non per nuovo codice nativo NextPDF.
TCPDF::getDocument()	nessuno.	Restituisce il documento NextPDF sottostante.	NextPDF\Core\Document	nessuna prevista.	Escape hatch per il codice di migrazione che deve combinare chiamate legacy e native.
TCPDF::getUnitConverter()	nessuno.	Restituisce il convertitore creato a partire dall’unità legacy.	UnitConverter	nessuna prevista.	Da usare per la diagnostica di migrazione, non per il normale codice applicativo.
TCPDF::setStrictMode(bool $enabled)	Flag per la modalità strict.	Abilita o disabilita il fallimento esplicito per i comportamenti di compatibilità non supportati.	static	nessuna prevista.	Da mantenere abilitato durante le verifiche di migrazione.
TCPDF::isStrictMode()	nessuno.	Restituisce il flag corrente della modalità strict.	bool	nessuna prevista.	Utile nelle asserzioni dei test.
metodi legacy di TCPDF	Varia in base al metodo.	I metodi supportati vengono mappati su chiamate al documento core; i metodi non supportati falliscono in modo esplicito.	Varia in base al metodo.	TcpdfNotImplementedException o UnsupportedFeatureException.	Controllare la copertura dei metodi prima di affidarsi a un metodo.
CompatAdapterInterface::getDocument()	nessuno.	Metodo del contratto implementato da TCPDF.	Document	nessuna prevista.	Consente agli strumenti di raggiungere il documento nativo.
CompatAdapterInterface::Output(string $name = '', string $dest = '')	Nome del file e destinazione legacy.	Delega al bridge di output.	string	Errori di scrittura del core o destinazione non supportata.	Rispecchia il punto di ingresso legacy di TCPDF per l’output; il concreto TCPDF::Output fornisce i valori predefiniti 'doc.pdf'/'I'.

Gruppi di metodi legacy

Questa tabella mappa le famiglie di metodi TCPDF coperte dall’adapter. Esaminarla per individuare approssimativamente dove ricade una determinata chiamata legacy prima di verificarne lo stato esatto nella copertura dei metodi.

Gruppo	Simboli rappresentativi	Comportamento predefinito	Note
Ciclo di vita e output	Open(), Close(), Output(), getPDFData()	Mantiene il ciclo di vita del documento in stile TCPDF su un documento nativo.	Dopo la migrazione, preferire le API di output native.
Metadati	SetTitle(), SetAuthor(), SetSubject(), SetKeywords(), SetCreator()	Mappa i setter dei metadati sul documento sottostante.	Mantenere la normalizzazione dei metadati nel codice applicativo.
Pagine e posizionamento	AddPage(), setPage(), lastPage(), GetX(), SetXY()	Converte unità e coordinate legacy in operazioni di pagina native.	Verificare visivamente il posizionamento assoluto dopo la migrazione.
Margini e layout	SetMargins(), SetAutoPageBreak(), setCellPaddings(), getMargins()	Conserva lo stato di compatibilità e mappa i valori supportati.	Il comportamento complesso di interruzione di pagina di TCPDF può richiedere una revisione manuale.
Font e testo	SetFont(), AddFont(), Cell(), MultiCell(), Write(), Text()	Instrada le operazioni di testo comuni verso le API native di font e testo.	Verificare il comportamento CJK e della codifica con i font di produzione.
HTML	writeHTML(), writeHTMLCell(), fixHTMLCode()	Invia l’HTML supportato alla pipeline HTML nativa.	Il renderer nativo non replica integralmente l’HTML di TCPDF.
Immagini e disegno	Image(), Line(), Rect(), Circle(), SetDrawColor()	Mappa le operazioni grafiche supportate attraverso le componenti dell’adapter.	I formati vettoriali o speciali non supportati falliscono in modo esplicito.
Navigazione e annotazioni	Bookmark(), AddLink(), SetLink(), Annotation()	Preserva le chiamate di navigazione comuni quando sono mappate.	Convalidare gli outline e i collegamenti generati.
Sicurezza e firme	SetProtection(), setSignature(), setTimeStamp(), setUserRights()	Collega le chiamate di sicurezza legacy supportate alle funzionalità native.	Trattare l’output crittografico come un gate di verifica separato.
Moduli, template, trasformazioni	TextField(), startTemplate(), StartTransform(), Rotate(), Scale()	Implementa i sottoinsiemi supportati e fallisce in modo esplicito per i comportamenti non supportati.	Verificare ogni chiamata rispetto alla copertura dei metodi prima del rilascio.

Bootstrap e configurazione

Da consultare per integrare l’adapter nel percorso di avvio di un’applicazione, registrando gli alias globali e scegliendo tra le costanti legacy e la moderna AdaptationConfig.

Simbolo	Parametri	Comportamento predefinito	Valori restituiti	Solleva o fallisce con	Note
LegacyBootstrap::enableAliases()	nessuno.	Registra gli alias di compatibilità una sola volta.	void	Errori di autoload o di ambiente.	Da usare solo quando il codice legacy si aspetta che i nomi TCPDF esistano a livello globale.
LegacyBootstrap::isRegistered()	nessuno.	Indica se gli alias sono stati registrati.	bool	nessuna prevista.	Utile nei test di bootstrap.
LegacyBootstrap::resetForTesting()	nessuno.	Cancella lo stato di registrazione per i test.	void	nessuna prevista.	Helper riservato ai test.
AdaptationConfig	Flag dell’adapter e controlli per la migrazione.	Usa i valori predefiniti del pacchetto quando omessi.	AdaptationConfig	Valori di opzione non validi.	Mantenere la configurazione esplicita durante le verifiche di migrazione.
AdaptationConfig::fromLegacyConstants()	nessuno.	Legge le costanti legacy note e costruisce la configurazione.	AdaptationConfig	Valori di costante legacy non validi.	Helper di transizione per applicazioni legacy di grandi dimensioni.
LegacyDefaults	nessuno.	Fornisce i valori legacy predefiniti.	Insieme dei valori predefiniti.	nessuna prevista.	Punto centrale per i valori predefiniti di compatibilità.

Bridge e helper

Queste sono le classi di conversione interne utilizzate dall’adapter. Consultare questa tabella soprattutto per contribuire alla copertura dell’adapter o per diagnosticare come viene tradotto un argomento legacy, non per il codice applicativo quotidiano.

Simbolo	Parametri	Comportamento predefinito	Valori restituiti	Solleva o fallisce con	Note
ConstructorBridge	Elenco degli argomenti del costruttore legacy.	Normalizza le opzioni legacy nella configurazione di NextPDF.	Dati per il costruttore.	Valori di argomento legacy non validi.	Utilizzato internamente dall’adapter.
CellParameterAdapter	Parametri di cella TCPDF.	Mappa gli argomenti posizionali legacy sulle opzioni di layout del testo del core.	Parametri adattati.	Dimensioni o allineamento non validi.	Nel nuovo codice, preferire i metodi nativi del core.
OutputBridge::dispatch(Document $document, string $filename, string $dest)	Documento nativo, nome del file e destinazione legacy.	Mappa i comportamenti inline/download/salvataggio sulle API di output NextPDF.	string	Errori di scrittura del core; destinazione non supportata.	Convalidare i nomi dei file e le radici di archiviazione prima dell’output.
OutputBridge::resolveDestination(string $dest)	Codice di destinazione legacy.	Converte la destinazione in una destinazione di output nativa.	OutputDestination	Errori di destinazione non supportata.	Mantiene centralizzata la mappatura delle destinazioni.
ColorTranslator	Argomenti di colore TCPDF.	Normalizza le forme di colore legacy.	Valore di colore del core.	Valori di colore non validi.	Utilizzato dalle componenti di colore e disegno.
PageFormatResolver	Input legacy per il formato pagina.	Mappa i nomi noti alle dimensioni di pagina del core.	Valore di formato pagina.	Formato sconosciuto.	Dopo la migrazione, usare dimensioni di pagina native esplicite.
UnitConverter	Valori di misura e unità legacy.	Converte nelle unità del core.	Valore numerico.	Unità non valida.	Contribuisce a preservare il comportamento di layout legacy.

Eccezioni

Usare questa tabella quando una chiamata di migrazione fallisce in modo esplicito. Indica quale eccezione significa «non implementato» rispetto a «noto ma non supportato» e come gestire il recupero da ciascuna.

Simbolo	Significato	Ripristino
TcpdfNotImplementedException	L’adapter non implementa intenzionalmente il metodo legacy richiesto.	Sostituire la chiamata con l’API nativa NextPDF o rimuovere la dipendenza.
TcpdfNotImplementedException::forSilentIgnore()	Una chiamata legacy che in precedenza sarebbe stata ignorata viene resa esplicita per chiarezza nella migrazione.	Decidere se il comportamento esplicito di no-op è accettabile.
TcpdfNotImplementedException::forUnimplemented()	Una chiamata legacy non dispone di alcun percorso di adapter implementato.	Sostituire la chiamata o isolarla dietro codice di migrazione.
UnsupportedFeatureException	La funzionalità legacy è nota ma non supportata nei limiti dell’adapter.	Consultare le linee guida per la migrazione e isolare la funzionalità dietro un adapter applicativo.
UnsupportedFeatureException::forMethod()	Crea un errore di funzionalità non supportata specifico per il metodo.	Da usare nei contributi di compatibilità per preservare messaggi di errore coerenti.

Note di sviluppo

• Trattare l’adapter come uno strumento di migrazione. Il nuovo codice dovrebbe usare direttamente le API core NextPDF.
• Il comportamento non supportato dovrebbe fallire in modo esplicito. Non intercettare le eccezioni di compatibilità per poi continuare con un documento parziale, a meno che l’applicazione non accetti esplicitamente tale rischio.
• Mantenere circoscritte le modifiche di migrazione e verificare ogni metodo legacy rispetto alla tabella di copertura.