Migrare a NextPDF

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 e l’aggregatore la pubblica in questo sito. 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 consiste in una modifica del codice e nella 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
mPDF	mPDF → core di NextPDF	Riscrittura dell’API	nextpdf (core)	Guida mPDF
FPDF	FPDF → core di NextPDF	Riscrittura dell’API	nextpdf (core)	Guida FPDF
TCPDF 6.x	TCPDF → NextPDF tramite l’adattatore compat-legacy	Drop-in-then-migrate	nextpdf-compat-tcpdf repository, pacchetto nextpdf/compat-legacy	Guida TCPDF

Le guide dompdf, mpdf e fpdf 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 — 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 — 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.
• FPDF → NextPDF — per codebase che usano direttamente l’API di disegno di FPDF. Mappa AddPage/SetFont/Cell/MultiCell/Write/Text/Image/Output e il modello a cursore manuale sull’API core e documenta la differenza nelle unità di misura. Non esiste alcuno shim della classe FPDF.
• TCPDF → NextPDF (compat-legacy) — 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.

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).