Guida per sviluppatori alla compatibilità con TCPDF

In breve

L’adattatore di compatibilità è un livello per la migrazione. Deve rendere visibile il comportamento legacy, non mascherarlo. Usarlo per mantenere operativa un’applicazione mentre si spostano i percorsi di maggior valore verso le API native di NextPDF.

Usare questa guida quando si gestisce codice legacy basato su TCPDF, si aggiunge copertura all’adattatore o si pianifica una migrazione graduale alle API native di NextPDF.

Perimetro architetturale

Livello	Di competenza di	Responsabilità	Da non inserire qui
Applicazione legacy	Applicazione	Mantenere operative le chiamate esistenti in forma TCPDF durante la migrazione.	Nuove funzionalità PDF che dovrebbero usare le API native di NextPDF.
Shell dell’adattatore	nextpdf/compat-legacy	Esporre la classe in forma TCPDF e lo stato di compatibilità condiviso.	Famiglie di metodi estese o logica di conversione.
Trait per ambiti specifici	nextpdf/compat-legacy	Raggruppare le famiglie di metodi legacy: testo, font, immagini, sicurezza, moduli, pagine.	Criteri di output trasversali alle famiglie.
Classi bridge	nextpdf/compat-legacy	Convertire argomenti, destinazioni, colori, unità e formati legacy.	Comportamento specifico del dominio applicativo.
Motore principale	nextpdf/nextpdf	Produrre il documento nativo.	Garanzie di compatibilità legacy.

Ciclo di vita a runtime

Fase	Comportamento	Azione dello sviluppatore
Bootstrap	Il bootstrap legacy opzionale rende disponibili i nomi di compatibilità.	Usarlo solo nei punti in cui il codice legacy si aspetta i simboli TCPDF.
Costruzione	Gli argomenti del costruttore legacy vengono adattati alla configurazione del documento principale.	Mantenere stabili gli input del costruttore durante la migrazione.
Chiamata di metodo	I metodi supportati vengono mappati al comportamento di NextPDF tramite trait per ambiti specifici e bridge.	Verificare la copertura dei metodi prima di dare per scontata la parità.
Funzionalità non supportata	Il comportamento non supportato solleva eccezioni di compatibilità esplicite.	Sostituire la chiamata o isolarla dietro un livello applicativo.
Output	Il bridge di output mappa il comportamento delle destinazioni legacy sull’output di NextPDF.	Convalidare i nomi dei file e le radici di archiviazione.

Inventario di migrazione

Iniziare raccogliendo ogni chiamata di metodo TCPDF usata dall’applicazione. Classificare ogni chiamata prima di modificarne il comportamento.

Classificazione	Significato	Azione
Metodo dell’adattatore supportato	Il metodo è documentato come supportato ed è coperto da test.	Mantenerlo temporaneamente, poi migrarlo quando si interviene su quell’area.
Metodo dell’adattatore con supporto parziale	Il metodo esiste, ma il comportamento non corrisponde del tutto a TCPDF legacy.	Aggiungere test con fixture e convalidare manualmente l’output.
Metodo esplicitamente non supportato	L’adattatore genera un’eccezione di compatibilità.	Sostituirlo con NextPDF nativo o rimuovere la funzionalità.
Wrapper specifico del dominio applicativo	L’applicazione incapsula già le chiamate TCPDF in un wrapper.	Migrare prima la logica interna del wrapper.
Chiamata sensibile alla conformità	Firma, cifratura, tagging, PDF/A, accessibilità o flusso di fatturazione.	Migrare alle API native di NextPDF con una verifica dedicata.

Modello di contributo all’adattatore

Aggiungere il supporto di compatibilità nella più piccola famiglia di metodi che possiede il comportamento.

Tipo di modifica	Dove implementare	Test richiesto
Metodo per l’output di testo	Concerns\AdaptsTextOutput o concern relativo ai font.	Fixture legacy e asserzione sull’output nativo.
Metodo per pagine o margini	Concern di pagina, posizionamento o margine.	Test di conversione delle coordinate e dello stato della pagina.
Metodo per immagini o disegno	Concern di immagine, disegno, colore o gradiente.	Convalida dell’input e test dell’output visivo/strutturale.
Destinazione di output	OutputBridge.	Test di mappatura delle destinazioni e dei percorsi non sicuri.
Funzionalità non supportata	Factory di eccezioni o tabella di copertura dei metodi.	Test del tipo di eccezione e del messaggio.

Non aggiungere un metodo di grandi dimensioni direttamente nella shell dell’adattatore quando un trait per ambiti specifici possiede quella famiglia.

Modello di migrazione nativa

Usare l’adattatore per stabilizzare, quindi spostare i flussi di lavoro stabili sulle API native.

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

Considerare la migrazione come una sequenza di piccole modifiche comportamentali. Una pagina può continuare a usare l’adattatore mentre una sezione ad alto rischio passa alle API native.

Punti di estensione

Punto di estensione	Da usare per	Vincolo
AdaptationConfig	Controllare il comportamento dell’adattatore durante la migrazione.	Mantenere i valori predefiniti revisionati ed espliciti.
Trait per ambiti specifici	Raggruppare famiglie di metodi come testo, moduli, immagini o sicurezza.	Aggiungere i metodi al concern appropriato, non alla shell dell’adattatore.
Classi bridge	Convertire le forme degli argomenti legacy in valori del motore principale.	Mantenere il comportamento del bridge coperto dai test di migrazione.
CompatAdapterInterface	Astrazione a livello di adattatore per gli strumenti.	Non usarla al posto dei contratti nativi del motore principale nel codice nuovo.
Tabella di copertura dei metodi	Registro del supporto rivolto agli sviluppatori.	Aggiornare quando lo stato di supporto cambia.

Flusso di lavoro di migrazione

1. Installare l’adattatore ed eseguire la suite di test legacy senza modifiche.
2. Aprire la copertura dei metodi e classificare ogni metodo chiamato.
3. Sostituire prima i metodi non supportati.
4. Spostare i percorsi a volume elevato o sensibili alla conformità sulle API native del motore principale.
5. Aggiungere copertura tramite fixture per ogni famiglia di metodi migrata.
6. Rimuovere gli alias di bootstrap quando nessun punto di ingresso dell’applicazione dipende più da essi.

Gestione degli errori

Errore	Dove va gestito	Risposta consigliata
Metodo non supportato	Eccezione dell’adattatore.	Sostituire la chiamata o isolarla dietro un adattatore applicativo.
Parità parziale del layout	Test di migrazione e revisione visiva.	Documentare la differenza accettata prima del rilascio.
Destinazione di output non sicura	OutputBridge e criteri di archiviazione dell’applicazione.	Rifiutare i percorsi non sicuri e preferire le API di output native.
Disallineamento delle funzionalità di sicurezza	Piano di migrazione nativa.	Non rilasciare comportamenti basati solo sulla compatibilità per gli output regolamentati.
Collisione degli alias di bootstrap	Bootstrap dell’applicazione.	Rimuovere gli alias globali o limitarne l’ambito ai punti di ingresso legacy.

Valori predefiniti sicuri

Ambito	Predefinito	Quando eseguire l’override
Metodi non supportati	Genera un’eccezione esplicita.	Non indebolire questo comportamento in produzione.
Valori predefiniti legacy	Centralizzati in LegacyDefaults.	Eseguire l’override solo per un comportamento di migrazione noto.
Mappatura dell’output	Passa attraverso OutputBridge.	Usare le API di output native dopo la migrazione.
Fonte di copertura	Pagina di copertura dei metodi e test.	Rieseguire le verifiche di copertura dopo ogni aggiornamento dell’adattatore.
Modalità strict	Mantenerla abilitata durante gli audit di migrazione.	Disabilitarla solo per una finestra di compatibilità legacy documentata.

Elenco di controllo dei test

• Mantenere una fixture legacy per ogni famiglia di metodi migrata.
• Aggiungere un test NextPDF nativo prima di sostituire un metodo legacy.
• Verificare che i metodi non supportati generino l’eccezione documentata.
• Confrontare la struttura dell’output quando l’uguaglianza esatta a livello di byte non è un obiettivo realistico della migrazione.
• Eseguire le verifiche di copertura dei metodi dopo l’aggiunta o la modifica di metodi dell’adattatore.
• Aggiungere test sui percorsi di archiviazione per ogni destinazione di output utilizzata dal codice legacy.