mPDF'den NextPDF çekirdeğine geçiş

Genel bakış

Bu kılavuz, mPDF tabanlı bir kod tabanını NextPDF çekirdeğine taşımanıza yardımcı olur. mPDF’de ana içerik çağrısı WriteHTML()’dir; bu, doğrudan Document::writeHtml() ile eşleşir. İşin büyük kısmı, kurucu yapılandırma dizisinin eşlenmesi (mPDF her şeyi new Mpdf([...]) çağrısına aktarılan tek bir ilişkisel dizi üzerinden yapılandırır) ve yazı tipi işleme farklarıdır. NextPDF ile mPDF bağımsız motorlardır; bu nedenle geçirilen bir belge, mPDF çıktısıyla uyumludur, ancak ona bayt düzeyinde özdeş değildir. Bu kılavuz; eylem eşlemesini, yapılandırma dizisi eşlemesini, yazı tipi işleme farklarını, CSS desteğindeki farkları, davranışsal farkları ve güvenli geçiş sırasını kapsar.

Hangi HTML ve CSS özelliklerinin doğrulandığını CSS destek matrisi belirler. Bu kılavuz davranışı açıklar; mPDF ile görsel eşdeğerlik iddiasında bulunmaz.

Kurulum

composer require nextpdf/core:^3

Geçiş sırasında mpdf/mpdf paketini kurulu tutun. Son geçiş tamamlandıktan sonra kaldırın (bkz. güvenli geçiş sırası).

Kavramsal genel bakış

mPDF’nin Mpdf nesnesi, yapılandırma ile işlemeyi tek bir arayüz altında birleştirir. Bu nesne, kurucu dizisiyle yapılandırılır ve WriteHTML() ile sayfalama eylemleri (AddPage, SetHTMLHeader, SetHTMLFooter) tarafından yönlendirilir. NextPDF, yapılandırmayı değişmez NextPDF\Core\Config değer nesnesine ayırır ve içeriği Document::writeHtml() ile yazar. Kurucuya verilen bir “mode” dizesi yoktur. NextPDF, ilettiğiniz HTML’yi ayrıştırır, ardından belgeyi save(), output() veya getPdfData() ile yayımlar.

Yazı tipleri tarafında mPDF, bir yazı tipi dizini, bir fontdata eşlemesi ve bir “çekirdek yazı tipleri” yedek kümesiyle gelir. NextPDF, yazı tiplerini tek bir yazı tipi dizininden ve CSS font-family eşleştirmesinden çözer; gömülü yazı tiplerinde her zaman alt kümeleme yapar (Uluslararası Standartlaştırma Örgütü (ISO) 32000-2 §9, iso32000_2_sec9#x1.x45.p7). Yazı tipi eşleştirme ve yedekleme motora özeldir (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13); bu nedenle glif değişimi farklılık gösterebilir. Bu, ana görünür farktır ve yazı tipi işleme farkı bölümünde ele alınır.

API yüzeyi

NextPDF’in HTML API’si Html modülü referansında belgelenmiştir. Çekirdek giriş noktaları şunlardır: Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::addPage(), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string ve NextPDF\Core\Config değer nesnesi.

API eylem eşlemesi

Aşağıda listelenen mPDF genel yöntem adları, yukarı akış genel deposuna karşı doğrulanmıştır (mpdf/mpdf, development); depo içindeki _source-sidecar-upstream-api.md kaynak izleme dosyasına bakın. Yukarı akış belge metinlerinin hiçbiri çoğaltılmamıştır.

mPDF	NextPDF	Notlar
`new Mpdf([...])`	`Document::createStandalone($config)`	mPDF yapılandırma dizisi `NextPDF\Core\Config` değerine eşlenir; bkz. yapılandırma eşlemesi. Uzun ömürlü işçiler için `DocumentFactory` kullanın.
`$mpdf->WriteHTML($html)`	`$doc->writeHtml($html)`	Doğrudan eşleme. mPDF’nin ikinci `$mode` bağımsız değişkeninin (tam belge / yalnızca CSS / öğe) NextPDF karşılığı yoktur; eksiksiz HTML iletin.
`$mpdf->WriteFixedPosHTML(...)`	`$doc->writeHtmlCell(...)`	Konumlandırılmış ve boyutlandırılmış HTML bölgesi; x/y/width/height bağımsız değişkenlerini eşleyin.
`$mpdf->AddPage(...)`	`$doc->addPage()`	NextPDF, mPDF’nin çağrı başına orientation/format/kenar boşluğu geçersiz kılmalarını bağımsız değişken olarak almaz; bunun yerine çağrılar arasında belge modelini değiştirin.
`$mpdf->SetHTMLHeader($html)` / `SetHTMLFooter($html)`	Layout API’si üzerinden header/footer	mPDF’nin yinelenen HTML üst bilgileri, gövdenin üstündeki satır içi HTML’ye değil, NextPDF header/footer mekanizmasına eşlenir.
`$mpdf->Output($name, $dest)`	`$doc->output($name, OutputDestination::…)`	mPDF hedef karakterleri (`I`/`D`/`F`/`S`), `OutputDestination` sabit listesine eşlenir (`Inline`/`Download`/file için `save()`/string için `getPdfData()`).
`$mpdf->Output('','S')`	`$doc->getPdfData()`	Bayt döndürür.
`$mpdf->Output($path,'F')`	`$doc->save($path)`	Bir dosya yoluna yazar.
`$mpdf->SetTitle($t)`	`$doc->setTitle($t)`	ISO 32000-2 §14 bilgi sözlüğüne / XMP’ye yerleşir (`iso32000_2_sec14#x1.x5.p5`).
`$mpdf->SetProtection($perms,...)`	`$doc->setEncryption(...)` (Security API)	İzinler erişim denetimi değil, okuyucuyla iş birliğine dayalıdır — bkz. Güvenlik notları.

Kod örneği — hızlı başlangıç

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

Kod örneği — üretim

Bu örnek, bu kılavuzdaki yazı tipi işleme kavramlarının çalıştırılabilir referansı olan examples/04-text-and-fonts.php ile uyumludur. Açık sayfa boyutu, kenar boşlukları ve yazı tipi seçimi içeren bir içerik gövdesi kullanır.

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

Uç durumlar ve dikkat edilecek noktalar

WriteHTML üzerindeki $mode bağımsız değişkeni. mPDF’nin WriteHTML($html, $mode) (2 = yalnızca CSS, 1 = öğe) çağrısının karşılığı yoktur. CSS’yi ilettiğiniz HTML’nin içine koyun; “önce CSS yaz, sonra gövde yaz” diye bir sıra yoktur.
AddPage başına geçersiz kılmalar. mPDF, AddPage() çağrısının belge ortasında bağımsız değişkenlerle format/orientation değiştirmesine izin verir. NextPDF addPage() böyle bir bağımsız değişken almaz; model boyut değişiklikleri sayfa çağrısında değil, belge boyunca yapılır.
Üst bilgi/alt bilgi HTML’si. mPDF, yinelenen üst bilgileri ayrı HTML parçaları olarak kaydeder; bunları gövdeye yapıştırmayın. Bu parçaları NextPDF header/footer mekanizmasına eşleyin.
Yazı tipi adları. mPDF, yazı tipi adlarını kendi fontdata/core-font tablosu üzerinden normalleştirir. NextPDF, CSS font-family değerini yazı tipleri dizinine göre eşleştirir; mPDF’de sessizce çözümlenen bir takma ad, açık bir @font-face/family bildirimi gerektirebilir.
Hedef karakterleri. 'I'/'D'/'F'/'S' kabul edilmez; OutputDestination sabit listesini ya da save()/getPdfData() kullanın.

Performans

writeHtml() tek geçişlidir (ADR-001); tepe bellek, korunan bir Belge Nesne Modeli’ni (DOM) değil, belge boyutunu izler. Bu kılavuzun örneği için bütçe: wall_ms: 2000, peak_mb: 128. Uzun belgelerde, tek bir devasa dize iletmek yerine içeriği addPage() çağrılarına bölün. Bu, mPDF’nin $mode parçalama yaklaşımındaki aynı yönlendirmenin sayfa modeliyle ifade edilmiş halidir.

Güvenlik notları

İzinler okuyucuyla iş birliğine dayalıdır. SetProtection() → setEncryption() erişim denetimi değil, gizlilik sağlar: ISO izin bitleri, iş birliği yapan bir okuyucuya bağlıdır. Şifrelemeyi kullanıcılara erişim denetimi olarak sunmayın.
Üst veri. SetTitle() ve belge bilgileri ISO 32000-2 §14 bilgi sözlüğüne / XMP’ye yerleşir (iso32000_2_sec14#x1.x5.p5); burada asla gizli bilgi saklamayın.
NextPDF belge içi betikleri yürütmez; hiçbir mPDF yönergesi bunu burada değiştirmez.

Uygunluk

İfade	Spesifikasyon	Madde
Yazı tipleri gömülü/alt kümelenmiş yazı tipi programları olarak yazılır.	ISO 32000-2	§9
Sayfa format/margins değerleri, sayfa sınır kutusuna eşlenir.	ISO 32000-2	§7
Başlık / koruma üst verisi, bilgi sözlüğüne / XMP’ye yerleşir.	ISO 32000-2	§14
Yazı tipi eşleştirme / yedekleme motora özeldir.	CSS Fonts 4	§5.5

NextPDF, ISO 32000-2 içeriği üretir; mPDF ile görsel özdeşlik iddiasında bulunmaz. İşleyiciyi her değiştirdiğinizde çıktıyı yeniden gözden geçirin.

Ticari bağlam

Geçerli değil. NextPDF çekirdeği, burada açıklanan mPDF geçiş yolunu kapsar.

Ayrıca bkz.

Geçiş ayrıntıları (R6 zorunlu bölümleri)

Bu kimin için

Sunucu tarafı HTML’den PDF’ye dönüşüm için mpdf/mpdf kullanan ekipler. Kodunuz new Mpdf([...]) + WriteHTML + Output (+ isteğe bağlı header/footer) üzerine kuruluysa, eylem eşlemesi ve yapılandırma eşlemesi bunu kapsar.

Kapsam

Kapsam içinde: Mpdf kurucu yapılandırma dizisi, WriteHTML/Output/AddPage, headers/footers, yazı tipleri, koruma, üst veri. Kapsam dışında: mPDF’nin dahili sınıfları ve Hızlı Yanıt (QR)/barcode/watermark yardımcı yüzeyleri. Bunları ilgili NextPDF modüllerine (Barcode, Graphics) eşleyin; burada ele alınmazlar.

Uyumluluk eşlemesi

Davranışsal uyumluluk, doğrudan takılabilir bir uyumluluk katmanı anlamına gelmez: NextPDF bir Mpdf sınıfı uyumluluk katmanı sağlamaz. Her çağrı yerini yeniden yazın. CSS özelliği beklentileri için CSS destek matrisi içindeki doğrulanmış satırları kullanın.

Kurucu yapılandırma dizisi eşlemesi

Aşağıdaki mPDF yapılandırma anahtarları, yukarı akış genel deposuna karşı doğrulanmıştır (mpdf/mpdf, development). Yukarı akış belge metinlerinin hiçbiri çoğaltılmamıştır.

mPDF yapılandırma anahtarı	NextPDF	Notlar
`mode`	(karşılığı yok)	mPDF’nin mode dizesi (`'utf-8'`, `'c'`, `'+aCJK'`, …) font/script davranışını seçer. NextPDF her zaman Unicode’dur; Çince, Japonca ve Korece (CJK) metin bir mod ile değil, yazı tipi seçimiyle işlenir. Anahtarı bırakın.
`format`	`Config->pageSize` (`PageSize` değer nesnesi (VO))	Adlandırılmış biçimler açık nokta boyutlarına dönüşür; `[w,h]` dizileri bir `PageSize` ile eşlenir.
`orientation`	Takas: `PageSize` width/height değerleri	Yön bayrağı yoktur; yatay, genişlik > yükseklik anlamına gelir.
`default_font_size`	CSS taban yazı tipi boyutu	Bunu bir kurucu anahtarında değil, taban stil sayfanızda ayarlayın.
`default_font`	CSS `font-family` / kayıtlı yazı tipi	Varsayılan aileyi CSS / yazı tipi kaydı üzerinden ayarlayın.
`margin_left` / `margin_right` / `margin_top` / `margin_bottom`	`Config->margins` (`Margin` VO) nokta cinsinden	Tek bir `Margin` değer nesnesi kullanın; kurucu sırası mPDF anahtar sırası değil, `Margin(top, right, bottom, left)` şeklindedir (`src/ValueObjects/Margin.php` üzerinden doğrulayın).
`margin_header` / `margin_footer`	Layout API’si üzerinden header/footer uzaklığı	Bunları kurucu anahtarlarına değil, NextPDF header/footer yapılandırmasına eşleyin.

Yazı tipi işleme farkı

Tek bir yazı tipleri dizini. mPDF’nin yazı tipi dizini listesi, fontdata eşlemesi ve çekirdek yazı tipi yedeklemesi, Config->fontsDirectory ile CSS font-family eşleştirmesinde birleşir.
Her zaman alt kümeleme. NextPDF gömülü yazı tiplerinde her zaman alt kümeleme yapar (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7); mPDF’nin alt küme bayraklarının karşılığı yoktur ve gerekli değildir.
Eşleştirme motora özeldir. Yazı tipi eşleştirme ve yedekleme motora göre farklılık gösterir (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13); bir mPDF yazı tipi takma adı, açık bir @font-face ya da tam aile adı gerektirebilir. Geçişten sonra glif işlemeyi yeniden baz alın. Değişim farkları beklenir; bunlar kusur değildir.

Davranışsal farklar

Yazı tipi değişimi (yukarıya bakın) — ana görünür fark.
WriteHTML üzerinde $mode yok — satır içi CSS ile eksiksiz HTML iletin.
AddPage başına biçim geçersiz kılması yok — model boyut değişiklikleri belge boyunca yapılır.
İzinler okuyucuyla iş birliğine dayalıdır (bkz. Güvenlik notları).
Bağımsız yerleşim motoru — yoğun içerikte satır kaydırma / sayfalama farklılık gösterir; görsel farkları yeniden baz alın.

Bunlar belgelenmiş davranışsal farklardır; iki motordan birindeki kusur anlamına gelmez.

Desteklenmeyen / doğrudan karşılığı yok

mode kurucu dizesi — modellenmemiştir (her zaman Unicode).
Her AddPage() çağrısında format/orientation/kenar boşluğu bağımsız değişkenleri — NextPDF’de bağımsız değişken değildir.
mPDF fontdata eşlemesi — yazı tipleri dizini + CSS eşleştirmesiyle değiştirilmiştir.
mPDF’nin 'I'/'D'/'F'/'S' hedef karakterleri — OutputDestination sabit listesi + save()/getPdfData() ile değiştirilmiştir.

Güvenli geçiş sırası

Yeni nextpdf/core paketini mpdf/mpdf ile birlikte ekleyin; şimdilik mPDF’yi kurulu tutun.
Düşük riskli bir belge seçin. new Mpdf([...]) çağrısını yapılandırma eşlemesi üzerinden, WriteHTML/Output çağrılarını da eylem eşlemesi üzerinden dönüştürün.
Belgenin kullandığı yazı tiplerini Config->fontsDirectory içinde kaydedin ve mPDF takma adları için açık @font-face/family bildirimleri ekleyin.
Aynı girdi için her iki PDF’yi de oluşturun ve görsel olarak karşılaştırın. Farklar (yazı tipi değişimi, satır kaydırma) bağımsız motorlar için beklenir — bunları belge bazında kabul edin.
Herhangi bir header/footer HTML’sini NextPDF header/footer mekanizmasına eşleyin.
Önce en düşük riskli belgelerden başlayarak belge bazında tekrarlayın; son geçişe kadar mPDF’yi kurulu tutun.
Son geçişten sonra mpdf/mpdf paketini composer.json dosyasından kaldırın.

Geçişi test etme

Kodu değiştirmeden önce temsili belgeler için mPDF çıktısının anlık görüntüsünü alın (altın girdiler; baytlar farklı olacaktır).
Geçirilen her belge için, kendi denetiminizle kabulü doğrulayın (görsel fark
- metin çıkarımı). NextPDF’in yazı tipi/HTML davranışı examples/04-text-and-fonts.php ve examples/08-html-basic.php ile ve çekirdek tests/ Html/Font paketleri tarafından test edilir. Geçiş kabulü belgeye özeldir ve sizin sorumluluğunuzda kalır.
Geçirilen her belge için bir gerileme testi ekleyin.

Kanıt / izlenebilirlik

Bu sayfadaki her NextPDF davranışsal ifadesi, depo içindeki bir test, örnek, kaynak imzası veya mimari karar kaydı (ADR) ile ya da PDF biçimi özellikleri için, retrieval-augmented generation (RAG) ile sabitlenmiş ISO 32000-2 / CSS maddeleriyle desteklenir; bu maddeler ön bilgideki citations: içinde ve Uygunluk tablosunda yer alır. mPDF davranışı yalnızca “bağımsız motor — belgelenmiş farklar beklenir” olarak ileri sürülür; bu sayfa, depo içindeki bir yapının kanıtlamadığı hiçbir eşdeğerlik iddiasında bulunmaz.

NextPDF davranışsal iddiası	Depo içi kanıt (yol)
`WriteHTML()` doğrudan `Document::writeHtml(string $html): static` ile eşlenir.	`src/Core/Concerns/HasTextOutput.php` (`writeHtml()`); `examples/08-html-basic.php`.
`WriteFixedPosHTML(...)`, `writeHtmlCell(...)` ile eşlenir.	`src/Core/Concerns/HasTextOutput.php` (`writeHtmlCell()`).
`createStandalone()` varsayılan sayfası A4 dikeydir (`595.276 × 841.890 pt`).	`src/Core/Config.php` (varsayılan `PageSize`); `tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php`.
`Margin` kurucu sırası `(top, right, bottom, left)` şeklindedir.	`src/ValueObjects/Margin.php` (yükseltilmiş özellik sırası).
Çıktı hedefi `NextPDF\Contracts\OutputDestination` sabit listesidir; `'I'/'D'/'F'/'S'` kabul edilmez.	`src/Contracts/OutputDestination.php` (durumlar `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()`, `setEncryption(...)` ile eşlenir; izinler okuyucuyla iş birliğine dayalıdır.	`src/Core/Concerns/HasSecurity.php` (`setEncryption()`); ISO 32000-2 §14 (ön bilgi `citations:`).
`SetTitle()` → `setTitle()`; üst veri, bilgi sözlüğüne / XMP’ye yerleşir.	`src/Core/Concerns/HasMetadata.php` (`setTitle()`); `tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php`; ISO 32000-2 §14 (ön bilgi `citations:`).
Yazı tipleri her zaman alt kümelenmiş programlar olarak gömülür.	`tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php`; `examples/04-text-and-fonts.php`; ISO 32000-2 §9 (ön bilgi `citations:`).
Yazı tipi eşleştirme / yedekleme motora özeldir (değişim farkı).	CSS Fonts 4 §5.5 (ön bilgi `citations:` + Uygunluk).
`writeHtml()` tek geçişlidir; tepe bellek belge boyutunu izler.	`docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md`.

Geri alma

Her iki paket de son geçişe kadar kurulu kalır; bu nedenle her çağrı yeri için geri alma, o çağrı yerini mPDF yoluna döndürmek anlamına gelir. Son geçişten sonra geri alma, mpdf/mpdf paketini ve önceki kodu sürüm denetiminden geri yüklemek anlamına gelir. Hiçbir veri geçişi söz konusu değildir.

Performans değerlendirmeleri

Bkz. Performans. Tek geçişli model, mPDF’nin tutulan arabellek maliyetini ortadan kaldırır. Yeni belge başına maliyet, yazı tipleri dizini üzerinden önbelleğe alınabilen erken yazı tipi çözümlemesidir (3. adım).

Sık karşılaşılan tuzaklar

Eski mode anahtarını korumak ve ondan CJK davranışı beklemek; NextPDF onu bırakır ve CJK davranışı yazı tipi seçimine bağlıdır.
Eski WriteHTML($html, 2) (yalnızca CSS modu) çağrısını taşımak; bunun yerine satır içi CSS kullanın.
header/footer HTML’sini gövdeye yapıştırmak.
Bir mPDF takma adının, açık bir aile olmadan aynı yazı tipine çözümlenmesini beklemek.
byte/pixel-identical çıktı beklemek (bağımsız motorlar — bu kılavuz hiçbir zaman doğrudan takılabilirlik ya da “uyumlu ama byte-identical değil” türü bir iddia öne sürmez).
CSS destek matrisini tavsiye niteliğinde saymak; o, doğrulanmış özellikler için otoritedir.