ย้ายจาก Dompdf ไปยัง NextPDF

ภาพรวมโดยสังเขป

คู่มือนี้ช่วยให้คุณย้ายฐานโค้ดที่ใช้ Dompdf ซึ่งสร้างไฟล์ Portable Document Format (PDF) จาก Hypertext Markup Language (HTML) ไปยังไปป์ไลน์ Html ของ NextPDF จุดเรียกใช้งานส่วนใหญ่ย้ายได้ค่อนข้างตรงไปตรงมา เพราะไลบรารีทั้งสองทำงานตามลำดับหลักแบบเดียวกัน คือโหลด HTML เรนเดอร์ และส่งออก PDF งานสำคัญอยู่ที่การแมปตัวเลือกและความแตกต่างในการรองรับ Cascading Style Sheets (CSS) NextPDF และ Dompdf เป็นเอนจินอิสระจากกัน ดังนั้นเค้าโครงที่ Dompdf สร้างขึ้นจึง เข้ากันได้กับ ผลลัพธ์ของ NextPDF แต่ไม่เหมือนกันทุกไบต์ คู่มือนี้ครอบคลุมการจับคู่เมธอด การจับคู่คีย์ตัวเลือก ความแตกต่างของพฤติกรรม และลำดับการย้ายที่ปลอดภัย

การที่ NextPDF รองรับฟีเจอร์ HTML/CSS ใดฟีเจอร์หนึ่ง ไม่ได้รับประกันว่าจะสร้างเอกสาร Dompdf ซ้ำได้ตรงกันทุกพิกเซล เมทริกซ์การรองรับ CSS คือแหล่งอ้างอิงที่เชื่อถือได้สำหรับฟีเจอร์ที่ผ่านการตรวจสอบแล้ว คู่มือนี้อธิบายพฤติกรรม ไม่ได้อ้างว่าผลลัพธ์จะเทียบเท่ากันทางภาพ

การติดตั้ง

composer require nextpdf/core:^3

ให้ติดตั้ง dompdf/dompdf ไว้ต่อไปในระหว่างการเปลี่ยนผ่าน ลำดับการย้ายที่ปลอดภัย จะรันเอนจินทั้งสองควบคู่กันจนกว่าจุดเรียกใช้งานแต่ละจุดจะย้ายเสร็จ จึงค่อยนำออกเมื่อการเปลี่ยนผ่านเสร็จสมบูรณ์

ภาพรวมเชิงแนวคิด

อ็อบเจกต์ Dompdf ของ Dompdf เป็นฟาซาดเดียวที่ถือครอง Document Object Model (DOM) สไตล์ชีต โครงสร้างเฟรม และแคนวาส NextPDF แยกความรับผิดชอบเหล่านี้ออกจากกัน โดย NextPDF\Core\Document ถือครองโมเดลหน้าและการส่งออก ส่วน writeHtml() ขับเคลื่อนไปป์ไลน์ HTML ไม่มีเฟสสองขั้นตอนแยกต่างหากแบบ “เรนเดอร์ แล้วจึงส่งออก” writeHtml() จัดวางเนื้อหาไปพร้อมกับการเขียน และคุณส่งออกเอกสารด้วย save() output() หรือ getPdfData() ได้

เนื้อหาหน้าซึ่ง NextPDF เขียนคือการวาดคอนเทนต์สตรีมตาม ISO 32000-2 (ISO 32000-2 §8, iso32000_2_sec8#x1.x3.p14) เรขาคณิตของหน้าที่ควบคุมด้วยตัวเลือกขนาดกระดาษจะจับคู่กับ MediaBox ของอ็อบเจกต์หน้า (ISO 32000-2 §7, iso32000_2_sec7#x1.x104.p10) สิ่งเหล่านี้เป็นพื้นฐานร่วมของเอนจินตัวเขียนที่สอดคล้องตามมาตรฐาน แต่ อัลกอริทึมการจัดวาง ที่แปลง CSS เป็นเนื้อหาเป็นของ NextPDF เองและแตกต่างจากของ Dompdf ดู ความแตกต่างของพฤติกรรม ประกอบ

พื้นผิว API

application programming interface (API) ของ Html ใน NextPDF มีเอกสารอยู่ในเอกสารอ้างอิงของโมดูล Html ซึ่งสร้างจาก PHPDoc โดยอัตโนมัติ จุดเข้าใช้งานที่ใช้ด้านล่างคือ Document::createStandalone() Document::writeHtml(string $html): static Document::writeHtmlCell(...) Document::output(?string, OutputDestination) Document::save(string $path): void Document::getPdfData(): string และอ็อบเจกต์ค่า NextPDF\Core\Config (pageSize, margins, fontsDirectory)

การจับคู่เมธอดของ API

ชื่อ API สาธารณะของ Dompdf ด้านล่างได้รับการตรวจยืนยันกับที่เก็บสาธารณะต้นทาง (dompdf/dompdf, master) ดูไฟล์อ้างอิงแหล่งที่มา _source-sidecar-upstream-api.md ภายในที่เก็บ ไม่มีการนำข้อความจากเอกสารต้นทางมาทำซ้ำ

Dompdf	NextPDF	หมายเหตุ
new Dompdf($options)	Document::createStandalone($config)	Dompdf รับอ็อบเจกต์ Options ส่วน NextPDF รับ NextPDF\Core\Config สำหรับเวิร์กเกอร์ที่ทำงานต่อเนื่องระยะยาว ให้ใช้ DocumentFactory แทนการเรียก createStandalone() โดยตรง
$dompdf->loadHtml($html, $encoding)	$doc->writeHtml($html)	NextPDF ถือว่าอินพุตเป็น UTF-8 ให้แปลงรหัสอินพุตที่ไม่ใช่ UTF-8 ก่อนเรียกใช้ แทนการส่งอาร์กิวเมนต์การเข้ารหัส
$dompdf->loadHtmlFile($file)	$doc->writeHtml(file_get_contents($file))	NextPDF ไม่มีเมธอดโหลดไฟล์โดยตรง อ่านไฟล์ด้วยตนเองเพื่อให้นโยบายทรัพยากรอยู่ในโค้ดของคุณ
$dompdf->setPaper($size, $orientation)	ConfigpageSize (อ็อบเจกต์ค่า PageSize)	ดูแผนที่ตัวเลือก ประกอบ
$dompdf->render()	(โดยปริยาย)	NextPDF จัดวางในระหว่าง writeHtml() ไม่มีเฟสเรนเดอร์แยกต่างหาก นำการเรียก render() ออก
$dompdf->output()	$doc->getPdfData()	คืนค่าไบต์ของ PDF
$dompdf->stream($name, $opts)	$doc->output($name, OutputDestination::Download)	NextPDF เลือกปลายทางด้วยอีนัม OutputDestination
$dompdf->setBasePath($p) / setProtocol() / setBaseHost()	(การแปลงทรัพยากรแตกต่างกัน)	NextPDF แปลงทรัพยากรแบบสัมพัทธ์เทียบกับชุดงานของเอกสาร ไม่ใช่ทริปเล็ต path/protocol ฐาน ดู ความแตกต่างของพฤติกรรม ประกอบ
$dompdf->addInfo($label, $value)	$doc->setTitle() / setAuthor() / API เมทาดาตา	คู่ข้อมูลแบบอิสระของ Dompdf จับคู่กับตัวตั้งค่าเมทาดาตาแบบมีชนิด (ISO 32000-2 §14 ข้อมูลเอกสาร, iso32000_2_sec14#x1.x5.p5)
$dompdf->setHttpContext($ctx)	(ไม่มีสิ่งที่เทียบเท่า)	NextPDF ไม่ดึงทรัพยากรระยะไกลผ่านสตรีมคอนเท็กซ์ ดู ไม่รองรับ / ไม่มีสิ่งที่เทียบเท่าโดยตรง ประกอบ

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

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

ตัวอย่างโค้ด — สำหรับการใช้งานจริง

ตัวอย่างนี้สอดคล้องกับ examples/08-html-basic.php ซึ่งเป็นไฟล์ที่รันได้และรองรับคู่มือนี้ โดยระบุขนาดกระดาษและระยะขอบอย่างชัดเจนแทนการใช้ค่าเริ่มต้น เทียบเท่ากับการเรียก setPaper() ของ Dompdf ร่วมกับการกำหนดค่าระยะขอบใน Options

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

 RegionTotal EMEA1,204HTML;$doc->writeHtml($html);// Equivalent of $dompdf->stream('report.pdf'):$doc->output('report.pdf', OutputDestination::Download);">

กรณีขอบและข้อควรระวัง

• ไม่มีการเรนเดอร์สองเฟส โค้ด Dompdf ที่ตรวจสอบสถานะระหว่าง render() และ output() เช่นการอ่านจำนวนหน้า จะไม่มีสิ่งที่เทียบเท่าใน NextPDF ที่ขอบเขตนั้นพอดี ให้สอบถามเอกสารหลังจาก writeHtml() แทน
• การเข้ารหัส NextPDF ละเว้นพารามิเตอร์ $encoding ของ Dompdf แปลงอินพุตเป็น UTF-8 ก่อน writeHtml() การส่งไบต์แบบ Latin-1 จะทำให้เกิดอักขระเพี้ยน (mojibake) ไม่ใช่ข้อผิดพลาด
• render() ที่หลงเหลืออยู่ การเรียก $dompdf->render() ที่ตกค้างไม่มีเมธอด NextPDF รองรับ และจะล้มเหลวด้วยข้อผิดพลาดร้ายแรง “undefined method” ให้ลบออกระหว่างการเปลี่ยนผ่าน อย่าทำเป็นสตับ
• PHP แบบอินไลน์ enable_php ของ Dompdf ประมวลผล <script type="text/php"> ส่วน NextPDF ไม่มี การประมวลผล PHP ภายในเอกสารโดยการออกแบบ เพราะเป็นพื้นผิวการแทรกโค้ด ย้ายตรรกะนั้นไปไว้ในโค้ด PHP ของคุณก่อน writeHtml() เสมอ
• การแปลงทรัพยากรแบบสัมพัทธ์ Dompdf แปลง <img src> เทียบกับทริปเปิล path/protocol/host ฐาน ส่วน NextPDF แปลงเทียบกับชุดงานของเอกสาร ระหว่างการย้าย ให้ส่งพาธสัมบูรณ์หรือ data URI ที่แปลงไว้ล่วงหน้าเพื่อขจัดตัวแปรนี้

ประสิทธิภาพ

writeHtml() จัดวางในรอบเดียวแบบสตรีมมิง ตามที่อธิบายไว้ในบันทึกการตัดสินใจทางสถาปัตยกรรม ADR-001 ไม่มีอ็อบเจกต์โครงสร้างเฟรมตัวกลางที่เก็บไว้หลังการจัดวาง ดังนั้นหน่วยความจำสูงสุดจึงสัมพันธ์กับขนาดเอกสารมากกว่าจำนวนโหนดของ DOM งบประมาณประสิทธิภาพสำหรับตัวอย่างในคู่มือนี้คือ wall_ms: 2000, peak_mb: 128 สำหรับเอกสารขนาดใหญ่ ให้แบ่ง HTML ตามขอบเขต addPage() แทนการสร้างสตริงขนาดหลายเมกะไบต์เพียงสตริงเดียว

หมายเหตุด้านความปลอดภัย

• ไม่มีการดึงข้อมูลระยะไกลด้วยสตรีมคอนเท็กซ์ NextPDF ไม่มีเส้นทางดึงข้อมูลระยะไกลแบบ setHttpContext() / enable_remote ของ Dompdf ให้แปลงและตรวจสอบทรัพยากรระยะไกลในแอปพลิเคชันของคุณ แล้วจึงส่งไบต์หรือ data URI วิธีนี้จะขจัดพื้นผิว server-side request forgery (SSRF) ที่ enable_remote นำมา
• ไม่มีการรันโค้ดภายในเอกสาร การไม่มีสิ่งที่เทียบเท่า enable_php เป็นการเสริมความแข็งแกร่งโดยเจตนา ไม่ใช่ช่องว่าง
• เมทาดาตาเอกสารที่คุณตั้งค่าผ่านตัวตั้งค่าแบบมีชนิดจะถูกเขียนลงในพจนานุกรมข้อมูล ISO 32000-2 §14 / Extensible Metadata Platform (XMP) (iso32000_2_sec14#x1.x5.p5) อย่าวางข้อมูลลับไว้ที่นั่น

ความสอดคล้อง

ข้อความระบุ	มาตรฐาน	ข้อกำหนด	reference_id (รหัสอ้างอิง)
เนื้อหาหน้าเป็นการวาดคอนเทนต์สตรีมในโมเดล opaque/transparent	ISO 32000-2	§8
ขนาดกระดาษจับคู่กับกล่องขอบเขตของอ็อบเจกต์หน้า	ISO 32000-2	§7
ฟอนต์ HTML ถูกเขียนเป็นโปรแกรมฟอนต์แบบ embedded/subset	ISO 32000-2	§9
การประมวลผลช่องว่าง / การตัดบรรทัดขึ้นอยู่กับเอนจิน	CSS Text 3	§6.5

NextPDF สร้างเนื้อหา ISO 32000-2 แต่ไม่ได้อ้างว่าเอกสาร Dompdf ที่ย้ายมาแล้วจะเหมือนกันทางภาพ ตรวจทานผลลัพธ์อีกครั้งทุกครั้งที่คุณเปลี่ยนตัวเรนเดอร์

บริบทเชิงพาณิชย์

ไม่เกี่ยวข้อง Core ครอบคลุมเส้นทางการย้ายจาก HTML เป็น PDF นี้

ดูเพิ่มเติม

• ดัชนีการย้าย
• การย้ายจาก mPDF
• เมทริกซ์การรองรับ CSS
• โมดูล Html

---

รายละเอียดการย้าย (ส่วนที่ R6 กำหนด)

คู่มือนี้เหมาะกับใคร

ใช้คู่มือนี้หากทีมของคุณใช้ dompdf/dompdf สำหรับการแปลง HTML เป็น PDF ฝั่งเซิร์ฟเวอร์และต้องการย้ายไปใช้เอนจิน NextPDF หากคุณเรียกเพียง loadHtml / setPaper / render / output เท่านั้น การจับคู่เมธอด จะครอบคลุมพื้นผิวทั้งหมดของคุณ

ขอบเขต

อยู่ในขอบเขต: เมธอดของฟาซาด Dompdf คีย์ Options ความคาดหวังเรื่องความเท่าเทียมของฟีเจอร์ CSS การแปลงทรัพยากร และเมทาดาตา นอกขอบเขต: อ็อบเจกต์ภายในของ Dompdf เช่น FrameTree/Canvas/Stylesheet NextPDF ไม่มีสิ่งที่เทียบเท่าแบบสาธารณะ ดังนั้นอย่าย้ายโค้ดที่เข้าถึงอ็อบเจกต์เหล่านั้น ให้แทนที่ด้วย API สาธารณะ

แผนที่ความเข้ากันได้

การครอบคลุมหมายถึง ความเข้ากันได้เชิงพฤติกรรม ไม่ใช่ชิมแบบ drop-in NextPDF ไม่มีชิมคลาส Dompdf (ต่างจากเส้นทาง TCPDF ดู /migration/tcpdf-compat/) ให้เขียนจุดเรียกใช้งานทุกจุดใหม่โดยใช้การจับคู่เมธอด แถวที่ผ่านการตรวจสอบแล้วในเมทริกซ์การรองรับ CSS เป็นตัวกำหนดความคาดหวังเรื่องฟีเจอร์ CSS ทั้งหมด คู่มือนี้ไม่ได้กล่าวซ้ำสถานะของแต่ละพร็อพเพอร์ตี

แผนที่ตัวเลือกและการกำหนดค่า

ตัวเลือก Dompdf (คีย์ / ตัวตั้งค่า)	NextPDF	หมายเหตุ
default_paper_size / setDefaultPaperSize() ; setPaper($size,...)	Config->pageSize (PageSize VO)	ขนาดที่มีชื่อจะถูกแปลงเป็นมิติหน่วยจุดที่ระบุชัดเจน new PageSize(595.276, 841.890, 'A4') คือค่าเริ่มต้นที่ createStandalone() ใช้
default_paper_orientation / setDefaultPaperOrientation()	สลับ PageSize width/height	NextPDF ไม่มีแฟล็กการวางแนว หน้าแนวนอนคือ PageSize ที่มีความกว้าง > ความสูง
dpi / setDpi()	(ไม่ใช่ปุ่มปรับระดับทั่วทั้งเอกสาร)	NextPDF ทำงานในหน่วยจุดของ PDF (1/72 นิ้ว) การกำหนดขนาดภาพทำเป็นรายภาพ ไม่ใช่ตัวคูณ dots per inch (DPI) ของทั้งเอกสาร ให้คำนวณขนาดพิกเซลคงที่ใหม่เป็นหน่วยจุด
enable_remote / setIsRemoteEnabled()	(ไม่มีสิ่งที่เทียบเท่า — โดยการออกแบบ)	แปลงทรัพยากรระยะไกลในโค้ดของคุณ ดูหมายเหตุด้านความปลอดภัย ประกอบ
enable_html5_parser / setIsHtml5ParserEnabled()	(แยกวิเคราะห์ HTML เสมอ)	ไม่มีสวิตช์ ตัวแยกวิเคราะห์คือไปป์ไลน์
enable_php / setIsPhpEnabled()	(ไม่มีสิ่งที่เทียบเท่า — โดยการออกแบบ)	ไม่รองรับ PHP ภายในเอกสาร ย้ายตรรกะออกจากเทมเพลต
font_dir / setFontDir()	Config->fontsDirectory	สตริงไดเรกทอรีฟอนต์เดียว
chroot	(แปลงในแอป)	NextPDF ไม่รับตัวเลือกจำกัดขอบเขตระบบไฟล์ (filesystem jail) ตรวจสอบความถูกต้องของพาธก่อนส่งไบต์
default_font / setDefaultFont()	CSS font-family / ฟอนต์ที่ลงทะเบียน	ตั้งค่าเริ่มต้นในสไตล์ชีตพื้นฐานหรือการลงทะเบียนฟอนต์ของคุณ ไม่ใช่ตัวเลือกทั่วทั้งเอกสาร
enable_font_subsetting / setIsFontSubsettingEnabled()	(ทำซับเซ็ตเสมอ)	NextPDF ทำซับเซ็ตฟอนต์ที่ฝังไว้เสมอ (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7) ไม่มีตัวเลือก “ปิด” เส้นทาง Dompdf ที่ปิดแฟล็กไม่มีสิ่งที่เทียบเท่าและไม่จำเป็นต้องมี

ความแตกต่างของพฤติกรรม

• เอนจินการจัดวาง Dompdf และ NextPDF ใช้การทำงานการจัดวาง CSS ที่เป็นอิสระจากกัน การยุบช่องว่างและการตัดบรรทัดมีข้อกำหนดรองรับ แต่ยังขึ้นอยู่กับเอนจิน (CSS Text 3 §6.5, css_text_3#x1.x6.x5.p20) คาดว่าจะมีความแตกต่างของการตัดบรรทัดและการแบ่งหน้าในข้อความที่หนาแน่น ให้กำหนดเส้นฐานของความต่างทางภาพใหม่หลังการย้าย
• รอยต่อการเรนเดอร์ ไม่มีขอบเขตสองเฟส render()/output() (ดู กรณีขอบ)
• การแปลงทรัพยากร การจัดการ base-path/protocol/host แตกต่างจากชุดงานของเอกสาร
• โมเดล DPI หน่วยจุดของ PDF แตกต่างจากตัวคูณ DPI ของ Dompdf
• เมทาดาตา คู่ addInfo() แบบอิสระแตกต่างจากตัวตั้งค่าแบบมีชนิด (ISO 32000-2 §14, iso32000_2_sec14#x1.x5.p5)

สิ่งเหล่านี้เป็นความแตกต่างของพฤติกรรมที่มีการบันทึกไว้ ไม่ใช่ข้อบกพร่องของเอนจินใดเอนจินหนึ่ง

ไม่รองรับ / ไม่มีสิ่งที่เทียบเท่าโดยตรง

• enable_php (PHP ภายในเอกสาร) — ไม่มีโดยเจตนา
• setHttpContext() / enable_remote การดึงข้อมูลระยะไกล — ไม่มีโดยเจตนา
• การเข้าถึงแบบสาธารณะไปยัง FrameTree / Canvas / Stylesheet — ไม่มีสิ่งที่เทียบเท่าแบบสาธารณะ
• dpi ในฐานะตัวคูณทั่วทั้งเอกสาร — ไม่ได้สร้างโมเดลไว้

โค้ดที่ขึ้นอยู่กับสิ่งเหล่านี้ไม่สามารถ “ย้าย” ได้โดยตรง ให้นำออกหรือเขียนใหม่ในโค้ดแอปพลิเคชันโดยใช้แถวด้านบน

ลำดับการย้ายที่ปลอดภัย

1. เพิ่ม nextpdf/core ควบคู่ไปกับ dompdf/dompdf อย่าเพิ่งนำ Dompdf ออก
2. เลือกเอกสารที่มีความเสี่ยงต่ำหนึ่งฉบับ เขียนจุดเรียกใช้งานของเอกสารนั้นใหม่ด้วยการจับคู่เมธอด และลบการเรียก render() ออก
3. สร้าง PDF ทั้งสองจากอินพุตเดียวกันและเปรียบเทียบความต่างทางภาพ ถือว่าความแตกต่างเป็นสิ่งที่คาดได้เพราะเอนจินทั้งสองเป็นอิสระจากกัน และตัดสินการยอมรับเป็นรายเอกสาร
4. แปลงการใช้ตัวเลือกด้วยแผนที่ตัวเลือก คำนวณขนาดที่ได้จาก DPI ให้เป็นหน่วยจุดใหม่
5. แปลงทรัพยากรระยะไกลและทรัพยากรแบบสัมพัทธ์ล่วงหน้าให้เป็นพาธสัมบูรณ์หรือ data URI เพื่อขจัดตัวแปรการแปลง
6. ทำซ้ำเป็นรายเอกสาร จากความเสี่ยงต่ำสุดไปสูงสุด คงเอนจินทั้งสองไว้จนกว่าจุดเรียกใช้งานสุดท้ายจะย้ายเสร็จ
7. นำ dompdf/dompdf ออกจาก composer.json หลังการเปลี่ยนผ่านครั้งสุดท้ายเท่านั้น

การทดสอบการย้าย

• บันทึกสแนปช็อตผลลัพธ์ Dompdf ของเอกสารตัวแทน ก่อน เปลี่ยนแปลงโค้ด ใช้อินพุตอ้างอิงมาตรฐาน (golden inputs) ไม่ใช่ไบต์อ้างอิงมาตรฐาน เพราะไบต์จะแตกต่างกัน
• สำหรับเอกสารแต่ละฉบับที่ย้ายมา ให้นำผลลัพธ์ NextPDF ผ่านการตรวจสอบการยอมรับของคุณเอง เช่น การเปรียบเทียบความต่างทางภาพหรือการยืนยันการดึงข้อความ พฤติกรรมไปป์ไลน์ HTML ของ NextPDF เองครอบคลุมโดย examples/08-html-basic.php และชุดทดสอบ Html ของ Core ใน tests/ การยอมรับการย้ายขึ้นอยู่กับเอกสารแต่ละฉบับ และคุณเป็นผู้รับผิดชอบในการยืนยัน
• เพิ่มการทดสอบการถดถอยสำหรับเอกสารที่ย้ายแต่ละฉบับ เพื่อให้ตรวจจับการอัปเดตเอนจินในอนาคตได้

หลักฐาน / การสอบกลับ

ทุกข้อความระบุพฤติกรรมของ NextPDF ในหน้านี้มีการทดสอบ ตัวอย่าง ลายเซ็นต้นทาง หรือบันทึกการตัดสินใจทางสถาปัตยกรรม (ADR) ภายในที่เก็บรองรับ สำหรับคุณสมบัติของรูปแบบ PDF จะมีข้อกำหนด ISO 32000-2 / CSS ที่ตรึงด้วย Retrieval-Augmented Generation (RAG) ใน citations: ของฟรอนต์แมตเทอร์ และตารางความสอดคล้อง รองรับ พฤติกรรมของ Dompdf ถูกระบุเพียงว่า “เอนจินอิสระ — คาดว่าจะมีความแตกต่างตามที่บันทึกไว้” หน้านี้ไม่อ้างความเท่าเทียมใด ๆ เว้นแต่จะมีอาร์ติแฟกต์ภายในที่เก็บพิสูจน์

ข้อความระบุพฤติกรรมของ NextPDF	หลักฐานภายในที่เก็บ (พาธ)
createStandalone() มีหน้าเริ่มต้นเป็น A4 แนวตั้ง (595.276 × 841.890 pt)	src/Core/Config.php (ค่าเริ่มต้น PageSize(595.276, 841.890, 'A4')); tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php (createStandaloneWithNullConfigBuildsDocumentWithA4Defaults)
writeHtml() จัดวางในรอบเดียวแบบสตรีมมิง ไม่มี DOM ที่เก็บไว้หลังการจัดวาง	docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md; src/Core/Concerns/HasTextOutput.php (writeHtml())
writeHtml() สร้างหน้าแรกโดยอัตโนมัติเมื่อยังไม่มีหน้าใด ๆ	tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php (writeHtmlAutoCreatesFirstPageWhenNoPagesExist)
output() / save() / getPdfData() เป็นเมธอดการส่งออก (ไม่มี render/output สองเฟส)	src/Core/Concerns/HasOutput.php (output(), save(), getPdfData()); tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php (การทดสอบ)
ปลายทางการส่งออกคืออีนัม NextPDF\Contracts\OutputDestination (Inline/Download/File/String)	src/Contracts/OutputDestination.php; tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php (การทดสอบ)
ฟอนต์ HTML ถูกเขียนเป็นโปรแกรมแบบ embedded/subset เสมอ	tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php (recordUsedCharactersAffectsFontSubsetting); ISO 32000-2 §9 (citations: ในฟรอนต์แมตเทอร์)
ตัวตั้งค่าเมทาดેตาแบบมีชนิด (setTitle/setAuthor) แทนที่ addInfo() แบบอิสระ	src/Core/Concerns/HasMetadata.php (setTitle(), setAuthor()); tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php (การทดสอบ)
ไปป์ไลน์ HTML แบบครบวงจร (ไฟล์ที่รันได้รองรับคู่มือนี้)	examples/08-html-basic.php; ชุดทดสอบ tests/Unit/Html/ ของ Core
การประมวลผลช่องว่าง / การตัดบรรทัดขึ้นอยู่กับเอนจิน (ความต่างของการจัดวาง)	CSS Text 3 §6.5 (citations: ในฟรอนต์แมตเทอร์ + ความสอดคล้อง)

การย้อนกลับ

เนื่องจากแพ็กเกจทั้งสองยังคงติดตั้งอยู่จนกว่าจะเปลี่ยนผ่านครั้งสุดท้าย การย้อนกลับสำหรับจุดเรียกใช้งานที่ยังไม่ถูกแปลงจึงหมายถึงการเปลี่ยนจุดเรียกใช้งานนั้นกลับไปใช้เส้นทาง Dompdf หลังการเปลี่ยนผ่านครั้งสุดท้าย การย้อนกลับหมายถึงการกู้คืน dompdf/dompdf และจุดเรียกใช้งานเดิมจากระบบควบคุมเวอร์ชัน ไม่มีการย้ายข้อมูลเข้ามาเกี่ยวข้อง มีเพียงการเปลี่ยนแปลงโค้ดเท่านั้น

ข้อพิจารณาด้านประสิทธิภาพ

ดูประสิทธิภาพ โมเดลรอบเดียวหมายความว่าการย้ายไม่ได้นำต้นทุนการเก็บโครงสร้างเฟรมเข้ามา ต้นทุนหลักที่เปลี่ยนไปต่อเอกสารคือการแปลงทรัพยากรล่วงหน้าจากขั้นตอนที่ 5 ซึ่งคุณสามารถแคชได้

ข้อผิดพลาดที่พบบ่อย

• การปล่อยให้ render() ค้างอยู่ ซึ่งทำให้เกิดข้อผิดพลาดร้ายแรงเมธอดที่ไม่ได้นิยาม
• การส่งไบต์ที่ไม่ใช่ UTF-8 หลังจากเลิกใช้ $encoding ซึ่งทำให้เกิดอักขระเพี้ยน (mojibake) แบบเงียบ ๆ
• การคาดหวังผลลัพธ์ที่เหมือนกันทุกไบต์หรือทุกพิกเซลจากเอนจินอิสระ คู่มือนี้ไม่เคยอ้างว่าเป็นแบบ drop-in หรือเข้ากันได้ 100%
• การพึ่งพาเทมเพลต enable_php ซึ่งต้องเขียนใหม่ออกไป
• การถือว่าเมทริกซ์การรองรับ CSS เป็นเพียงคำแนะนำ เมทริกซ์ดังกล่าวคือแหล่งอ้างอิงฟีเจอร์ที่ผ่านการตรวจสอบแล้วสำหรับสิ่งที่ควรคาดหวัง