Guide alla migrazione

Le ricette e le guide compaiono qui man mano che i repository upstream vengono rilasciati. Questa pagina è un indice di instradamento per i contenuti redatti nei repository di origine (nextpdf, nextpdf-Laravel, nextpdf-Symfony e gli altri pacchetti dell'ecosistema). Per la documentazione attualmente disponibile, vedere Insider_ (35 articoli, tutte le 17 lingue) oppure Scegli un'integrazione.

Guide alla migrazione

NextPDF è un motore PDF 2.0 per PHP. Se già si generano PDF con un’altra libreria, una guida alla migrazione mappa l’API di quella libreria su NextPDF e documenta le differenze comportamentali che si incontrano. Questa pagina è l’indice cross-repository: indica da quale libreria parte ogni migrazione, quale repository possiede ogni guida e l’unico modello condiviso da tutte le guide.

Poiché questa pagina è un indice, non formula alcuna affermazione comportamentale su nessuna guida. Ogni guida appartiene al proprio repository. L’aggregatore la incorpora in questo sito e, finché una guida non viene pubblicata, il collegamento sottostante punta a un segnaposto. Ogni affermazione comportamentale risiede nella guida stessa, supportata da un test interno al repository o da una clausola ISO 32000-2 / CSS WG fissata come riferimento — non qui.

L’unico modello di migrazione

Ogni guida alla migrazione di NextPDF condivide un unico modello onesto, ed è bene leggere ciascuna guida tenendolo presente:

• Compatibile, non identica a livello di byte. NextPDF e la libreria che si sta abbandonando sono implementazioni indipendenti. Un documento migrato è funzionalmente equivalente nello scopo, non identico a livello di pixel o di byte. Nessuna guida promette una sostituzione drop-in o una compatibilità al 100%.
• La copertura è un conteggio misurato, non un’asserzione. Quando una guida indica un valore di copertura (per esempio l’adattatore TCPDF), quel valore è una metrica di completezza funzionale ricavata da una matrice interna al repository, nel senso della clausola 43 di ISO/IEC 25023 — un conteggio misurato dei metodi coperti, non una garanzia generalizzata.
• Ogni guida dichiara apertamente le proprie differenze comportamentali. Ogni guida include una tabella esplicita delle differenze e una sezione «non supportato / nessun equivalente diretto». Una differenza è una proprietà documentata del motore, non un bug.
• Un cambio di renderer richiede una nuova revisione. La migrazione è una modifica del codice più la ridefinizione della baseline dell’output. Ogni guida descrive come testare la migrazione; l’accettazione visiva avviene documento per documento ed è responsabilità dell’integratore.

Le forme di migrazione

Le guide si suddividono in due forme. La forma indica quanto codice cambia.

• Le migrazioni con riscrittura dell’API non prevedono alcuno shim di compatibilità: ogni punto di chiamata viene riscritto utilizzando la mappatura dei verbi e la mappa delle opzioni della guida. Le migrazioni dalle librerie da HTML a PDF (dompdf, mpdf) seguono questa forma — puntano direttamente alla pipeline Html di NextPDF.
• Le migrazioni drop-in-then-migrate forniscono un adattatore quasi compatibile a livello di sorgente, quindi il passaggio iniziale è una sostituzione minima delle dipendenze. Da lì si migrano in modo incrementale i punti di chiamata verso l’API moderna, quindi si dismette l’adattatore. La migrazione di TCPDF segue questa forma, tramite l’adattatore nextpdf/compat-legacy.

Riferimento alle guide e ai repository proprietari

Ogni guida elencata di seguito risiede nella directory docs/public/ del repository proprietario e l’aggregatore la incorpora in questo sito. Il repository proprietario fa autorità per le affermazioni comportamentali di quella guida; questo indice registra soltanto l’instradamento.

Da	Guida	Forma	Repository proprietario	Pagina
Dompdf	Dompdf → pipeline Html di NextPDF	Riscrittura dell’API	nextpdf (core)	Guida Dompdf dompdf (pianificata upstream)
mPDF	mPDF → core di NextPDF	Riscrittura dell’API	nextpdf (core)	Guida mPDF mpdf (pianificata upstream)
TCPDF 6.x	TCPDF → NextPDF tramite l’adattatore compat-legacy	Drop-in-then-migrate	nextpdf-compat-tcpdf repository, pacchetto nextpdf/compat-legacy	Guida TCPDF tcpdf-compat (pianificata upstream)

Le guide dompdf e mpdf risiedono nel repository core perché puntano alle API del motore core e sono supportate dagli examples/ del core. La guida tcpdf-compat risiede nel repository compat-tcpdf perché il pacchetto nextpdf/compat-legacy è responsabile della superficie comportamentale di TCPDF e dei test dell’adattatore che supportano la guida. Questo indice risiede nativamente nei docs perché copre più repository e non formula alcuna affermazione comportamentale su alcuno di essi.

A cosa serve ogni guida

• Dompdf → NextPDF (dompdf (pianificata a monte)) — per codebase che usano dompdf/dompdf lato server. Mappa loadHtml/render/output e le chiavi Options sulla pipeline Html di NextPDF e rimanda le aspettative sulle funzionalità CSS alla matrice di supporto CSS solo-Verificato. Non esiste alcuno shim della classe Dompdf; ogni punto di chiamata viene riscritto.
• mPDF → NextPDF (mpdf (pianificata a monte)) — per codebase che usano mpdf/mpdf. Mappa WriteHTML/Output/AddPage e l’array di configurazione del costruttore sull’API core, con una differenza nella gestione dei font: NextPDF risolve attraverso un’unica directory di font più la corrispondenza CSS e applica sempre il subsetting. Non esiste alcuno shim della classe Mpdf.
• TCPDF → NextPDF (compat-legacy) (tcpdf-compat (pianificata a monte)) — per codebase TCPDF 6.x che desiderano la modifica iniziale più contenuta. Installare l’adattatore, verificare la superficie reale in modalità strict rispetto alla matrice di copertura interna al repository, migrare i punti di chiamata al di fuori dell’adattatore, quindi aggiungere una struttura con tag PDF/UA-2 — una capacità che TCPDF non ha mai avuto. L’adattatore è un’impalcatura, non la destinazione, e non una garanzia drop-in.

Come si risolvono i collegamenti alle guide

Ogni segnaposto [[…]] qui sopra è un riferimento in avanti a una pagina che risiede nel repository proprietario in docs/public/migration/, e l’aggregatore incorpora quella pagina in questo sito. Gli slug di destinazione seguono una convenzione unica:

/migration/<source>/

Il token <source> è il nome breve della libreria da cui si sta migrando: uno tra dompdf, mpdf o tcpdf-compat, come indicato nella tabella di riferimento delle guide qui sopra. Finché una pagina di destinazione non viene aggregata, il suo collegamento è un segnaposto e non viene risolto. Questo indice non formula alcuna affermazione comportamentale su nessuna guida di destinazione; registra soltanto l’instradamento e il modello di migrazione condiviso.

Vedere anche

• Matrice di supporto CSS — l’autorità solo-Verificato a cui le guide dompdf e mpdf rimandano le aspettative sulle funzionalità CSS.
• Ricettario di integrazione — l’indice cross-repository per i pacchetti di integrazione dell’ecosistema (una questione diversa: collegare il motore, non migrare verso di esso).