Migrazione da mPDF a NextPDF

In sintesi

Questa guida accompagna la migrazione di un codebase basato su mPDF al core di NextPDF. Il verbo centrale di mPDF è WriteHTML(), che corrisponde direttamente a Document::writeHtml(). Il lavoro principale consiste nella mappa dell’array di configurazione del costruttore (mPDF configura tutto tramite un singolo array associativo passato a new Mpdf([...])) e nel delta nella gestione dei font. NextPDF e mPDF sono motori indipendenti, quindi un documento migrato è compatibile con l’output di mPDF, non identico byte per byte. Questa guida copre la mappa dei verbi, la mappa dell’array di configurazione, il delta dei font, il delta di supporto CSS, le differenze comportamentali e una sequenza sicura.

La matrice di supporto CSS è il riferimento autorevole per determinare quali funzionalità HTML/CSS sono Verificate. Questa guida descrive il comportamento; non afferma l’equivalenza visiva con mPDF.

Installazione

composer require nextpdf/core:^3

Mantenere mpdf/mpdf installato per tutta la transizione. Rimuoverlo dopo il passaggio finale (vedere sequenza di migrazione sicura).

Panoramica concettuale

L’oggetto Mpdf di mPDF è un’unica grande facciata. Un array del costruttore lo configura e WriteHTML() più i verbi di paginazione (AddPage, SetHTMLHeader, SetHTMLFooter) ne governano il flusso. NextPDF separa la configurazione nel value object immutabile NextPDF\Core\Config e gestisce il contenuto con Document::writeHtml(). Non esiste alcuna stringa di «mode» del costruttore. NextPDF analizza l’HTML passato, quindi emette il documento con save(), output() o getPdfData().

Font: mPDF include una directory dei font più una mappa fontdata e un set di fallback «core fonts». NextPDF risolve i font tramite un’unica directory dei font più la corrispondenza CSS font-family e esegue sempre il subset dei font incorporati (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7). Il matching/fallback dei font è specifico del motore (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13), quindi la sostituzione dei glifi può differire. Questo è il principale delta visibile, trattato nel delta nella gestione dei font.

Superficie API

L’API HTML di NextPDF è il riferimento del modulo Html. I principali punti di ingresso sono: Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::addPage(), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string e il value object NextPDF\Core\Config.

Mappatura dei verbi API

I nomi dei metodi pubblici di mPDF riportati di seguito sono confermati rispetto al repository pubblico upstream (mpdf/mpdf, development) — vedere il sidecar di provenienza _source-sidecar-upstream-api.md presente nel repository. Nessun testo della documentazione upstream è riprodotto.

mPDF	NextPDF	Note
`new Mpdf([...])`	`Document::createStandalone($config)`	L’array di configurazione di mPDF corrisponde a `NextPDF\Core\Config`; vedere mappa di configurazione. Usare `DocumentFactory` per i worker a lunga durata.
`$mpdf->WriteHTML($html)`	`$doc->writeHtml($html)`	Mappatura diretta. Il secondo argomento `$mode` di mPDF (documento completo vs. solo CSS vs. elemento) non ha alcun corrispondente in NextPDF — passare HTML completo.
`$mpdf->WriteFixedPosHTML(...)`	`$doc->writeHtmlCell(...)`	Regione HTML posizionata e dimensionata; mappare gli argomenti x/y/width/height.
`$mpdf->AddPage(...)`	`$doc->addPage()`	Le sostituzioni per singola chiamata di orientation/format/margine di mPDF non sono argomenti in NextPDF; modificare invece il modello del documento tra una chiamata e l’altra.
`$mpdf->SetHTMLHeader($html)` / `SetHTMLFooter($html)`	header/footer tramite la Layout API	Le intestazioni HTML ricorrenti di mPDF corrispondono al meccanismo di NextPDF per header/footer, non a HTML inline all’inizio del corpo.
`$mpdf->Output($name, $dest)`	`$doc->output($name, OutputDestination::…)`	I caratteri di destinazione di mPDF (`I`/`D`/`F`/`S`) si mappano sull’enum `OutputDestination` (`Inline`/`Download`/file tramite `save()`/string tramite `getPdfData()`).
`$mpdf->Output('','S')`	`$doc->getPdfData()`	Restituisce i byte.
`$mpdf->Output($path,'F')`	`$doc->save($path)`	Scrive su un percorso di file.
`$mpdf->SetTitle($t)`	`$doc->setTitle($t)`	Finisce nel dizionario informativo / XMP §14 di ISO 32000-2 (`iso32000_2_sec14#x1.x5.p5`).
`$mpdf->SetProtection($perms,...)`	`$doc->setEncryption(...)` (Security API)	I permessi sono cooperativi con il lettore, non un controllo di accesso — vedere Note di sicurezza.

Esempio di codice — Avvio rapido

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

// mPDF:
//   $mpdf = new \Mpdf\Mpdf();
//   $mpdf->WriteHTML('<h1>Invoice</h1>');
//   $mpdf->Output('out.pdf', \Mpdf\Output\Destination::FILE);

// NextPDF — default page is A4 portrait:
$doc = Document::createStandalone();
$doc->setTitle('Invoice');
$doc->addPage();
$doc->writeHtml('<h1>Invoice</h1>');
$doc->save(__DIR__ . '/out.pdf');

echo "Wrote out.pdf\n";

Esempio di codice — Produzione

Questo esempio è allineato a examples/04-text-and-fonts.php, il supporto eseguibile dei concetti di gestione dei font in questa guida. Usa una dimensione di pagina esplicita, margini e un corpo di contenuto che mette alla prova la selezione dei font.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

// Equivalent of: new Mpdf(['format'=>'A4','margin_left'=>20, ...]).
// Margin constructor order is (top, right, bottom, left) — NOT L,R,T,B.
$config = new Config(
    pageSize: new PageSize(595.276, 841.890, 'A4'),
    margins: new Margin(16.0, 20.0, 16.0, 20.0), // top,right,bottom,left in points
    fontsDirectory: __DIR__ . '/fonts',
);

$doc = Document::createStandalone($config);
$doc->setTitle('Quarterly Report');
$doc->addPage();

$html = <<<'HTML'
<h1 style="font-family:'DejaVu Sans';color:#1E3A8A;">Quarterly Report</h1>
<p>Body text resolves through CSS font-family matching against the configured
fonts directory. mPDF's fontdata map has no direct analogue — register the
family via CSS and the fonts directory instead.</p>
HTML;

$doc->writeHtml($html);

// Equivalent of $mpdf->Output('report.pdf', Destination::DOWNLOAD):
$doc->output('report.pdf', OutputDestination::Download);

Casi limite e insidie

Argomento $mode su WriteHTML. WriteHTML($html, $mode) di mPDF (2 = solo CSS, 1 = elemento) non ha equivalente. Inserire il CSS inline nell’HTML che si passa; non esiste una sequenza “scrivi il CSS poi scrivi il corpo”.
Sostituzioni per AddPage. mPDF consente a AddPage() di cambiare format/orientation a metà documento tramite argomenti. In NextPDF, addPage() non accetta tali argomenti; le modifiche di dimensione si modellano nel documento, non tramite la chiamata di pagina.
HTML di intestazione/piè di pagina. Le intestazioni ricorrenti di mPDF sono frammenti HTML registrati separatamente; non incollarle nel corpo. Mapparle sul meccanismo di NextPDF per header/footer.
Nomi dei font. mPDF normalizza i nomi dei font tramite la propria tabella fontdata/core-font. NextPDF confronta il font-family CSS con la directory dei font; un alias mPDF che veniva risolto silenziosamente potrebbe richiedere una dichiarazione @font-face/family esplicita.
Caratteri di destinazione. 'I'/'D'/'F'/'S' non sono accettati; usare l’enum OutputDestination oppure save()/getPdfData().

Prestazioni

writeHtml() è a passaggio singolo (ADR-001); la memoria di picco segue la dimensione del documento, non un DOM mantenuto in memoria. Budget per l’esempio di questa guida: wall_ms: 2000, peak_mb: 128. Per i documenti lunghi, suddividere il contenuto in pagine con addPage() anziché in un’unica stringa enorme. È lo stesso consiglio che si applica al chunking $mode di mPDF, ma espresso attraverso il modello di pagina.

Note di sicurezza

I permessi sono cooperativi con il lettore. SetProtection() → setEncryption() fornisce riservatezza, non controllo di accesso: i bit dei permessi ISO dipendono da un lettore cooperante. Non presentare la cifratura agli utenti come controllo di accesso.
Metadati. SetTitle() e le informazioni del documento finiscono nel dizionario informativo / XMP §14 di ISO 32000-2 (iso32000_2_sec14#x1.x5.p5); non memorizzarvi mai segreti.
NextPDF non esegue script all’interno del documento; nessuna direttiva mPDF lo abilita in questo contesto.

Conformità

Dichiarazione	Specifica	Clausola
I font sono scritti come programmi font embedded/subset.	ISO 32000-2	§9
Il format/margins della pagina si mappano sul riquadro di delimitazione della pagina.	ISO 32000-2	§7
I metadati di titolo / protezione finiscono nel dizionario informativo / XMP.	ISO 32000-2	§14
La corrispondenza / fallback dei font è specifica del motore.	CSS Fonts 4	§5.5

NextPDF produce contenuti ISO 32000-2; non afferma l’identità visiva con mPDF. Un cambio di renderer richiede una nuova revisione dell’output.

Contesto commerciale

Non applicabile. Il core copre il percorso di migrazione da mPDF descritto qui.

Vedere anche

Dettagli di migrazione (sezioni richieste R6)

A chi è destinato

Team che usano mpdf/mpdf per la conversione HTML-in-PDF lato server. Se la superficie usata è new Mpdf([...]) + WriteHTML + Output (+ header/footer opzionale), la mappatura dei verbi e la mappa di configurazione coprono il caso.

Ambito

In ambito: l’array di configurazione del costruttore Mpdf, WriteHTML/Output/AddPage, headers/footers, font, protezione, metadati. Fuori ambito: le classi interne di mPDF e le funzionalità di supporto QR/barcode/filigrana (mapparle sui moduli NextPDF corrispondenti — Barcode, Graphics — non trattati qui).

Mappa di compatibilità

Compatibilità comportamentale, non uno shim drop-in: non esiste alcuno shim della classe Mpdf. Ogni punto di chiamata va riscritto. Le aspettative sulle funzionalità CSS sono definite dalle righe Verificate della matrice di supporto CSS.

Mappa dell’array di configurazione del costruttore

Le chiavi di configurazione di mPDF sono confermate rispetto al repository pubblico upstream (mpdf/mpdf, development). Nessun testo della documentazione upstream è riprodotto.

Chiave di configurazione mPDF	NextPDF	Note
`mode`	(nessun equivalente)	La stringa di mode di mPDF (`'utf-8'`, `'c'`, `'+aCJK'`, …) seleziona il comportamento font/script. NextPDF è sempre Unicode; il CJK è gestito dalla selezione dei font, non da una mode. Eliminare la chiave.
`format`	`Config->pageSize` (VO `PageSize`)	I formati con nome diventano dimensioni esplicite in punti; gli array `[w,h]` si mappano su un `PageSize`.
`orientation`	scambiare width/height in `PageSize`	Nessun flag di orientamento; orizzontale = width > height.
`default_font_size`	Dimensione CSS del font di base	Da impostare tramite il foglio di stile di base, non tramite una chiave del costruttore.
`default_font`	CSS `font-family` / font registrato	Impostare la famiglia predefinita tramite CSS / registrazione dei font.
`margin_left` / `margin_right` / `margin_top` / `margin_bottom`	`Config->margins` (VO `Margin`) in punti	Un unico value object `Margin`; l’ordine del suo costruttore è `Margin(top, right, bottom, left)` (verificare rispetto a `src/ValueObjects/Margin.php`), non l’ordine delle chiavi di mPDF.
`margin_header` / `margin_footer`	offset di header/footer tramite la Layout API	Mapparli sulla configurazione di NextPDF per header/footer, non su chiavi del costruttore.

Delta nella gestione dei font

Directory unica dei font. L’elenco delle directory dei font di mPDF + la mappa fontdata + il fallback dei core-font si riducono a Config->fontsDirectory più la corrispondenza CSS font-family.
Subset sempre attivo. NextPDF esegue sempre il subset dei font incorporati (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7); i flag di subset di mPDF non hanno equivalente e non sono necessari.
La corrispondenza è specifica del motore. Il matching/fallback dei font differisce a seconda del motore (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13); un alias di font mPDF potrebbe richiedere un @font-face esplicito o il nome esatto della famiglia. Ricalibrare il rendering dei glifi dopo la migrazione; le differenze di sostituzione sono attese, non difetti.

Differenze comportamentali

Sostituzione dei font (vedere sopra) — il principale delta visibile.
Nessun $mode su WriteHTML — passare HTML completo con CSS inline.
Nessuna sostituzione di formato per AddPage — le modifiche di dimensione si modellano nel documento.
I permessi sono cooperativi col lettore (vedere Note di sicurezza).
Motore di layout indipendente — l’andata a capo / la paginazione differiscono su contenuti densi; ricalibrare i diff visivi.

Queste sono differenze comportamentali documentate, non difetti di uno dei due motori.

Non supportato / nessun equivalente diretto

Stringa mode del costruttore — non modellata (sempre Unicode).
Argomenti format/orientation/margine per AddPage() — non sono argomenti in NextPDF.
Mappa fontdata di mPDF — sostituita da directory dei font + corrispondenza CSS.
I caratteri di destinazione 'I'/'D'/'F'/'S' di mPDF — sostituiti dall’enum OutputDestination + save()/getPdfData().

Sequenza di migrazione sicura

Aggiungere nextpdf/core insieme a mpdf/mpdf (mantenere mPDF per ora).
Scegliere un documento a basso rischio. Convertire new Mpdf([...]) tramite la mappa di configurazione e WriteHTML/Output tramite la mappa dei verbi.
Registrare i font usati dal documento in Config->fontsDirectory e aggiungere dichiarazioni esplicite @font-face/family per ogni alias mPDF.
Generare entrambi i PDF per lo stesso input; eseguire un diff visivo. Le differenze (sostituzione dei font, a capo) sono attese per motori indipendenti — accettarle documento per documento.
Mappare qualsiasi HTML di header/footer sul meccanismo di NextPDF per header/footer.
Ripetere documento per documento, partendo da quelli a rischio più basso; mantenere mPDF installato fino all’ultimo passaggio.
Rimuovere mpdf/mpdf da composer.json dopo il passaggio finale.

Testare la migrazione

Acquisire uno snapshot dell’output mPDF di documenti rappresentativi prima di modificare il codice (input golden; i byte differiranno).
Per ogni documento migrato, eseguire la verifica tramite il proprio controllo di accettazione (diff visivo + estrazione del testo). Il comportamento font/HTML di NextPDF è esercitato da examples/04-text-and-fonts.php ed examples/08-html-basic.php più le suite Html/Font del core in tests/. L’accettazione della migrazione è specifica del documento e resta responsabilità del progetto.
Aggiungere un test di regressione per ogni documento migrato.

Evidenze / tracciabilità

Ogni affermazione comportamentale su NextPDF in questa pagina è supportata da un test, un esempio, una firma del sorgente o un ADR presenti nel repository — oppure, quando riguarda una proprietà del formato PDF, dalle clausole ISO 32000-2 / CSS fissate dal RAG nelle citations: del front-matter e dalla tabella Conformità. Il comportamento di mPDF è descritto solo come «motore indipendente — attendersi differenze documentate»; non si rivendica alcuna parità che un artefatto nel repository non dimostri.

Affermazione comportamentale su NextPDF	Evidenza nel repository (percorso)
`WriteHTML()` si mappa direttamente su `Document::writeHtml(string $html): static`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtml()`); `examples/08-html-basic.php`.
`WriteFixedPosHTML(...)` si mappa su `writeHtmlCell(...)`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtmlCell()`).
`createStandalone()` ha come pagina predefinita A4 verticale (`595.276 × 841.890 pt`).	`src/Core/Config.php` (`PageSize` predefinito); `tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php`.
`Margin` ha l’ordine del costruttore `(top, right, bottom, left)`.	`src/ValueObjects/Margin.php` (ordine delle proprietà promosse).
La destinazione dell’output è l’enum `NextPDF\Contracts\OutputDestination`; `'I'/'D'/'F'/'S'` non sono accettati.	`src/Contracts/OutputDestination.php` (casi `Inline`/`Download`/`File`/`String`); `tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php`.
`Output('','S')` → `getPdfData()`; `Output($path,'F')` → `save($path)`.	`src/Core/Concerns/HasOutput.php` (`getPdfData()`, `save()`, `output()`).
`SetProtection()` si mappa su `setEncryption(...)`; i permessi sono cooperativi col lettore.	`src/Core/Concerns/HasSecurity.php` (`setEncryption()`); ISO 32000-2 §14 (`citations:` del front-matter).
`SetTitle()` → `setTitle()`; i metadati finiscono nel dizionario informativo / XMP.	`src/Core/Concerns/HasMetadata.php` (`setTitle()`); `tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php`; ISO 32000-2 §14 (`citations:` del front-matter).
I font sono sempre incorporati come programmi in subset.	`tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php`; `examples/04-text-and-fonts.php`; ISO 32000-2 §9 (`citations:` del front-matter).
La corrispondenza / fallback dei font è specifica del motore (delta di sostituzione).	CSS Fonts 4 §5.5 (`citations:` del front-matter + Conformità).
`writeHtml()` è a passaggio singolo; la memoria di picco segue la dimensione del documento.	`docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md`.

Rollback

Entrambi i pacchetti restano installati fino al passaggio finale, quindi il rollback per singolo punto di chiamata consiste nel riportare quel punto di chiamata al percorso mPDF. Dopo il passaggio finale, il rollback consiste nel ripristinare mpdf/mpdf e il codice precedente dal controllo di versione. Non è prevista alcuna migrazione di dati.

Considerazioni sulle prestazioni

Vedere Prestazioni. Il modello a passaggio singolo elimina il costo del buffer mantenuto in memoria da mPDF. Il nuovo costo per documento è la risoluzione anticipata dei font (passo 3), che è memorizzabile in cache tramite la directory dei font.

Insidie comuni

Mantenere la chiave mode aspettandosi che determini il comportamento CJK (viene eliminata; il CJK è selezione dei font).
Passare WriteHTML($html, 2) (modalità solo CSS) — inserire invece il CSS inline.
Incollare l’HTML di header/footer nel corpo.
Aspettarsi lo stesso font per un alias mPDF senza una famiglia esplicita.
Aspettarsi un output byte/pixel-identical (motori indipendenti — questa guida non rivendica mai un drop-in o la compatibilità al 100%).
Trattare la matrice di supporto CSS come consultiva — è il riferimento autorevole sulle funzionalità Verificate.