Dompdf'ten NextPDF'ye geçiş

Bir bakışta

Bu kılavuz, HTML’den PDF dosyaları üreten Dompdf tabanlı bir kod tabanını NextPDF Html işlem hattına taşımanıza yardımcı olur. Her iki kitaplık da aynı genel akışı izlediği için çoğu çağrı noktası mekanik olarak dönüştürülebilir: HTML’yi yükleyin, işleyin ve bir PDF üretin. Asıl dikkat gerektiren bölüm, seçenek haritası ve CSS desteği farklarıdır. NextPDF ve Dompdf bağımsız motorlardır; bu nedenle Dompdf’in ürettiği bir yerleşim NextPDF sonucuyla uyumludur, onunla bayt düzeyinde özdeş değildir. Bu kılavuz, fiil eşlemesini, seçenek anahtarı eşlemesini, davranışsal farkları ve güvenli bir geçiş sırasını kapsar.

Bir HTML/CSS özelliğine NextPDF desteği olması, bir Dompdf belgesinin piksel piksel yeniden üretileceğini garanti etmez. CSS destek matrisi doğrulanmış özellikler için yetkili kaynaktır. Bu kılavuz davranışı açıklar; görsel eşdeğerlik iddiasında bulunmaz.

Kurulum

composer require nextpdf/core:^3

Geçiş boyunca dompdf/dompdf paketini kurulu tutun. Güvenli geçiş sırası, her çağrı noktası taşınana kadar iki motoru yan yana çalıştırır. Geçiş tamamlandıktan sonra paketi kaldırın.

Kavramsal genel bakış

Dompdf’in Dompdf nesnesi, Belge Nesne Modeli’ni (DOM), stil sayfasını, çerçeve ağacını ve tuvali tek bir cephede toplar. NextPDF bu sorumlulukları ayırır: bir NextPDF\Core\Document sayfa modelinden ve çıktıdan sorumludur, writeHtml() ise HTML işlem hattını yürütür. Ayrı bir iki adımlı “işle, sonra çıktı al” aşaması yoktur. writeHtml() içeriği yazarken yerleştirir; belgeyi save(), output() veya getPdfData() ile üretirsiniz.

NextPDF’nin yazdığı sayfa içeriği, ISO 32000-2 içerik akışı boyamasıdır (ISO 32000-2 §8, iso32000_2_sec8#x1.x3.p14). Kâğıt boyutu seçeneğiyle denetlenen sayfa geometrisi, sayfa nesnesinin MediaBox değerine eşlenir (ISO 32000-2 §7, iso32000_2_sec7#x1.x104.p10). Bunlar, uyumlu her işleyicinin paylaştığı temel motor davranışlarıdır. CSS’i bu içeriğe dönüştüren yerleşim algoritması NextPDF’ye özgüdür ve Dompdf’inkinden farklıdır; bkz. Davranışsal farklar.

API yüzeyi

NextPDF Html API’si, PHPDoc’tan otomatik üretilen Html modülü başvurusunda belgelenmiştir. Aşağıda kullanılan giriş noktaları şunlardır: Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string ve NextPDF\Core\Config değer nesnesi (pageSize, margins, fontsDirectory).

API fiil eşlemesi

Aşağıdaki herkese açık Dompdf API adları, herkese açık upstream deposuna göre doğrulanmıştır (dompdf/dompdf, master); depo içindeki _source-sidecar-upstream-api.md köken dosyasına bakın. Hiçbir upstream belge metni yeniden üretilmemiştir.

Dompdf	NextPDF	Notlar
`new Dompdf($options)`	`Document::createStandalone($config)`	Dompdf bir `Options` nesnesi alır; NextPDF bir `NextPDF\Core\Config` alır. Uzun süre çalışan işçiler için `DocumentFactory` kullanın, `createStandalone()` değil.
`$dompdf->loadHtml($html, $encoding)`	`$doc->writeHtml($html)`	NextPDF girişi UTF-8 olarak işler. Bir kodlama bağımsız değişkeni geçirmek yerine, UTF-8 olmayan girişin kodlamasını çağrıdan önce dönüştürün.
`$dompdf->loadHtmlFile($file)`	`$doc->writeHtml(file_get_contents($file))`	NextPDF’de dosya yükleme varyantı yoktur. Kaynak ilkesini kendi kodunuzda tutmak için dosyayı kendiniz okuyun.
`$dompdf->setPaper($size, $orientation)`	`ConfigpageSize` (bir `PageSize` değer nesnesi)	Şu bölüme bakın: Seçenek haritası.
`$dompdf->render()`	(örtük)	NextPDF, `writeHtml()` sırasında yerleştirir; ayrı bir işleme aşaması yoktur. `render()` çağrısını kaldırın.
`$dompdf->output()`	`$doc->getPdfData()`	PDF baytlarını döndürür.
`$dompdf->stream($name, $opts)`	`$doc->output($name, OutputDestination::Download)`	NextPDF hedefi `OutputDestination` numaralandırmasıyla seçer.
`$dompdf->setBasePath($p)` / `setProtocol()` / `setBaseHost()`	(kaynak çözümleme farklıdır)	NextPDF, göreli kaynakları bir temel path/protocol üçlüsüne göre değil, belge çalışma kümesine göre çözer; bkz. Davranışsal farklar.
`$dompdf->addInfo($label, $value)`	`$doc->setTitle()` / `setAuthor()` / meta veri API’si	Dompdf’in serbest biçimli bilgi çiftleri, çeşitli meta veri ayarlayıcılarına eşlenir (ISO 32000-2 §14 belge bilgisi, `iso32000_2_sec14#x1.x5.p5`).
`$dompdf->setHttpContext($ctx)`	(eşdeğeri yok)	NextPDF uzak kaynakları bir akış bağlamı üzerinden getirmez; bkz. Desteklenmeyen / doğrudan eşdeğeri olmayan.

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

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// Dompdf:
//   $dompdf = new Dompdf();
//   $dompdf->loadHtml('<h1>Invoice</h1>');
//   $dompdf->setPaper('A4', 'portrait');
//   $dompdf->render();
//   file_put_contents('out.pdf', $dompdf->output());

// NextPDF — the createStandalone() default page size 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, varsayılan olmayan açık bir kâğıt boyutu ve kenar boşluklarıyla, bu kılavuzun çalıştırılabilir dayanağı olan examples/08-html-basic.php dosyasını yansıtır. Bir Dompdf setPaper() çağrısının ve bir Options kenar boşluğu yapılandırmasının eşdeğeridir.

<?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: $dompdf->setPaper('letter','portrait') + margin options.
// US Letter portrait = 612 x 792 pt.
// Margin constructor order is (top, right, bottom, left) — all 0.5in here.
$config = new Config(
    pageSize: new PageSize(612.0, 792.0, 'Letter'),
    margins: new Margin(36.0, 36.0, 36.0, 36.0), // top,right,bottom,left; 0.5in in points
);

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

$html = <<<'HTML'
<h1 style="color:#1E3A8A;">Quarterly Report</h1>
<p>This report renders through the NextPDF Html pipeline. The CSS subset that
is <strong>Verified</strong> for production is the support-matrix authority,
not this page.</p>
<table border="1">
  <tr><th>Region</th><th>Total</th></tr>
  <tr><td>EMEA</td><td>1,204</td></tr>
</table>
HTML;

$doc->writeHtml($html);

// Equivalent of $dompdf->stream('report.pdf'):
$doc->output('report.pdf', OutputDestination::Download);

Sınır durumları ve tuzaklar

İki aşamalı işleme yoktur. render() ile output() arasında, örneğin sayfa sayısını okuyarak durumu inceleyen Dompdf kodunun kullandığı sınırın bire bir NextPDF karşılığı yoktur. Bunun yerine belgeyi writeHtml() sonrasında sorgulayın.
Kodlama. NextPDF, Dompdf’in $encoding parametresini kullanmaz. Girişi writeHtml() öncesinde UTF-8’e dönüştürün. Latin-1 baytları geçirmek hata vermez; mojibake üretir.
Yerinde bırakılan render(). Geride kalan $dompdf->render() türünde bir çağrının hiçbir NextPDF yöntemi yoktur ve ölümcül bir “undefined method” hatasıyla başarısız olur. Geçiş sırasında silin; bunun yerine boş gövde (stub) eklemeyin.
Satır içi PHP. Dompdf’in enable_php seçeneği <script type="text/php"> öğesini değerlendirir. NextPDF’de tasarım gereği belge içi PHP yürütmesi yoktur, çünkü bu bir enjeksiyon yüzeyidir. Bu mantığı writeHtml() öncesinde kendi PHP kodunuza taşıyın.
Göreli kaynak çözümleme. Dompdf, <img src> öğesini temel path/protocol/host üçlüsüne göre çözer. NextPDF ise belge çalışma kümesine göre çözer. Geçiş sırasında, bu değişkeni ortadan kaldırmak için mutlak yollar veya önceden çözülmüş veri URI’leri geçirin.

Performans

writeHtml(), mimari karar kaydı ADR-001’de açıklandığı gibi tek bir akışlı geçişte yerleştirir. Yerleşimden sonra tutulan ara bir çerçeve ağacı nesnesi yoktur; bu nedenle tepe bellek kullanımı, DOM düğüm sayısından çok belge boyutuyla ilişkilidir. Bu kılavuzdaki örneğin performans bütçesi wall_ms: 2000, peak_mb: 128 şeklindedir. Büyük belgeler için, çok megabaytlık tek bir dize oluşturmak yerine HTML’yi addPage() sınırları boyunca parçalara ayırın.

Güvenlik notları

Akış bağlamıyla uzaktan getirme yoktur. NextPDF, Dompdf’in setHttpContext() / enable_remote uzaktan getirme yolunu uygulamaz. Uzak varlıkları uygulamanızda çözün ve doğrulayın, ardından baytları veya veri URI’lerini geçirin. Bu, enable_remote seçeneğinin taşıdığı sunucu tarafı istek sahteciliği (SSRF) yüzeyini ortadan kaldırır.
Belge içi kod yürütme yoktur. Bir enable_php eşdeğerinin bulunmaması, bir eksiklik değil, kasıtlı bir sıkılaştırmadır.
Çeşitli ayarlayıcılar aracılığıyla ayarladığınız belge meta verileri, ISO 32000-2 §14 bilgi sözlüğüne / Genişletilebilir Meta Veri Platformu’na (XMP) yazılır (iso32000_2_sec14#x1.x5.p5). Oraya sır yerleştirmeyin.

Uygunluk

İfade	Belirtim	Madde
Sayfa içeriği, opaque/transparent modelinde içerik akışı boyamasıdır.	ISO 32000-2	§8
Kâğıt boyutu, sayfa nesnesinin sınır kutusuna eşlenir.	ISO 32000-2	§7
HTML yazı tipleri embedded/subset yazı tipi programları olarak yazılır.	ISO 32000-2	§9
Boşluk / satır kesme işleme motora özgüdür.	CSS Text 3	§6.5

NextPDF, ISO 32000-2 içeriği üretir. Geçirilen bir Dompdf belgesinin görsel olarak özdeş olduğunu iddia etmez. İşleyiciyi her değiştirdiğinizde çıktıyı yeniden gözden geçirin.

Ticari bağlam

Geçerli değildir. Bu HTML’den PDF’ye geçiş yolunu Core kapsar.

Ayrıca bkz.

Geçiş ayrıntıları (R6 gerekli bölümler)

Bu kimin için

Ekibiniz sunucu tarafında HTML’den PDF’ye dönüştürme için dompdf/dompdf çalıştırıyorsa ve NextPDF motoruna geçmek istiyorsa bu kılavuzu kullanın. Yalnızca loadHtml / setPaper / render / output çağrılarını yapıyorsanız, fiil eşlemesi tüm yüzeyinizi kapsar.

Kapsam

Kapsam dâhilinde: Dompdf cephe fiilleri, Options anahtarları, CSS özelliği eşitlik beklentileri, kaynak çözümleme ve meta veriler. Kapsam dışında: Dompdf’in iç FrameTree/Canvas/Stylesheet nesneleri. NextPDF’nin herkese açık karşılıkları yoktur; bu nedenle bunlara erişen kodu taşımayın; yerine herkese açık API’yi kullanın.

Uyumluluk haritası

Kapsam, çalışmaya hazır bir uyumluluk katmanı değil, davranışsal uyumluluk anlamına gelir. NextPDF’de bir Dompdf sınıfı uyumluluk katmanı yoktur (TCPDF yolunun aksine; bkz. /migration/tcpdf-compat/). Her çağrı noktasını fiil eşlemesi kullanarak yeniden yazın. CSS destek matrisi, CSS özelliği beklentileri için doğrulanmış satırlarda nihai kaynaktır. Bu kılavuz, her özellik için durumu yeniden açıklamaz.

Seçenek ve yapılandırma haritası

Dompdf seçeneği (anahtar / ayarlayıcı)	NextPDF	Notlar
`default_paper_size` / `setDefaultPaperSize()` ; `setPaper($size,...)`	`Config->pageSize` (`PageSize` VO)	Adlandırılmış boyutlar, açık nokta boyutlarına dönüşür. `new PageSize(595.276, 841.890, 'A4')`, `createStandalone()` varsayılanıdır.
`default_paper_orientation` / `setDefaultPaperOrientation()`	şu değerleri değiştirin: `PageSize` width/height	NextPDF’de yönlendirme bayrağı yoktur. Yatay bir sayfa, genişliği > yüksekliği olan bir `PageSize` değeridir.
`dpi` / `setDpi()`	(genel bir ayar düğmesi değil)	NextPDF PDF noktalarıyla çalışır (1/72 inç). Görüntü boyutlandırma, belge genelinde inç başına nokta (DPI) çarpanı değil, görüntü bazındadır. Sabit piksel boyutlarını noktalara yeniden hesaplayın.
`enable_remote` / `setIsRemoteEnabled()`	(eşdeğeri yok — tasarım gereği)	Uzak varlıkları kendi kodunuzda çözün; bkz. Güvenlik notları.
`enable_html5_parser` / `setIsHtml5ParserEnabled()`	(her zaman HTML’yi ayrıştırır)	Geçiş anahtarı yok; ayrıştırıcı işlem hattının kendisidir.
`enable_php` / `setIsPhpEnabled()`	(eşdeğeri yok — tasarım gereği)	Belge içi PHP desteklenmez. Mantığı şablonun dışına taşıyın.
`font_dir` / `setFontDir()`	`Config->fontsDirectory`	Tek bir yazı tipleri dizini dizesi.
`chroot`	(uygulamada çözün)	NextPDF bir dosya sistemi hapsi (jail) seçeneğini kabul etmez. Baytları geçirmeden önce yolları doğrulayın.
`default_font` / `setDefaultFont()`	CSS `font-family` / kayıtlı yazı tipi	Varsayılanı, genel bir seçenekte değil, temel stil sayfanızda veya yazı tipi kaydında ayarlayın.
`enable_font_subsetting` / `setIsFontSubsettingEnabled()`	(her zaman alt küme oluşturur)	NextPDF gömülü yazı tiplerinin her zaman alt kümesini oluşturur (ISO 32000-2 §9, `iso32000_2_sec9#x1.x45.p7`). “Kapalı” durumu yoktur; bayrağı kapalı bir Dompdf yolunun eşdeğeri yoktur ve gerekmez.

Davranışsal farklar

Yerleşim motoru. Dompdf ve NextPDF bağımsız CSS yerleşim uygulamaları kullanır. Boşluk daraltma ve satır kesme tanımlıdır, ancak motora duyarlı kalır (CSS Text 3 §6.5, css_text_3#x1.x6.x5.p20). Yoğun metinde satır kaydırma ve sayfalama farkları bekleyin. Geçişten sonra görsel farklar için yeni taban çizgisini belirleyin.
İşleme sınırı. İki aşamalı render()/output() sınırı yoktur (bkz. Sınır durumları).
Kaynak çözümleme. Temel yol/protokol/host işleme, belge çalışma kümesinden farklıdır.
DPI modeli. PDF noktaları, Dompdf’in DPI çarpanından farklıdır.
Meta veriler. Serbest biçimli addInfo() çiftleri, çeşitli ayarlayıcılardan farklıdır (ISO 32000-2 §14, iso32000_2_sec14#x1.x5.p5).

Bunlar, herhangi bir motordaki kusurlar değil, belgelenmiş davranışsal farklardır.

Desteklenmeyen / doğrudan eşdeğeri olmayan

enable_php (belge içi PHP) — kasıtlı olarak yoktur.
setHttpContext() / enable_remote uzaktan getirme — kasıtlı olarak yoktur.
Şunlara herkese açık erişim: FrameTree / Canvas / Stylesheet — herkese açık karşılığı yoktur.
dpi belge genelinde bir çarpan olarak — modellenmemiştir.

Bunlara bağımlı kod taşınamaz. Bu kodu kaldırın veya yukarıdaki satırları kullanarak uygulama kodunda yeniden ifade edin.

Güvenli geçiş sırası

Önce nextpdf/core paketini dompdf/dompdf ile birlikte ekleyin. Dompdf’i henüz kaldırmayın.
Düşük riskli bir belge seçin. Çağrı noktasını fiil eşlemesi ile yeniden yazın ve render() çağrısını silin.
Aynı girişten her iki PDF’yi de üretin ve görsel olarak karşılaştırın. Motorlar bağımsız olduğundan farkları beklenen kabul edin ve kabulü belge başına kararlaştırın.
Seçenek kullanımını seçenek haritası ile dönüştürün; DPI türevli boyutları noktalara yeniden hesaplayın.
Çözümleme değişkenini ortadan kaldırmak için uzak ve göreli varlıkları önceden mutlak yollara veya veri URI’lerine çözün.
En düşük riskten en yükseğe doğru belge başına yineleyin. Son çağrı noktası geçirilene kadar her iki motoru da kurulu tutun.
Yalnızca son geçişten sonra dompdf/dompdf paketini composer.json dosyasından kaldırın.

Geçişin sınanması

Temsil niteliği olan belgelerin Dompdf çıktısının, kodu değiştirmeden önce anlık görüntüsünü alın. Baytlar farklı olacağı için altın baytları değil, altın girişleri kullanın.
Geçirilen her belge için, NextPDF çıktısını görsel fark veya metin çıkarma doğrulamaları gibi kendi kabul denetiminizden geçirin. NextPDF’nin kendi HTML işlem hattı davranışı, examples/08-html-basic.php ve çekirdek tests/ Html paketi tarafından kapsanır. Geçiş kabulü belgeye özgüdür ve bunu doğrulamaktan siz sorumlusunuz.
Gelecekteki motor güncellemelerini yakalamak için geçirilen her belge için bir gerileme testi ekleyin.

Kanıt / izlenebilirlik

Bu sayfadaki her NextPDF davranışsal ifadesi; depo içi bir test, örnek, kaynak imzası veya mimari karar kaydıyla (ADR) ya da PDF biçim özellikleri söz konusu olduğunda, ön bilgideki citations: ve Uygunluk tablosunda Geri Getirmeyle Artırılmış Üretim (RAG) ile sabitlenmiş ISO 32000-2 / CSS maddeleriyle desteklenir. Dompdf davranışı yalnızca “bağımsız motor — belgelenmiş farklar bekleyin” şeklinde savlanır. Bir depo içi yapıt bunu kanıtlamadıkça bu sayfa hiçbir eşitlik iddiasında bulunmaz.

NextPDF davranışsal iddiası	Depo içi kanıt (yol)
`createStandalone()` varsayılan sayfası A4 dikeydir (`595.276 × 841.890 pt`).	`src/Core/Config.php` (varsayılan `PageSize(595.276, 841.890, 'A4')`); `tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php` (`createStandaloneWithNullConfigBuildsDocumentWithA4Defaults`).
`writeHtml()` tek bir akışlı geçişte yerleştirir; yerleşimden sonra DOM tutulmaz.	`docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md`; `src/Core/Concerns/HasTextOutput.php` (`writeHtml()`).
`writeHtml()` hiç sayfa yokken ilk sayfayı otomatik oluşturur.	`tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php` (`writeHtmlAutoCreatesFirstPageWhenNoPagesExist`).
`output()` / `save()` / `getPdfData()` üretim fiilleridir (iki aşamalı render/output yoktur).	`src/Core/Concerns/HasOutput.php` (`output()`, `save()`, `getPdfData()`); `tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php`.
Çıktı hedefi, `NextPDF\Contracts\OutputDestination` numaralandırmasıdır (`Inline`/`Download`/`File`/`String`).	`src/Contracts/OutputDestination.php`; `tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php`.
HTML yazı tipleri her zaman embedded/subset programlar olarak yazılır.	`tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php` (`recordUsedCharactersAffectsFontSubsetting`); ISO 32000-2 §9 (ön bilgi `citations:`).
Çeşitli meta veri ayarlayıcıları (`setTitle`/`setAuthor`) serbest biçimli `addInfo()` yerine geçer.	`src/Core/Concerns/HasMetadata.php` (`setTitle()`, `setAuthor()`); `tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php`.
Uçtan uca HTML işlem hattı (bu kılavuzun çalıştırılabilir dayanağı).	`examples/08-html-basic.php`; çekirdek `tests/Unit/Html/` paketi.
Boşluk / satır kesme motora özgüdür (yerleşim farkı).	CSS Text 3 §6.5 (ön bilgi `citations:` + Uygunluk).

Geri alma

Her iki paket de son geçişe kadar kurulu kaldığından, geçirilmemiş bir çağrı noktası için geri alma, o çağrı noktasını Dompdf yoluna döndürmek demektir. Son geçişten sonra geri alma, dompdf/dompdf paketini ve önceki çağrı noktasını sürüm denetiminden geri yüklemek anlamına gelir. Veri geçişi söz konusu değildir; yalnızca kod değişiklikleri vardır.

Performans değerlendirmeleri

Bkz. Performans. Tek geçişli model, geçişin bir çerçeve ağacı tutma maliyeti getirmediği anlamına gelir. Belge başına başlıca maliyet değişikliği, 5. adımdaki istekli varlık çözümlemesidir ve bunu önbelleğe alabilirsiniz.

Sık karşılaşılan tuzaklar

Mevcut render() çağrısını yerinde bırakmak; bu, ölümcül bir tanımsız yöntem hatasına yol açar.
UTF-8 olmayan baytları $encoding bırakıldıktan sonra geçirmek; bu, sessiz mojibake’ye yol açar.
Bağımsız motorlardan bayt düzeyinde özdeş veya piksel düzeyinde özdeş çıktı beklemek. Bu kılavuz hiçbir zaman drop-in replacement ya da byte-identical çıktı anlamında uyumluluk iddiasında bulunmaz.
Şablonlar için enable_php kullanımına bel bağlamak; bunlar yeniden düzenlenerek çıkarılmalıdır.
CSS destek matrisini tavsiye niteliğinde saymak. Beklentiler için doğrulanmış özelliklerde yetkili kaynak odur.