Support: gedeelde hulpprogramma's + Clock + Sleeper

In een oogopslag

De Support-module bevat gedeelde hulpprogramma’s die de engine intern gebruikt. Daarnaast biedt de module een klein publiek oppervlak: de systeemklok volgens PHP Standards Recommendation 20 (PSR-20), de pijplijn voor het verzamelen van waarschuwingen en serialisatieprimitieven voor het Portable Document Format (PDF). Het grootste deel van de naamruimte is interne infrastructuur. Deze pagina documenteert de onderdelen waarop je kunt vertrouwen en markeert welke onderdelen uitsluitend voor intern gebruik zijn.

Installatie

composer require nextpdf/core:^3

Conceptueel overzicht

Klok (PSR-20). SystemClock implementeert Psr\Clock\ClockInterface. De methode now() retourneert de huidige tijd als een DateTimeImmutable. Het PSR-20-model definieert een klokinterface met één leesbewerking die de huidige tijd retourneert als een onveranderlijke datum-tijdwaarde (PSR-20 psr_20_clock#2.1). SystemClock is de standaardklok; de engine gebruikt deze als je geen klok injecteert. Injecteer in tests voor een vaste tijd een bevroren klok die dezelfde interface implementeert. Combineer de klok met Config::deterministic als je byte-identieke uitvoer nodig hebt.

Waarschuwingspijplijn. WarningCollector is het belangrijkste in-memory transport voor niet-fatale weergaveproblemen. De engine voegt een Warning toe voor elke deterministische degradatie, zoals een ingekrompen tabelkolom, een niet-geconverteerd lettertype of een ontbrekende glief. Na het genereren lees je waarschuwingen uit via Document::getWarnings(). Een Warning is een onveranderlijk waardeobject. Het bevat een WarningCode, een WarningSeverity (warning of degraded), de pagina, het elementtype, de feature-id, een degraded-parity-vlag, een bericht, een DegradationImpact en een optionele capability-id. WarningCode is een string-backed enum van stabiele identifiers. De identifiers gebruiken de prefix NEXTPDF_W_, zoals NEXTPDF_W_FONT_UNRESOLVED, zodat je ze veilig kunt matchen in tests. addWithPolicy() handhaaft de actieve DegradationPolicy. Bij een strikt beleid gooit een compliance-, semantische of blokkerende impact een DegradedException. Bij een gebalanceerd beleid gooit alleen een blokkerende impact. Een toegeeflijk beleid gooit nooit.

PDF-primitieven. PdfStringEscaper is de enige bron van waarheid voor het escapen van PDF-strings en -namen. escapeLiteral() escapet de tekens die in een PDF-literalstring verplicht moeten worden geëscapet: reverse solidus, haakjes, carriage return (CR), line feed (LF), horizontal tab (HT), backspace (BS) en form feed (FF). Daarnaast verwijdert de methode de NUL-byte. escapeName() codeert bytes buiten het afdrukbare bereik van de American Standard Code for Information Interchange (ASCII) en bytes in de PDF-scheidingstekenset hexadecimaal voor een naamobject. BinaryBuffer is een voor schrijven geoptimaliseerde binaire accumulator voor PDF-objecten en -streams. In streamingmodus wijkt het voor grote documenten uit naar een php://temp-handle. Het ondersteunt ook de byte-range-bewerkingen die nodig zijn voor het inbedden van handtekeningen. PdfOperators bevat de opmaakstrings voor de content-streamoperators voor paden, tekst, grafische status en lettertypen. De teken- en parserlagen delen deze strings.

BinaryBuffer, PdfOperators en het grootste deel van de rest van NextPDF\Support\ zijn interne infrastructuur. De writer- en tekenlagen gebruiken deze onderdelen. Deze pagina documenteert ze voor volledigheid en audit. Ze maken geen deel uit van de ondersteunde publieke application programming interface (API). Vertrouw in plaats daarvan op de Document-façade en de naamruimte Contracts. SystemClock, WarningCollector, Warning, WarningCode, WarningSeverity en DegradationImpact zijn publieke onderdelen.

API-oppervlak

Symbool	Soort	Zichtbaarheid	Belangrijkste leden
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	stabiele NEXTPDF_W_*-identifiers
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	opmaakstringconstanten voor content-streamoperators

Codevoorbeeld — Snelstart

Lees de verzamelde waarschuwingen na het genereren.

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

Codevoorbeeld — Productie

Injecteer een klok om de tijd deterministisch te maken en behandel een degraded-parity-waarschuwing als een buildfout.

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

Randgevallen en valkuilen

• SystemClock::now() retourneert bij elke aanroep een nieuwe DateTimeImmutable. Ga er niet van uit dat twee aanroepen hetzelfde moment retourneren. Injecteer voor een vaste tijd een bevroren klok.
• WarningCollector is in-memory en per instantie. Het is het primaire waarschuwingskanaal. De JavaScript Object Notation (JSON)-sidecar en de standaardfoutuitvoer (STDERR) van de command-line interface (CLI) worden aan de uitvoergrens uitgegeven, niet door de collector zelf.
• addWithPolicy() kan bij een strikt beleid tijdens het renderen een DegradedException gooien. Vang die op bij de generatiegrens als je gedeeltelijke uitvoer nodig hebt.
• De waarden van WarningCode zijn stabiele strings. Match op de enum-case, niet op de menselijk leesbare berichttekst, want die kan veranderen.
• BinaryBuffer::getLength() is een opzettelijke alias van getOffset() voor pariteit met de stream-interface. Beide retourneren hetzelfde aantal bytes.
• Behandel PdfStringEscaper, BinaryBuffer en PdfOperators als interne infrastructuur. Ze vallen niet onder de stabiliteitsbelofte van de openbare API.

Prestaties

SystemClock::now() construeert één object en draait in O(1). Toevoegingen aan WarningCollector zijn geamortiseerde O(1) list-pushes. getWarnings() retourneert de onderliggende lijst. In streamingmodus gebruikt BinaryBuffer geheugen tot aan de maxmemory-drempel (standaard 2 MB) en wijkt daarna uit naar schijf, waardoor het piekgeheugen vlak blijft voor grote documenten. De standaard performance_budget voor deze referentiepagina is wall_ms: 1500, peak_mb: 64.

Beveiligingsnotities

Gebruik het klokoppervlak om nondeterminisme door de wall clock uit ondertekende en van een tijdstempel voorziene uitvoer te verwijderen door een vaste klok te injecteren samen met Config::deterministic. PdfStringEscaper is de enige controleerbare escaper voor PDF-string- en -naamuitvoer. Stuur alle string-uitvoer via deze escaper om contentinjectie via niet-geëscapete haakjes of scheidingstekens in door de gebruiker aangeleverde tekst te voorkomen. Waarschuwingen kunnen uit het document afgeleide details bevatten, zoals elementtypen en feature-id’s. Schoon de waarschuwingsuitvoer op voordat je deze doorstuurt naar een log-sink met een laag vertrouwensniveau.

Conformiteit

Specificatie	Clausule	Onderwerp
PSR-20 (PHP-FIG)	psr_20_clock#2.1	Leesbewerking van klok retourneert een onveranderlijke datum-tijd
ISO 32000-2:2020	§7.3.4.2 / §7.3.5	Escapen van literalstrings en naamobjecten (geparafraseerd; ISO-tekst niet geciteerd, geen chunk gepind)

SystemClock implementeert de PSR-20 ClockInterface. De escaper volgt de tekenregels voor PDF-literalstrings en -naamobjecten. De ISO-tekst is geparafraseerd volgens het citatiebeleid van de site; er is geen verbatim chunk gepind.

Zie ook

• /modules/core/exception/ — DegradedException gegooid door addWithPolicy()
• /modules/core/contracts/ — DegradationPolicy, Capability
• /modules/core/observability/ — doorsturen van waarschuwingen en metrieken
• /modules/core/config/ — Config::deterministic gebruiken samen met de klok
• /modules/core/writer/ — interne consument van BinaryBuffer en PdfOperators

Woordenlijst: PSR-20 · degradatiebeleid · waardeobject