Copertura dei metodi TCPDF in NextPDF compat-legacy

In sintesi

nextpdf/compat-legacy è un livello di compatibilità, non un fork di TCPDF né un clone comportamentale garantito. Espone i nomi dei metodi pubblici, l’ordine dei parametri e i valori predefiniti di TCPDF 6.x sopra il motore core di NextPDF. La maggior parte delle chiamate corrisponde direttamente a un’operazione NextPDF Document. Una minoranza ben definita accetta parametri legacy che NextPDF non onora, oppure non produce alcun effetto.

Questa pagina offre un riepilogo orientato alla lettura dell’audit metodo per metodo. La matrice di copertura autorevole e verificata dai test si trova nel repository in docs/TCPDF_COVERAGE.md. In caso di divergenza tra questa pagina e la matrice nel repository, prevale la matrice nel repository, perché è verificata dalla suite di test.

Usare questa pagina per rispondere a una domanda prima della migrazione: per ogni metodo TCPDF chiamato dalla codebase, che cosa fa effettivamente l’adapter?

Riepilogo della copertura

L’audit ha esaminato circa 120 metodi pubblici di TCPDF 6.x. Ciascuno è stato assegnato esattamente a una di quattro categorie.

Categoria	Conteggio	Che cosa significa per te
Rispecchiati — delega completa	94	La chiamata corrisponde direttamente a un metodo NextPDF `Document`. Il comportamento è compatibile per i parametri documentati.
Ignorati-in-silenzio — parziali	15	Il metodo viene eseguito e produce output, ma uno o più parametri TCPDF non hanno alcun effetto. È una differenza di comportamento documentata.
Non implementati — corpo no-op	4	Il metodo esiste per la compatibilità del sorgente ma non fa nulla.
Non applicabili	7	Il metodo TCPDF non ha effetto sull’output PDF; è escluso intenzionalmente.
Metodi di drift dell’API moderna aggiunti	17	Metodi Document di NextPDF v5.1+ esposti sull’adapter affinché il codice con API mista compili. Nessun equivalente in TCPDF 6.x.

Queste cifre provengono da docs/TCPDF_COVERAGE.md §Summary. La matrice è verificata da tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php e tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php.

Nota sulla formulazione. Questo pacchetto non pretende di essere un «sostituto drop-in » né di essere «compatibile al 100% con TCPDF». Copre 94 dei ~120 metodi TCPDF esaminati tramite delega diretta; i metodi rimanenti presentano differenze di comportamento documentate, descritte di seguito. La descrizione accurata è alternativa compatibile con TCPDF con una superficie di compatibilità nota e testata.

Una nota sui conteggi dei metodi

L’adapter è costruito a partire da 25 trait di concern a responsabilità singola (src/Compat/Tcpdf/Concerns/) che espongono complessivamente 273 metodi pubblici, oltre a un piccolo numero di metodi di ciclo di vita e di escape-hatch sulla classe TCPDF stessa. Le categorie di copertura qui sopra conteggiano i metodi distinti della superficie API di TCPDF 6.x (~120), non il numero totale dei metodi pubblici dell’adapter. I due numeri misurano aspetti diversi: la copertura della superficie API rispetto alla dimensione dell’implementazione. Se nel README.md del pacchetto compare un conteggio di trait o di metodi inferiore, considerare docs/TCPDF_COVERAGE.md e questa pagina come autorevoli — il riepilogo del README precede il trait AdaptsDriftV51.

1. Metodi rispecchiati — delega compatibile

Novantaquattro metodi corrispondono direttamente all’istanza NextPDF\Core\Document sottostante. I nomi TCPDF in PascalCase corrispondono ai nomi NextPDF in camelCase quando il motore usa camelCase; l’adapter accetta entrambe le grafie per la compatibilità in avanti e all’indietro.

Gruppi rappresentativi (tabella completa: docs/TCPDF_COVERAGE.md §1):

Area TCPDF	Metodi di esempio	Trait dell’adapter
Ciclo di vita	`Output()`, `Close()`, `getPDFData()`	`AdaptsLifecycle`
Pagine	`AddPage()`, `getNumPages()`, `deletePage()`	`AdaptsPageManagement`
Testo	`Cell()`, `MultiCell()`, `Write()`, `Text()`, `Ln()`	`AdaptsTextOutput`
Font	`SetFont()`, `SetFontSize()`, `AddFont()`	`AdaptsFonts`
Colori	`SetTextColor()`, `SetDrawColor()`, `SetFillColor()`	`AdaptsColors`
Disegno	`Line()`, `Rect()`, `Circle()`, `Polygon()`, `Arrow()`	`AdaptsDrawing`
Trasformazioni	`Rotate()`, `Scale()`, `Translate()`, `Skew()`, `Mirror*()`	`AdaptsTransforms`
Navigazione	`AddLink()`, `Annotation()`, `addTOC()`	`AdaptsNavigation`

Per questi metodi, il comportamento osservato è compatibile con TCPDF 6.x per i parametri documentati da NextPDF. L’adapter non garantisce un output PDF identico byte per byte. Il motore sottostante è un’implementazione PDF 2.0 indipendente, quindi i byte prodotti dal rendering differiscono anche quando il risultato visibile è equivalente. Se i test fanno asserzioni sui byte PDF esatti anziché sul contenuto sottoposto a rendering, prevedere il riallineamento di tali asserzioni. Vedi /integrations/tcpdf-compat/migration/ per la strategia di riallineamento consigliata.

2. Metodi ignorati-in-silenzio — differenze di comportamento documentate

Questi 15 metodi vengono eseguiti e producono output, ma almeno un parametro TCPDF viene accettato per la compatibilità del sorgente e poi ignorato. È la sezione più importante da leggere prima della migrazione, perché la chiamata non fallisce — semplicemente fa meno dell’originale TCPDF, in silenzio.

Metodo TCPDF	Parametri ignorati	Alternativa compatibile
`Image()`	type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs	NextPDF `image()` accetta file, x, y, width, height. Per un’immagine cliccabile, disegnare l’immagine e poi aggiungere `Document::link()` sopra lo stesso rettangolo. Il mascheramento delle immagini e le immagini alternative non sono supportati.
`writeHTML()`	ln, fill, reseth, cell, align	NextPDF `writeHtml()` gestisce solo il contenuto. Per il controllo del layout, racchiudere l’HTML in un blocco posizionato tramite l’API moderna.
`writeHTMLCell()`	border (forma stringa), ln, fill, reseth, autopadding	Larghezza, altezza, posizione e un bordo booleano sono onorati; un layout di cella più ricco non ha alcuna corrispondenza.
`ImageEps()`	link, useBoundingBox, align, palign, border, fitonpage, fixoutvals	Solo posizione e dimensione.
`ImageSVG()`	link, align, palign, border, fitonpage	Solo posizione e dimensione.
`SetProtection()`	mode (diverso da zero), pubkeys (non vuoto)	NextPDF usa sempre AES-256 per il gestore standard. Per la cifratura basata su certificato, usare il moderno `setPublicKeyEncryption()` esposto sull’adapter (vedi /integrations/tcpdf-compat/security-and-operations/).
`Bookmark()`	style, color, x, isNamedDest	Titolo, livello e posizione y sono onorati.
`setDestination()`	page, x	Nome e posizione y sono onorati.
`Link()`	spaces	Tracciamento degli spazi interno di TCPDF; nessun equivalente nel motore.
`Annotation()`	chiavi di opzione oltre a Subtype, spaces	Tipo, posizione e testo sono onorati.
`SetLineStyle()`	dettaglio del pattern dei tratteggi oltre alla larghezza	Le proprietà fondamentali della linea sono associate.
`setAlpha()`	mappa parziale delle modalità di fusione	Alcuni nomi di modalità di fusione non hanno equivalente nel motore.
`Polycurve()`	elenco completo dei parametri	No-op in modalità predefinita; nessun equivalente nel motore.
`PieSectorXY()`	elenco completo dei parametri	Mappatura parziale (le linee dal centro al bordo differiscono).
`RoundedRectXY()`	raggio per angolo	Solo raggio degli angoli uniforme.

Il modo in cui l’adapter espone queste differenze dipende dalla modalità rigorosa (vedi /integrations/tcpdf-compat/configuration/). Con la modalità rigorosa disattivata (l’impostazione predefinita retrocompatibile), queste chiamate degradano in silenzio. Con la modalità rigorosa attivata, ogni chiamata che ignora un parametro lancia TcpdfNotImplementedException, con l’elenco esatto dei parametri ignorati e un suggerimento di migrazione. La modalità rigorosa è uno strumento di audit, non un’impostazione di produzione.

La progettazione della modalità rigorosa segue il principio per cui un chiamante deve poter osservare quando la sua intenzione non è stata rispettata. OWASP ASVS 5.0 §16.5.3 afferma che un’applicazione dovrebbe fallire in modo controllato e sicuro e prevenire le condizioni di fail-open. La perdita silenziosa di parametri è una trappola per l’esperienza di sviluppo più che una vulnerabilità, ma vale lo stesso principio di fallimento esplicito. Il digest della clausola fissata si trova nel front-matter della pagina citations.

3. Metodi non implementati — corpi no-op

Quattro metodi esistono affinché il sorgente legacy compili, ma i loro corpi non fanno nulla. Con la modalità rigorosa attivata, tre di essi lanciano TcpdfNotImplementedException. Il quarto (Open()) è un no-op sicuro e deliberato che non lancia mai, perché rimuoverlo dal codice legacy è sempre sicuro.

Metodo TCPDF	Comportamento	Sostituzione
`setSignature()`	No-op (non memorizza nulla di utilizzabile). Lancia in modalità rigorosa.	La firma digitale richiede un’edizione commerciale di NextPDF. Usare l’API moderna delle firme con un value object `CertificateInfo` — vedi /integrations/tcpdf-compat/security-and-operations/.
`addEmptySignatureAppearance()`	No-op. Lancia in modalità rigorosa.	Stesso vincolo di edizione commerciale di `setSignature()`.
`endPage()`	No-op. Lancia in modalità rigorosa.	NextPDF gestisce automaticamente il ciclo di vita della pagina. Rimuovere la chiamata.
`Open()`	No-op sicuro. Non lancia mai.	NextPDF apre automaticamente il documento. Rimuovere la chiamata è sempre sicuro.

La firma non è disponibile nel motore core tramite questo adapter. L’adapter espone un punto di ingresso moderno per le firme che delega al motore; il supporto baseline delle firme è riservato a un’edizione commerciale. Questa documentazione non formula alcuna affermazione sui profili di firma con convalida a lungo termine o con marca temporale per alcuna edizione — vedi /integrations/tcpdf-compat/security-and-operations/ per la dichiarazione esatta e prudente.

4. Metodi non applicabili

Sette metodi TCPDF non hanno effetto sull’output PDF e sono esclusi intenzionalmente. Chiamarli non comporta rischi.

Metodo TCPDF	Perché è escluso
`setDocCreationTimestamp()` / `setDocModificationTimestamp()`	Lo stato è mantenuto sull’adapter ma non è collegato ai metadati XMP del documento. Non visibile nell’output.
`setSRGBmode()`	La gestione del colore di NextPDF è indipendente da questo flag.
`setPDFVersion()`	NextPDF seleziona la versione PDF dal proprio profilo di conformance/output; non esiste un setter diretto. L’adapter emette un avviso e prosegue.
`setDocInfoUnicode()`	NextPDF usa sempre Unicode; il flag è un no-op per progettazione.
`setDefaultMonospacedFont()`	Nessun equivalente nel motore; si applica invece lo stile HTML/CSS.
`setFontSubsetting()`	NextPDF esegue sempre il subsetting dei font incorporati; il flag è di fatto sempre attivo.

La versione PDF è fissata dal motore. L’output viene scritto come PDF 2.0 (ISO 32000-2). ISO 32000-2 §7.5.2 specifica che un writer conforme deve identificare la versione del documento — nell’intestazione del file o nella voce Version del catalogo — come 2.0. Specifica inoltre che la versione di un file non viene abbassata a una versione precedente al momento del salvataggio. Ciò è coerente con il comportamento dell’adapter: chiamate come setPDFVersion('1.4') non possono puntare a una versione PDF precedente tramite questo adapter. Il digest della clausola fissata si trova nel front-matter della pagina citations.

5. Metodi di drift dell’API moderna

Diciassette metodi del core NextPDF v5.1+ sono esposti sull’adapter (trait AdaptsDriftV51) affinché il codice che mescola l’API TCPDF con l’API moderna compili comunque. Questi non hanno equivalente in TCPDF 6.x. Esempi: getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode(). Considerarli API moderna, non parte del contratto di compatibilità TCPDF.

6. Indicazioni su deprecazione e sostituzione

Se il tuo codice chiama…	Stato	Fai invece così
`Error()`	Comportamento modificato (irrobustito)	Il `die()` di TCPDF è sostituito dal lancio di una `RuntimeException`. Racchiudere le chiamate rischiose in `try`/`catch`; non fare affidamento sulla terminazione del processo.
`setPDFVersion()`	Non applicabile	Rimuovere. L’output è sempre PDF 2.0.
`setUserRights()`	Deprecato in PDF 2.0	Rimuovere. La chiamata emette un avviso `E_USER_DEPRECATED` e viene ignorata.
`setSignature()`	Non implementato nel core	Migrare all’API moderna delle firme su un’edizione commerciale.
`Image(...)` con parametri extra	Ignorato-in-silenzio	Ridurre a file, x, y, w, h; aggiungere `Document::link()` per le immagini cliccabili.
`endPage()` / `Open()`	Non implementato / no-op	Rimuovere.

7. Passaggi per una migrazione sicura

Installare il pacchetto ed eseguire la suite esistente sull’adapter senza modifiche al codice — vedi /integrations/tcpdf-compat/install/ e /integrations/tcpdf-compat/quickstart/.
Abilitare la modalità rigorosa in un’esecuzione di audit dedicata (non in produzione): $pdf->setStrictMode(true);. Raccogliere ogni TcpdfNotImplementedException. Ciascuna indica i parametri esatti ignorati e un suggerimento di migrazione.
Per ogni punto di lancio, scegliere se eliminare il parametro ignorato oppure migrare quella chiamata all’API moderna tramite $pdf->getDocument().
Riallineare ogni test che fa asserzioni sui byte PDF esatti; fare invece asserzioni sul contenuto sottoposto a rendering o sulle proprietà strutturali.
Disattivare la modalità rigorosa e distribuire il percorso di codice sottoposto ad audit. Mantenere un job CI periodico in modalità rigorosa per intercettare le regressioni man mano che si procede con il refactoring.

Procedura completa con codice: /integrations/tcpdf-compat/migration/.

Vedi anche

docs/TCPDF_COVERAGE.md — matrice di copertura autorevole e verificata dai test (nel repository)
/integrations/tcpdf-compat/migration/ — strategia di migrazione end-to-end da TCPDF a NextPDF
/integrations/tcpdf-compat/configuration/ — modalità rigorosa e configurazione dell’adapter
/integrations/tcpdf-compat/security-and-operations/ — postura di cifratura e firma
/integrations/tcpdf-compat/integration/ — integrazione dell’adapter in un’applicazione
/integrations/tcpdf-compat/boot-and-discovery/ — registrazione dell’alias di classe ed esposizione della facade