Support: ยูทิลิตีส่วนกลาง + Clock + Sleeper

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

โมดูล Support ประกอบด้วยยูทิลิตีส่วนกลางที่เอนจินใช้ภายใน และยังเปิดเผยพื้นผิวสาธารณะขนาดเล็ก ได้แก่ นาฬิการะบบตาม PHP Standards Recommendation 20 (PSR-20) ไปป์ไลน์การรวบรวมคำเตือน และพรีมิทีฟการทำซีเรียลไลซ์ของ Portable Document Format (PDF) เนมสเปซส่วนใหญ่เป็นโครงสร้างพื้นฐานภายใน หน้านี้จัดทำเอกสารส่วนที่คุณสามารถพึ่งพาได้ และระบุส่วนที่ใช้ภายในเท่านั้น

การติดตั้ง

composer require nextpdf/core:^3

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

Clock (PSR-20) SystemClock ใช้งาน Psr\Clock\ClockInterface เมท็อด now() ส่งคืนเวลาปัจจุบันเป็น DateTimeImmutable โมเดล PSR-20 กำหนดอินเทอร์เฟซนาฬิกาที่มีการดำเนินการอ่านหนึ่งรายการ ซึ่งส่งคืนเวลาปัจจุบันเป็นค่าวันที่และเวลาแบบไม่เปลี่ยนรูป (PSR-20 psr_20_clock#2.1) SystemClock เป็นค่าเริ่มต้น เอนจินจะใช้คลาสนี้เมื่อคุณไม่ได้ฉีดนาฬิกาเข้ามา สำหรับเวลาคงที่ในการทดสอบ ให้ฉีดนาฬิกาที่หยุดนิ่งซึ่งใช้งานอินเทอร์เฟซเดียวกัน จับคู่นาฬิกากับ Config::deterministic เมื่อคุณต้องการเอาต์พุตที่เหมือนกันในระดับไบต์

ไปป์ไลน์คำเตือน WarningCollector เป็นตัวขนส่งในหน่วยความจำหลักสำหรับปัญหาการเรนเดอร์ที่ไม่ร้ายแรงจนทำให้ล้มเหลว เอนจินจะเพิ่ม Warning สำหรับการลดทอนคุณภาพแบบดีเทอร์มินิสติกแต่ละครั้ง เช่น คอลัมน์ตารางที่ถูกบีบ ฟอนต์ที่แก้ไม่ได้ หรือกลีฟที่ขาดหายไป หลังการสร้าง คุณอ่านคำเตือนได้ผ่าน Document::getWarnings() Warning เป็นออบเจ็กต์ค่าแบบไม่เปลี่ยนรูป โดยมี WarningCode หนึ่งค่า WarningSeverity หนึ่งค่า (warning หรือ degraded) หน้า ชนิดองค์ประกอบ feature id แฟล็ก degraded-parity ข้อความ DegradationImpact หนึ่งค่า และ capability id ที่เป็นทางเลือก WarningCode เป็น enum แบบสตริงที่มีตัวระบุเสถียร ตัวระบุใช้คำนำหน้า NEXTPDF_W_ เช่น NEXTPDF_W_FONT_UNRESOLVED คุณจึงจับคู่ได้อย่างปลอดภัยในการทดสอบ addWithPolicy() บังคับใช้ DegradationPolicy ที่กำลังทำงานอยู่ ภายใต้นโยบายแบบเข้มงวด ผลกระทบด้านความสอดคล้อง ด้านความหมาย หรือแบบบล็อก จะโยน DegradedException ภายใต้นโยบายแบบสมดุล เฉพาะผลกระทบแบบบล็อกเท่านั้นที่จะโยนข้อยกเว้น นโยบายแบบผ่อนปรนจะไม่โยนข้อยกเว้นเลย

พรีมิทีฟของ PDF PdfStringEscaper เป็นแหล่งความจริงเพียงแหล่งเดียวสำหรับการ escape สตริงและชื่อของ PDF escapeLiteral() จะ escape อักขระที่จำเป็นในสตริงแบบลิเทอรัลของ PDF ได้แก่ reverse solidus วงเล็บ carriage return (CR) line feed (LF) horizontal tab (HT) backspace (BS) และ form feed (FF) นอกจากนี้ยังตัดไบต์ NUL ออกด้วย escapeName() จะเข้ารหัสไบต์เป็นเลขฐานสิบหกเมื่ออยู่นอกช่วง American Standard Code for Information Interchange (ASCII) ที่พิมพ์ได้ และเมื่อเป็นไบต์ในชุดตัวคั่นของ PDF สำหรับออบเจ็กต์ชื่อ BinaryBuffer เป็นตัวสะสมไบนารีที่ปรับให้เหมาะกับการเขียนออบเจ็กต์และสตรีมของ PDF ในโหมดสตรีมมิง จะ spill ไปยัง handle php://temp สำหรับเอกสารขนาดใหญ่ นอกจากนี้ยังรองรับการดำเนินการแบบ byte-range ที่การฝังลายเซ็นต้องการ PdfOperators เก็บสตริงรูปแบบของตัวดำเนินการ content-stream สำหรับ path ข้อความ สถานะกราฟิก และฟอนต์ เลเยอร์การวาดและตัวแยกวิเคราะห์ใช้สตริงเหล่านี้ร่วมกัน

BinaryBuffer PdfOperators และส่วนที่เหลือส่วนใหญ่ของ NextPDF\Support\ เป็นโครงสร้างพื้นฐานภายใน เลเยอร์ writer และการวาดใช้ส่วนเหล่านี้ หน้านี้จัดทำเอกสารไว้เพื่อความครบถ้วนและการตรวจสอบ ส่วนเหล่านี้ไม่ได้เป็นส่วนหนึ่งของ public application programming interface (API) ที่รองรับ ให้พึ่งพา façade Document และเนมสเปซ Contracts แทน SystemClock WarningCollector Warning WarningCode WarningSeverity และ DegradationImpact เป็นสมาชิกที่เปิดเผยสู่สาธารณะ

พื้นผิว API

สัญลักษณ์	ชนิด	การมองเห็น	สมาชิกหลัก
NextPDF\Support\SystemClock	final class	public	now(): DateTimeImmutable (PSR-20 ClockInterface)
NextPDF\Support\WarningCollector	final class	public	add(), emit(), addWithPolicy(), getWarnings(), hasWarnings(), hasDegradedParity(), clear()
NextPDF\Support\Warning	final readonly class	public	$code, $severity, $page, $elementType, $featureId, $degradedParity, $message, $impact, $capabilityId
NextPDF\Support\WarningCode	string enum	public	ตัวระบุ NEXTPDF_W_* ที่เสถียร
NextPDF\Support\WarningSeverity	string enum	public	Warning, Degraded
NextPDF\Support\DegradationImpact	string enum	public	Cosmetic, LayoutRisk, SemanticLoss, ComplianceRisk, Blocking
NextPDF\Support\PdfStringEscaper	final readonly class	internal	escapeLiteral(), escapeName() (static)
NextPDF\Support\BinaryBuffer	final class	internal	write(), writeStream(), replaceAt(), extract(), enableStreaming(), getContents()
NextPDF\Support\PdfOperators	final class	internal	ค่าคงที่สตริงรูปแบบของตัวดำเนินการ content-stream

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

อ่านคำเตือนที่รวบรวมไว้หลังสร้างเอกสาร

<?php

declare(strict_types=1);

use NextPDF\Support\WarningCollector;

$collector = new WarningCollector();

// The engine appends warnings during rendering. After generation:
if ($collector->hasWarnings()) {
    foreach ($collector->getWarnings() as $warning) {
        \printf(
            "[%s] page %d: %s\n",
            $warning->code->value,
            $warning->page,
            $warning->message,
        );
    }
}

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

ฉีดนาฬิกาเพื่อทำให้เวลาเป็นแบบดีเทอร์มินิสติก และจัดการคำเตือนแบบ degraded-parity ให้เป็นความล้มเหลวของการ build

<?php

declare(strict_types=1);

use NextPDF\Support\SystemClock;
use NextPDF\Support\WarningCollector;
use Psr\Clock\ClockInterface;

// Production uses the real system clock.
$clock = new SystemClock();
$now = $clock->now();          // DateTimeImmutable
$epoch = $now->getTimestamp(); // int

// In tests, swap in any ClockInterface that returns a fixed instant
// (the parameter is typed to the PSR-20 interface, not SystemClock).
function buildReport(ClockInterface $clock): \DateTimeImmutable
{
    return $clock->now();
}

$collector = new WarningCollector();
// ... run generation ...
if ($collector->hasDegradedParity()) {
    throw new \RuntimeException('Output parity degraded; failing the build.');
}

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

• SystemClock::now() จะส่งคืน DateTimeImmutable ใหม่ในการเรียกแต่ละครั้ง อย่าสันนิษฐานว่าการเรียกสองครั้งจะส่งคืนช่วงเวลาเดียวกัน สำหรับเวลาคงที่ ให้ฉีดนาฬิกาที่หยุดนิ่ง
• WarningCollector อยู่ในหน่วยความจำและเป็นแบบต่ออินสแตนซ์ เป็นช่องทางคำเตือนหลัก เอาต์พุต sidecar แบบ JavaScript Object Notation (JSON) และเอาต์พุต standard error (STDERR) ของ command-line interface (CLI) จะถูกส่งออกที่ขอบเขตเอาต์พุต ไม่ใช่โดยตัว collector เอง
• addWithPolicy() สามารถโยน DegradedException ระหว่างการเรนเดอร์ภายใต้นโยบายแบบเข้มงวด จับข้อยกเว้นนี้ที่ขอบเขตการสร้างหากคุณต้องการเอาต์พุตบางส่วน
• WarningCode มีค่าเป็นสตริงที่เสถียร ให้จับคู่กับเคสของ enum ไม่ใช่ข้อความที่มนุษย์อ่านได้ซึ่งอาจเปลี่ยนแปลงได้
• BinaryBuffer::getLength() เป็น alias โดยเจตนาของ getOffset() เพื่อความเข้ากันได้ของอินเทอร์เฟซสตรีม ทั้งสองส่งคืนจำนวนไบต์เท่ากัน
• ให้ปฏิบัติต่อ PdfStringEscaper BinaryBuffer และ PdfOperators เป็นโครงสร้างพื้นฐานภายใน ส่วนเหล่านี้ไม่ได้อยู่ภายใต้คำมั่นด้านความเสถียรของ public API

ประสิทธิภาพ

SystemClock::now() สร้างออบเจ็กต์หนึ่งตัวและทำงานใน O(1) การ append ของ WarningCollector เป็นการ push เข้า list แบบ amortized O(1) getWarnings() ส่งคืน list ที่รองรับอยู่เบื้องหลัง ในโหมดสตรีมมิง BinaryBuffer จะเก็บหน่วยความจำไว้จนถึงเกณฑ์ maxmemory (ค่าเริ่มต้น 2 MB) ก่อนจะ spill ลงดิสก์ ซึ่งช่วยให้หน่วยความจำสูงสุดคงที่สำหรับเอกสารขนาดใหญ่ performance_budget เริ่มต้นสำหรับหน้าอ้างอิงนี้คือ wall_ms: 1500, peak_mb: 64

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

ใช้พื้นผิวนาฬิกาเพื่อขจัดความไม่เป็นดีเทอร์มินิสติกของ wall-clock ออกจากเอาต์พุตที่มีการลงลายเซ็นและการประทับเวลา โดยฉีดนาฬิกาคงที่ควบคู่กับ Config::deterministic PdfStringEscaper เป็นตัว escape ที่ตรวจสอบได้เพียงตัวเดียวสำหรับเอาต์พุตสตริงและชื่อของ PDF ให้ส่งการปล่อยสตริงทั้งหมดผ่านตัวนี้ เพื่อป้องกันการแทรกเนื้อหาผ่านวงเล็บหรือตัวคั่นที่ไม่ได้ escape ในข้อความที่ผู้ใช้ให้มา คำเตือนอาจมีรายละเอียดที่ได้มาจากเอกสาร เช่น ชนิดองค์ประกอบและ feature id ให้ scrub เอาต์พุตคำเตือนก่อนส่งต่อไปยัง log sink ที่มีความน่าเชื่อถือต่ำ

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

ข้อกำหนด	อนุประโยค	หัวข้อ
PSR-20 (PHP-FIG)	psr_20_clock#2.1	การดำเนินการอ่านของนาฬิกาส่งคืนค่าวันที่และเวลาแบบไม่เปลี่ยนรูป
ISO 32000-2:2020	§7.3.4.2 / §7.3.5	การ escape สตริงแบบลิเทอรัลและออบเจ็กต์ชื่อ (ถอดความ ไม่ได้ยกข้อความ ISO มาอ้างอิงโดยตรง ไม่มีการ pin chunk)

SystemClock ใช้งาน ClockInterface ของ PSR-20 ตัว escape เป็นไปตามกฎอักขระของสตริงแบบลิเทอรัลและออบเจ็กต์ชื่อของ PDF ข้อความ ISO ถูกถอดความภายใต้นโยบายการอ้างอิงของไซต์ ไม่มีการ pin chunk แบบยกมาตรงตัว

ดูเพิ่มเติม

• /modules/core/exception/ — DegradedException ที่เกิดจาก addWithPolicy()
• /modules/core/contracts/ — DegradationPolicy, Capability
• /modules/core/observability/ — การส่งต่อคำเตือนและเมตริก
• /modules/core/config/ — Config::deterministic จับคู่กับนาฬิกา
• /modules/core/writer/ — ผู้บริโภคภายในของ BinaryBuffer และ PdfOperators

อภิธานศัพท์: PSR-20 · นโยบายการลดทอนคุณภาพ · ออบเจ็กต์ค่า