Migracja z mPDF do NextPDF

W skrócie

Ten przewodnik pomaga przenieść bazę kodu opartą na mPDF do rdzenia NextPDF. W mPDF główną metodą przekazywania treści jest WriteHTML(), która odwzorowuje się bezpośrednio na Document::writeHtml(). Większość pracy polega na odwzorowaniu tablicy konfiguracyjnej konstruktora (mPDF konfiguruje wszystko za pomocą jednej tablicy asocjacyjnej przekazywanej do new Mpdf([...])) oraz na uwzględnieniu różnic w obsłudze czcionek. NextPDF i mPDF to niezależne silniki, więc zmigrowany dokument jest zgodny z wynikiem mPDF, a nie identyczny z nim bajt po bajcie. Ten przewodnik obejmuje odwzorowanie czasowników API, odwzorowanie tablicy konfiguracyjnej, różnice w obsłudze czcionek, różnice w obsłudze CSS, różnice w zachowaniu oraz bezpieczną sekwencję.

Macierz obsługi CSS określa, które funkcje HTML i CSS zostały zweryfikowane. Ten przewodnik opisuje zachowanie, ale nie gwarantuje wizualnej równoważności z mPDF.

Instalacja

composer require nextpdf/core:^3

Podczas migracji pozostaw zainstalowany pakiet mpdf/mpdf. Usuń go dopiero po ostatecznym przełączeniu (zobacz bezpieczną sekwencję migracji).

Przegląd koncepcyjny

Obiekt Mpdf w mPDF łączy konfigurację i renderowanie w jednym interfejsie. Do konfiguracji służy tablica konstruktora, a sterowanie odbywa się przez WriteHTML() oraz czasowniki stronicowania (AddPage, SetHTMLHeader, SetHTMLFooter). NextPDF wydziela konfigurację do niezmiennego obiektu wartości NextPDF\Core\Config i zapisuje treść za pomocą Document::writeHtml(). Nie ma ciągu „trybu” konstruktora. NextPDF analizuje przekazany kod HTML, a następnie emituje dokument za pomocą save(), output() lub getPdfData().

Czcionki: mPDF jest dostarczany z katalogiem czcionek, mapą fontdata oraz zapasowym zestawem „core fonts”. NextPDF rozpoznaje czcionki z jednego katalogu czcionek oraz przez dopasowanie CSS font-family i zawsze tworzy podzbiory osadzonych czcionek (Międzynarodowa Organizacja Normalizacyjna (ISO) 32000-2 §9, iso32000_2_sec9#x1.x45.p7). Dopasowanie czcionek i mechanizm zapasowy zależą od silnika (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13), więc podstawianie glifów może się różnić. To główna widoczna różnica, omówiona w sekcji różnica w obsłudze czcionek.

Powierzchnia API

Interfejs API HTML NextPDF opisano w module Html. Główne punkty wejścia to Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::addPage(), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string oraz obiekt wartości NextPDF\Core\Config.

Odwzorowanie czasowników API

Poniższe nazwy publicznych metod mPDF potwierdzono względem publicznego repozytorium upstream (mpdf/mpdf, development); zobacz dołączony do repozytorium plik proweniencyjny _source-sidecar-upstream-api.md. Nie reprodukowano żadnego tekstu dokumentacji upstream.

mPDF	NextPDF	Uwagi
`new Mpdf([...])`	`Document::createStandalone($config)`	Tablica konfiguracyjna mPDF odwzorowuje się na `NextPDF\Core\Config`; zobacz odwzorowanie konfiguracji. W długotrwałych procesach roboczych użyj `DocumentFactory`.
`$mpdf->WriteHTML($html)`	`$doc->writeHtml($html)`	Bezpośrednie odwzorowanie. Drugi argument `$mode` w mPDF (pełny dokument, tylko CSS albo element) nie ma odpowiednika w NextPDF; przekaż kompletny kod HTML.
`$mpdf->WriteFixedPosHTML(...)`	`$doc->writeHtmlCell(...)`	Pozycjonowany obszar HTML o określonych wymiarach; odwzoruj argumenty x/y/szerokość/wysokość.
`$mpdf->AddPage(...)`	`$doc->addPage()`	NextPDF nie przyjmuje jako argumentów nadpisań orientation/format/marginesu charakterystycznych dla pojedynczego wywołania mPDF; zamiast tego zmieniaj model dokumentu między wywołaniami.
`$mpdf->SetHTMLHeader($html)` / `SetHTMLFooter($html)`	header/footer za pomocą interfejsu Layout API	Bieżące nagłówki HTML w mPDF odwzorowują się na mechanizm header/footer w NextPDF, a nie na kod HTML wbudowany u góry treści.
`$mpdf->Output($name, $dest)`	`$doc->output($name, OutputDestination::…)`	Oznaczenia miejsca docelowego mPDF (`I`/`D`/`F`/`S`) odwzorowują się na wyliczenie `OutputDestination` (`Inline`/`Download`/file za pomocą `save()`/string za pomocą `getPdfData()`).
`$mpdf->Output('','S')`	`$doc->getPdfData()`	Zwraca bajty.
`$mpdf->Output($path,'F')`	`$doc->save($path)`	Zapisuje do ścieżki pliku.
`$mpdf->SetTitle($t)`	`$doc->setTitle($t)`	Trafia do słownika informacji § 14 normy ISO 32000-2 / platformy rozszerzonych metadanych (XMP) (`iso32000_2_sec14#x1.x5.p5`).
`$mpdf->SetProtection($perms,...)`	`$doc->setEncryption(...)` (Security API)	Uprawnienia są oparte na współpracy czytnika, a nie stanowią kontroli dostępu — zobacz uwagi dotyczące bezpieczeństwa.

Przykład kodu — szybki start

<?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";

Przykład kodu — produkcja

Ten przykład jest zgodny z examples/04-text-and-fonts.php, uruchamialnym punktem odniesienia dla koncepcji obsługi czcionek w tym przewodniku. Wykorzystuje jawny rozmiar strony, marginesy oraz treść, która obejmuje wybór czcionek.

<?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);

Przypadki brzegowe i pułapki

Argument $mode w WriteHTML. WriteHTML($html, $mode) w mPDF (2 = tylko CSS, 1 = element) nie ma odpowiednika. Umieść CSS w przekazywanym kodzie HTML; nie ma sekwencji „zapisz CSS, potem zapisz treść”.
Nadpisania dla pojedynczego AddPage. mPDF pozwala, aby AddPage() zmieniał format/orientation w trakcie dokumentu za pomocą argumentów. addPage() w NextPDF nie przyjmuje takich argumentów; zmiany rozmiaru modeluj w obrębie dokumentu, a nie w wywołaniu strony.
Kod HTML nagłówka/stopki. mPDF rejestruje bieżące nagłówki jako oddzielne fragmenty HTML; nie wklejaj ich do treści. Odwzoruj je na mechanizm header/footer w NextPDF.
Nazwy czcionek. mPDF normalizuje nazwy czcionek za pomocą tabeli fontdata/core-font. NextPDF dopasowuje CSS font-family do katalogu czcionek; alias mPDF rozpoznawany niejawnie może wymagać jawnego @font-face/family.
Oznaczenia miejsca docelowego. 'I'/'D'/'F'/'S' nie są akceptowane; użyj wyliczenia OutputDestination lub save()/getPdfData().

Wydajność

writeHtml() działa jednoprzebiegowo (ADR-001); szczytowe zużycie pamięci śledzi rozmiar dokumentu, a nie utrzymywany obiektowy model dokumentu (DOM). Budżet dla przykładu w tym przewodniku: wall_ms: 2000, peak_mb: 128. W przypadku długich dokumentów dziel treść między wywołania addPage(), zamiast przekazywać jeden ogromny ciąg. To te same wskazówki, które w mPDF dotyczą dzielenia na fragmenty za pomocą $mode, wyrażone przez model strony.

Uwagi dotyczące bezpieczeństwa

Uprawnienia są oparte na współpracy czytnika. SetProtection() → setEncryption() zapewnia poufność, a nie kontrolę dostępu: bity uprawnień ISO zależą od współpracującego czytnika. Nie przedstawiaj użytkownikom szyfrowania jako kontroli dostępu.
Metadane. SetTitle() oraz informacje o dokumencie trafiają do słownika informacji § 14 normy ISO 32000-2 / XMP (iso32000_2_sec14#x1.x5.p5); nigdy nie przechowuj tam danych poufnych.
NextPDF nie wykonuje skryptów osadzonych w dokumencie; żadna dyrektywa mPDF tego tutaj nie zmienia.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula
Czcionki są zapisywane jako programy czcionek embedded/subset.	ISO 32000-2	§9
Parametry strony format/margins odwzorowują się na ramkę granicy strony.	ISO 32000-2	§7
Metadane tytułu / ochrony trafiają do słownika informacji / XMP.	ISO 32000-2	§14
Dopasowanie czcionek / mechanizm zapasowy zależą od silnika.	CSS Fonts 4	§5.5

NextPDF wytwarza treść ISO 32000-2; nie zapewnia wizualnej identyczności z mPDF. Sprawdź wynik ponownie za każdym razem, gdy zmieniasz mechanizm renderujący.

Kontekst komercyjny

Nie dotyczy. Rdzeń NextPDF obejmuje opisaną tu ścieżkę migracji z mPDF.

Zobacz także

Szczegóły migracji (wymagane sekcje R6)

Dla kogo jest ten przewodnik

Zespoły używające mpdf/mpdf do konwersji HTML na PDF po stronie serwera. Jeśli kod jest zbudowany wokół new Mpdf([...]) + WriteHTML + Output (+ opcjonalny header/footer), zastosowanie mają odwzorowanie czasowników oraz odwzorowanie konfiguracji.

Zakres

Zakres obejmuje: tablicę konfiguracyjną konstruktora Mpdf, WriteHTML/Output/AddPage, headers/footers, czcionki, ochronę, metadane. Poza zakresem są wewnętrzne klasy mPDF oraz pomocnicza powierzchnia kodów szybkiej odpowiedzi (QR)/barcode/watermark. Odwzoruj je na odpowiednie moduły NextPDF — Barcode, Graphics — które nie są tutaj omówione.

Mapa zgodności

Zgodność dotyczy poziomu zachowania, a nie nakładki typu drop-in: NextPDF nie udostępnia nakładki klasy Mpdf. Przepisz każde miejsce wywołania. Przy ustalaniu oczekiwań wobec funkcji CSS korzystaj z wierszy oznaczonych jako zweryfikowane w macierzy obsługi CSS.

Odwzorowanie tablicy konfiguracyjnej konstruktora

Poniższe klucze konfiguracji mPDF potwierdzono względem publicznego repozytorium upstream (mpdf/mpdf, development). Nie reprodukowano żadnego tekstu dokumentacji upstream.

klucz konfiguracji mPDF	NextPDF	Uwagi
`mode`	(brak odpowiednika)	Ciąg trybu mPDF (`'utf-8'`, `'c'`, `'+aCJK'`, …) wybiera zachowanie font/script. NextPDF zawsze działa w Unicode; tekst chiński, japoński i koreański (CJK) jest obsługiwany przez wybór czcionki, a nie przez tryb. Usuń ten klucz.
`format`	`Config->pageSize` (obiekt wartości `PageSize` (VO))	Nazwane formaty stają się jawnymi wymiarami w punktach; tablice `[w,h]` odwzorowują się na `PageSize`.
`orientation`	zamień width/height w `PageSize`	Brak flagi orientacji; orientacja pozioma oznacza szerokość > wysokość.
`default_font_size`	bazowy rozmiar czcionki CSS	Ustaw go w bazowym arkuszu stylów, a nie w kluczu konstruktora.
`default_font`	CSS `font-family` / zarejestrowana czcionka	Ustaw domyślną rodzinę czcionek za pomocą CSS lub rejestracji czcionek.
`margin_left` / `margin_right` / `margin_top` / `margin_bottom`	`Config->margins` (`Margin` VO) w punktach	Użyj jednego obiektu wartości `Margin`; kolejność jego konstruktora to `Margin(top, right, bottom, left)` (sprawdź względem `src/ValueObjects/Margin.php`), a nie kolejności kluczy mPDF.
`margin_header` / `margin_footer`	przesunięcie header/footer za pomocą interfejsu Layout API	Odwzoruj je na konfigurację header/footer w NextPDF, a nie na klucze konstruktora.

Różnica w obsłudze czcionek

Jeden katalog czcionek. Lista katalogów czcionek mPDF, mapa fontdata oraz zapasowy zestaw core-font sprowadzają się do Config->fontsDirectory plus dopasowanie CSS font-family.
Zawsze podzbiory. NextPDF zawsze tworzy podzbiory osadzonych czcionek (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7); flagi podzbiorów mPDF nie mają odpowiednika i nie są potrzebne.
Dopasowanie zależy od silnika. Dopasowanie czcionek i mechanizm zapasowy różnią się zależnie od silnika (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13); alias czcionki mPDF może wymagać jawnego @font-face lub dokładnej nazwy rodziny. Po migracji ustal na nowo punkt odniesienia dla renderowania glifów. Różnice w podstawianiu są oczekiwane i nie są wadami.

Różnice w zachowaniu

Podstawianie czcionek (zobacz powyżej) — główna widoczna różnica.
Brak $mode w WriteHTML — przekaż kompletny kod HTML z wbudowanym CSS.
Brak nadpisania formatu dla pojedynczego AddPage — zmiany rozmiaru modeluj w obrębie dokumentu.
Uprawnienia są oparte na współpracy czytnika (zobacz uwagi dotyczące bezpieczeństwa).
Niezależny silnik układu — zawijanie wierszy / podział na strony różni się przy gęstej treści; wyznacz od nowa punkt odniesienia dla różnic wizualnych.

Są to udokumentowane różnice w zachowaniu, a nie wady w żadnym z silników.

Nieobsługiwane / brak bezpośredniego odpowiednika

Ciąg konstruktora mode — nie jest modelowany (zawsze Unicode).
Argumenty format/orientation/marginesu dla pojedynczego AddPage() — nie są argumentami w NextPDF.
Mapa fontdata mPDF — zastąpiona katalogiem czcionek + dopasowaniem CSS.
Oznaczenia miejsca docelowego 'I'/'D'/'F'/'S' mPDF — zastąpione wyliczeniem OutputDestination + save()/getPdfData().

Bezpieczna sekwencja migracji

Dodaj nextpdf/core obok mpdf/mpdf; na razie pozostaw zainstalowany mPDF.
Wybierz jeden dokument o niskim ryzyku. Przekonwertuj new Mpdf([...]), korzystając z odwzorowania konfiguracji, oraz WriteHTML/Output, korzystając z odwzorowania czasowników.
Zarejestruj czcionki, których używa dokument, w Config->fontsDirectory i dodaj jawne deklaracje @font-face/family dla każdego aliasu mPDF.
Wygeneruj oba pliki PDF dla tych samych danych wejściowych i porównaj je wizualnie. Różnice (podstawianie czcionek, zawijanie wierszy) są oczekiwane dla niezależnych silników — zaakceptuj je dla każdego dokumentu.
Odwzoruj dowolny kod HTML header/footer na mechanizm header/footer w NextPDF.
Powtarzaj dla każdego dokumentu, zaczynając od najniższego ryzyka; pozostaw zainstalowany mPDF aż do ostatniego przełączenia.
Usuń mpdf/mpdf z composer.json po ostatecznym przełączeniu.

Testowanie migracji

Utwórz migawkę wyniku mPDF dla reprezentatywnych dokumentów przed zmianą kodu (wzorcowe dane wejściowe; bajty będą się różnić).
Dla każdego zmigrowanego dokumentu potwierdź akceptację własną kontrolą (porównanie wizualne
- wyodrębnianie tekstu). Zachowanie czcionek/HTML w NextPDF sprawdzają examples/04-text-and-fonts.php, examples/08-html-basic.php oraz zestawy testów Html/Font rdzenia w tests/. Akceptacja migracji jest specyficzna dla dokumentu i pozostaje Twoją odpowiedzialnością.
Dodaj test regresji dla każdego zmigrowanego dokumentu.

Dowody / identyfikowalność

Każde stwierdzenie dotyczące zachowania NextPDF na tej stronie jest poparte testem w repozytorium, przykładem, sygnaturą źródła lub zapisem decyzji architektonicznej (ADR) bądź, w przypadku właściwości formatu PDF, klauzulami ISO 32000-2 / CSS przypiętymi przez generowanie wspomagane wyszukiwaniem (RAG) w nagłówku citations: oraz w tabeli Zgodność. Zachowanie mPDF opisano wyłącznie jako „niezależny silnik — spodziewaj się udokumentowanych różnic”; ta strona nie deklaruje żadnej zgodności, której nie potwierdza artefakt w repozytorium.

stwierdzenie dotyczące zachowania NextPDF	Dowód w repozytorium (ścieżka)
`WriteHTML()` odwzorowuje się bezpośrednio na `Document::writeHtml(string $html): static`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtml()`); `examples/08-html-basic.php`.
`WriteFixedPosHTML(...)` odwzorowuje się na `writeHtmlCell(...)`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtmlCell()`).
`createStandalone()` ma domyślną stronę A4 w orientacji pionowej (`595.276 × 841.890 pt`).	`src/Core/Config.php` (domyślny `PageSize`); `tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php`.
Kolejność konstruktora `Margin` to `(top, right, bottom, left)`.	`src/ValueObjects/Margin.php` (kolejność właściwości promowanych).
Miejsce docelowe wyniku określa wyliczenie `NextPDF\Contracts\OutputDestination`; `'I'/'D'/'F'/'S'` nie są akceptowane.	`src/Contracts/OutputDestination.php` (przypadki `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()` odwzorowuje się na `setEncryption(...)`; uprawnienia zależą od współpracy czytnika.	`src/Core/Concerns/HasSecurity.php` (`setEncryption()`); ISO 32000-2 §14 (nagłówek `citations:`).
`SetTitle()` → `setTitle()`; metadane trafiają do słownika informacji / XMP.	`src/Core/Concerns/HasMetadata.php` (`setTitle()`); `tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php`; ISO 32000-2 §14 (nagłówek `citations:`).
Czcionki są zawsze osadzane jako programy czcionek będące podzbiorami.	`tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php`; `examples/04-text-and-fonts.php`; ISO 32000-2 §9 (nagłówek `citations:`).
Dopasowanie czcionek / mechanizm zapasowy zależą od silnika (różnica w podstawianiu).	CSS Fonts 4 §5.5 (nagłówek `citations:` + Zgodność).
`writeHtml()` działa jednoprzebiegowo; szczytowe zużycie pamięci śledzi rozmiar dokumentu.	`docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md`.

Wycofanie zmian

Oba pakiety pozostają zainstalowane aż do ostatecznego przełączenia, więc wycofanie pojedynczego miejsca wywołania oznacza przywrócenie go do ścieżki mPDF. Po ostatecznym przełączeniu wycofanie oznacza przywrócenie mpdf/mpdf oraz wcześniejszego kodu z systemu kontroli wersji. Nie wiąże się to z żadną migracją danych.

Uwagi dotyczące wydajności

Zobacz Wydajność. Model jednoprzebiegowy eliminuje koszt utrzymywania bufora mPDF. Nowym kosztem dla każdego dokumentu jest wczesne rozpoznawanie czcionek (krok 3), które można buforować na poziomie katalogu czcionek.

Częste pułapki

Pozostawienie klucza mode i oczekiwanie, że będzie sterował zachowaniem CJK; NextPDF usuwa go, a CJK to wybór czcionki.
Przekazywanie WriteHTML($html, 2) (tryb tylko CSS); zamiast tego wbuduj CSS.
Wklejanie kodu HTML header/footer do treści.
Oczekiwanie, że alias mPDF zostanie rozpoznany jako ta sama czcionka bez jawnej rodziny.
Oczekiwanie wyniku byte/pixel-identical (niezależne silniki — ten przewodnik nigdy nie deklaruje zgodności typu drop-in ani 100%).
Traktowanie macierzy obsługi CSS jako orientacyjnej; jest ona autorytetem w zakresie zweryfikowanych funkcji.