Support: utilitas umum + Clock + Sleeper

Sekilas

Modul Support berisi utilitas umum yang digunakan secara internal oleh engine. Modul ini juga mengekspos permukaan publik yang kecil: jam sistem PHP Standards Recommendation 20 (PSR-20), pipeline pengumpulan peringatan, dan primitif serialisasi Portable Document Format (PDF). Sebagian besar namespace ini merupakan infrastruktur internal. Halaman ini mendokumentasikan bagian yang dapat Anda andalkan, sekaligus menandai bagian yang hanya ditujukan untuk penggunaan internal.

Pemasangan

composer require nextpdf/core:^3

Tinjauan konseptual

Clock (PSR-20). SystemClock mengimplementasikan Psr\Clock\ClockInterface. Metode now() mengembalikan waktu saat ini sebagai DateTimeImmutable. Model PSR-20 mendefinisikan antarmuka jam dengan satu operasi baca, yang mengembalikan waktu saat ini sebagai nilai tanggal-waktu immutable (PSR-20 psr_20_clock#2.1). SystemClock adalah jam standar; engine menggunakannya saat Anda tidak menyuntikkan jam. Untuk waktu tetap dalam pengujian, suntikkan jam beku yang mengimplementasikan antarmuka yang sama. Pasangkan jam dengan Config::deterministic bila Anda membutuhkan keluaran yang identik byte demi byte.

Pipeline peringatan. WarningCollector adalah transport utama dalam memori untuk masalah rendering yang tidak fatal. Engine menambahkan satu Warning untuk setiap penurunan kualitas yang deterministik, seperti kolom tabel yang dipampatkan, fon yang tidak teratasi, atau glyph yang hilang. Setelah proses pembuatan, Anda membaca peringatan melalui Document::getWarnings(). Sebuah Warning adalah objek nilai yang immutable. Objek ini memuat sebuah WarningCode, sebuah WarningSeverity (warning atau degraded), halaman, jenis elemen, id fitur, flag degraded-parity, pesan, sebuah DegradationImpact, dan id kemampuan opsional. WarningCode adalah enum berbasis string yang berisi pengidentifikasi stabil. Pengidentifikasi tersebut menggunakan prefiks NEXTPDF_W_, seperti NEXTPDF_W_FONT_UNRESOLVED, sehingga Anda dapat mencocokkannya dengan aman dalam pengujian. addWithPolicy() menegakkan DegradationPolicy yang aktif. Pada kebijakan strict, dampak compliance, semantik, atau blocking memunculkan DegradedException. Pada kebijakan balanced, hanya dampak blocking yang memunculkannya. Kebijakan permissive tidak pernah memunculkan exception.

Primitif PDF. PdfStringEscaper adalah satu-satunya sumber kebenaran untuk escaping string dan name PDF. escapeLiteral() meng-escape karakter yang diwajibkan dalam string literal PDF: reverse solidus, tanda kurung, carriage return (CR), line feed (LF), horizontal tab (HT), backspace (BS), dan form feed (FF). Metode ini juga membuang byte NUL. escapeName() mengodekan secara heksadesimal byte di luar rentang American Standard Code for Information Interchange (ASCII) yang dapat dicetak serta byte dalam himpunan delimiter PDF untuk objek name. BinaryBuffer adalah akumulator biner yang dioptimalkan untuk menulis objek dan stream PDF. Dalam mode streaming, buffer ini meluap ke handle php://temp untuk dokumen besar. Buffer ini juga mendukung operasi byte-range yang dibutuhkan oleh penyematan tanda tangan. PdfOperators menyimpan string format operator content-stream untuk path, teks, graphics state, dan fon. Lapisan penggambaran dan parser menggunakan string-string tersebut bersama.

BinaryBuffer, PdfOperators, dan sebagian besar anggota lain di NextPDF\Support\ adalah infrastruktur internal. Lapisan writer dan penggambaran menggunakan komponen-komponen ini. Halaman ini mendokumentasikannya demi kelengkapan dan audit. Komponen-komponen tersebut bukan bagian dari application programming interface (API) publik yang didukung. Andalkan fasad Document dan namespace Contracts sebagai gantinya. SystemClock, WarningCollector, Warning, WarningCode, WarningSeverity, dan DegradationImpact adalah anggota yang terekspos publik.

Permukaan API

Simbol	Jenis	Visibilitas	Anggota utama
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	pengidentifikasi NEXTPDF_W_* yang stabil
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	konstanta format string operator content-stream

Contoh kode — Mulai cepat

Baca peringatan yang terkumpul setelah proses pembuatan.

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

Contoh kode — Produksi

Suntikkan jam agar waktu menjadi deterministik, lalu perlakukan peringatan degraded-parity sebagai kegagalan 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.');
}

Kasus tepi & jebakan

• SystemClock::now() mengembalikan DateTimeImmutable baru pada setiap pemanggilan. Jangan berasumsi dua pemanggilan akan mengembalikan saat yang sama. Untuk waktu tetap, suntikkan jam beku.
• WarningCollector bersifat dalam memori dan per-instance. Collector ini adalah kanal peringatan utama. Keluaran sidecar JavaScript Object Notation (JSON) dan standard error (STDERR) command-line interface (CLI) dipancarkan pada batas keluaran, bukan oleh collector itu sendiri.
• addWithPolicy() dapat memunculkan DegradedException di tengah rendering di bawah kebijakan strict. Tangkap exception tersebut pada batas pembuatan jika Anda membutuhkan keluaran parsial.
• Nilai WarningCode adalah string yang stabil. Cocokkan berdasarkan case enum, bukan berdasarkan teks pesan, yang dapat dibaca manusia dan dapat berubah.
• BinaryBuffer::getLength() adalah alias yang disengaja dari getOffset() untuk paritas antarmuka stream. Keduanya mengembalikan jumlah byte yang sama.
• Perlakukan PdfStringEscaper, BinaryBuffer, dan PdfOperators sebagai infrastruktur internal. Komponen-komponen tersebut tidak dicakup oleh janji stabilitas API publik.

Kinerja

SystemClock::now() membuat satu objek dan berjalan dalam O(1). Menambahkan item ke WarningCollector adalah operasi push list O(1) yang teramortisasi. getWarnings() mengembalikan list pendukungnya. Dalam mode streaming, BinaryBuffer menahan data di memori sampai ambang batas maxmemory-nya (standar 2 MB) sebelum meluap ke disk, sehingga puncak memori tetap datar untuk dokumen besar. performance_budget standar untuk halaman referensi ini adalah wall_ms: 1500, peak_mb: 64.

Catatan keamanan

Gunakan permukaan jam untuk menghilangkan nondeterminisme wall-clock dari keluaran yang ditandatangani dan diberi cap waktu dengan menyuntikkan jam tetap bersama Config::deterministic. PdfStringEscaper adalah satu-satunya escaper yang dapat diaudit untuk keluaran string dan name PDF. Salurkan semua emisi string melaluinya untuk mencegah injeksi konten lewat tanda kurung atau delimiter yang tidak di-escape dalam teks yang dipasok pengguna. Peringatan dapat membawa detail yang berasal dari dokumen, seperti jenis elemen dan id fitur. Sanitasi keluaran peringatan sebelum Anda meneruskannya ke log sink dengan tingkat kepercayaan rendah.

Konformansi

Spesifikasi	Klausa	Topik
PSR-20 (PHP-FIG)	psr_20_clock#2.1	Operasi baca jam mengembalikan tanggal-waktu yang immutable
ISO 32000-2:2020	§7.3.4.2 / §7.3.5	Escaping string literal dan objek name (diparafrasekan; prosa ISO tidak dikutip, tidak ada chunk yang dipin)

SystemClock mengimplementasikan PSR-20 ClockInterface. Escaper ini mengikuti aturan karakter string literal dan objek name PDF. Teks ISO diparafrasekan menurut kebijakan kutipan situs; tidak ada chunk verbatim yang dipin.

Lihat juga

• /modules/core/exception/ — DegradedException yang dimunculkan oleh addWithPolicy()
• /modules/core/contracts/ — DegradationPolicy, Capability
• /modules/core/observability/ — penerusan peringatan dan metrik
• /modules/core/config/ — Config::deterministic dipasangkan dengan jam
• /modules/core/writer/ — konsumen internal untuk BinaryBuffer dan PdfOperators

Glosarium: PSR-20 · kebijakan penurunan kualitas · objek nilai