Panoramica di NextPDF compat-legacy

In breve

nextpdf/compat-legacy è un’alternativa compatibile con TCPDF: un livello di compatibilità che espone l’API pubblica di TCPDF 6.x sul motore PDF 2.0 di NextPDF. Ha un solo compito: permettere a una codebase che dipende già da TCPDF 6.x di funzionare sul motore NextPDF senza riscriverla, così che la migrazione possa procedere file per file invece che in blocco.

Non è un fork di TCPDF né viene presentato come un clone comportamentale garantito. È un’implementazione indipendente che mantiene le firme di chiamata di TCPDF. La descrizione precisa è questa: copre 94 dei circa 120 metodi TCPDF 6.x esaminati tramite delega diretta, mentre i metodi restanti hanno differenze comportamentali documentate (vedere /integrations/tcpdf-compat/method-coverage/).

Che cos’è

Un ausilio alla migrazione. Il pacchetto fa parte della famiglia compat di NextPDF. Il suo scopo è abbreviare il percorso di uscita da una libreria PDF legacy, non diventare una dipendenza permanente. Va trattato come un’impalcatura da rimuovere man mano che si adotta l’API moderna.
Un adattatore della superficie API. Fornisce il nome della classe TCPDF, i nomi dei metodi, l’ordine dei parametri e i valori predefiniti di 6.2.13. Le chiamate vengono delegate a un’istanza NextPDF\Core\Document.
Un’implementazione indipendente, clean-room. Nessun codice sorgente TCPDF, artefatto di build, dato relativo ai font o altra espressione tutelabile da copyright è stato copiato o tradotto in questo pacchetto. Il nome TCPDF è usato esclusivamente per l’identificazione ai fini dell’interoperabilità. La dichiarazione canonica si trova nel file NOTICE del pacchetto.

Che cosa non è

Non è un «sostituto immediato» con output identico byte per byte. Il risultato visibile è compatibile per i metodi delegati, ma i byte del PDF prodotto sono diversi perché il motore sottostante è un’implementazione PDF 2.0 diversa e indipendente.
Non è «compatibile al 100% con TCPDF». In un insieme definito di metodi vengono accettati parametri legacy che il motore non rispetta, oppure l’invocazione non produce alcun effetto. Questi casi sono enumerati e testati: vedere /integrations/tcpdf-compat/method-coverage/.
Di per sé non è un prodotto di firma o di archiviazione. Le firme digitali e la conformità di archiviazione PDF/A sono riservate a un’edizione commerciale di NextPDF. Questa documentazione non formula alcuna rivendicazione relativa a firme certificate, garantite o legalmente valide.

Perché migrare tramite un livello di compatibilità

Una riscrittura completa di ogni chiamata TCPDF in un’applicazione di grandi dimensioni comporta un rischio elevato ed è difficile da rilasciare in modo incrementale. Il livello di compatibilità consente di:

Sostituire la dipendenza ed eseguire la suite esistente per individuare ciò che funziona già senza modifiche.
Usare la modalità strict come audit per enumerare ogni punto in cui il comportamento di TCPDF non può essere riprodotto esattamente.
Migrare quei punti di chiamata all’API moderna di NextPDF uno alla volta, mantenendo l’applicazione rilasciabile durante l’intero processo.

L’obiettivo finale è l’API moderna NextPDF\Core\Document con il livello di compatibilità rimosso. Vedere /integrations/tcpdf-compat/migration/ per la strategia completa.

Che cosa offre il motore NextPDF

Quando una chiamata TCPDF viene delegata, viene eseguita su un motore PDF 2.0 (ISO 32000-2), con cifratura AES-256 dello standard-handler disponibile e sicurezza dei tipi PHPStan Level 10 in tutto l’adattatore. L’output viene sempre scritto come PDF 2.0; l’adattatore non può ridurre il target a versioni PDF precedenti (vedere /integrations/tcpdf-compat/method-coverage/ §4).

L’adattatore rafforza diverse criticità storiche di TCPDF 6.2.13:

Comportamento legacy	Comportamento dell’adattatore
`Error()` chiama `die()` e termina silenziosamente il processo	`Error()` lancia `RuntimeException`: osservabile e intercettabile
Metodo HTML che poteva eseguire PHP a partire dal markup	Questo percorso è disabilitato: il markup non può innescare l’esecuzione di PHP
`Output()` scrive direttamente l’output e può corrompere i buffer di output dei worker	L’output viene instradato attraverso un bridge di destinazione sicuro
Ricorsione di header/footer non protetta	Protetta contro la ricorsione

Ambito ed edizioni

Il livello di compatibilità è incluso nella distribuzione core (nextpdf/compat-legacy, che richiede nextpdf/core ^3.0). La cifratura tramite lo standard handler è disponibile in core. Le firme digitali e la conformità di archiviazione PDF/A richiedono un’edizione commerciale di NextPDF; l’adattatore espone i punti di ingresso, ma il percorso core non costituisce un prodotto di firma. Vedere /integrations/tcpdf-compat/security-and-operations/ per la dichiarazione precisa.

Passaggi successivi

/integrations/tcpdf-compat/install/ — installare il pacchetto e verificare il collegamento al motore.
/integrations/tcpdf-compat/quickstart/ — creare un primo documento eseguibile e supportato da test.
/integrations/tcpdf-compat/method-coverage/ — capire che cosa fa esattamente ogni metodo TCPDF in questo contesto.
/integrations/tcpdf-compat/migration/ — pianificare la strategia di migrazione file per file.
/integrations/tcpdf-compat/configuration/ — configurare la modalità strict e l’adattatore.
/integrations/tcpdf-compat/production-usage/ — eseguire l’adattatore sotto carico e nei worker.
/integrations/tcpdf-compat/security-and-operations/ — gestire cifratura, postura relativa alle firme e hardening.
/integrations/tcpdf-compat/troubleshooting/ — diagnosticare problemi di migrazione comuni e applicare le relative correzioni.
/integrations/tcpdf-compat/integration/ / /integrations/tcpdf-compat/boot-and-discovery/ — integrare la facciata in un’applicazione e registrare gli alias di classe globali.

Vedere anche

docs/TCPDF_COVERAGE.md — matrice di copertura autorevole (nel repository)
File NOTICE del pacchetto — dichiarazione di implementazione indipendente