Config: onveranderlijke documentconfiguratie

In een oogopslag

Config is een onveranderlijk documentconfiguratieobject. Wanneer je een instelling wijzigt, geeft een getypeerde wither een nieuwe instantie terug, zodat je de configuratie veilig kunt delen tussen documenten en workers. NextPdfConfig is een aparte statische klasse die procesbrede veiligheidslimieten voor de Cascading Style Sheets-parser (CSS-parser) opslaat.

Installatie

composer require nextpdf/core:^3

Beide klassen maken deel uit van het core-pakket. Config bestaat sinds 1.7.0; NextPdfConfig sinds 2.2.0.

Conceptueel overzicht

Config is een final readonly-klasse met de markering #[DisallowDynamicProperties]. Ze slaat alleen scalars en final readonly-waardeobjecten op, waardoor de volledige graaf diep onveranderlijk is. Ze biedt geen generieke with(string, mixed)-setter. Elke mutatie loopt via een eigen getypeerde wither. Er zijn er 19: withPageSize(), withMargins(), withCompress(), tot en met withOutputColorProfile(), en elke wither reconstrueert het object met benoemde argumenten. Reconstructie met benoemde argumenten is een bewuste keuze. Wanneer je een constructorparameter toevoegt, verschuift een bestaande wither nooit ongemerkt een positioneel argument. Een compatibiliteitstest gebruikt reflectie om de lijst met publieke methoden en het aantal parameters vast te pinnen. Een afwijking in de signatuur laat de continue integratie (CI) mislukken.

De constructor stelt het configuratieoppervlak beschikbaar met veilige standaardwaarden:

Parameter	Type	Standaard
pageSize	PageSize	PageSize(595.276, 841.890, 'A4')
margins	Margin	Margin(10.0, 10.0, 10.0, 10.0)
compress	bool	true
autoPageBreak	bool	true
breakMargin	float	20.0
lang	string (BCP 47)	''
fontsDirectory	string	''
imageCacheBytes	int	52_428_800
deterministic	?DeterministicSettings	null
cryptoPolicy	?CryptoPolicyInterface	null
branding	?BrandingConfig	null
degradationPolicy	DegradationPolicy	Balanced
degradationOverrides	array<string, DegradationPolicy>	[]
cssRenderingMode	CssRenderingMode	Normal
auditCollector	?AuditCollector	null
cssFeatureFlags	?CssFeatureFlags	null
cssLayoutMode	CssLayoutMode	Streaming
retainedNodeBudget	int	50_000
layoutTelemetryCollector	?LayoutTelemetryCollector	null
telemetryEnabled	bool	false
outputColorProfile	OutputColorProfile	DeviceRGB

Drie instellingen dwingen waardegrenzen af. retainedNodeBudget accepteert het gesloten bereik [5_000, 100_000] (constanten RETAINED_NODE_BUDGET_MIN, RETAINED_NODE_BUDGET_MAX, standaard RETAINED_NODE_BUDGET_DEFAULT). withRetainedNodeBudget() werpt InvalidArgumentException buiten dat bereik. effectiveRetainedNodeBudget() geeft 0 terug in streamingmodus. In andere modi klemt ze de waarde terug binnen het bereik, als defense-in-depth-controle tegen directe positionele constructie. validate() dwingt invarianten over meerdere velden af die individuele withers niet zelfstandig kunnen zien. CssLayoutMode::Auto is gereserveerd en roept NotImplementedException op. CssRenderingMode::Safe met CssLayoutMode::Retained roept IncompatibleRenderingModeException op. auditCollector is de door de aanroeper geleverde verzamelaar voor het auditrapport. Ze wordt alleen gebruikt wanneer cssRenderingMode gelijk is aan CssRenderingMode::Audit; dan stuurt ze een privé nextpdfAudit Extensible Metadata Platform-blok (XMP-blok) aan. Andere weergavemodi negeren ze.

NextPdfConfig heeft een afzonderlijke verantwoordelijkheid. Het is een niet-instantieerbare statische hulpklasse die procesbrede limieten voor de CSS-parser bevat. De limieten zijn het maximale aantal stylesheetbytes (standaard 512 KB) en de maximale CSS-nestingdiepte (standaard 8). Dit zijn veiligheidsgrenzen tegen uitputting van bronnen door vijandige invoer, geen voorkeuren per document. Daarom zijn ze statisch. De setters klemmen naar een ondergrens (max(1024, …) bytes, max(1, …) diepte). resetDefaults() is gemarkeerd als @internal en is uitsluitend bedoeld voor testgebruik.

API-oppervlak

Symbool	Soort	Belangrijkste leden
NextPDF\Core\Config	final readonly-klasse	21 constructorparameters; 19 getypeerde withers; validate(), isSafeMode(), isRetainedMode(), effectiveRetainedNodeBudget(), resolveFeatureFlags()
NextPDF\Core\Config::RETAINED_NODE_BUDGET_MIN	const int	5_000
NextPDF\Core\Config::RETAINED_NODE_BUDGET_MAX	const int	100_000
NextPDF\Core\Config::RETAINED_NODE_BUDGET_DEFAULT	const int	50_000
NextPDF\Core\NextPdfConfig	final-klasse	setMaxCssBytes(), getMaxCssBytes(), setMaxCssNestingDepth(), getMaxCssNestingDepth(), resetDefaults() (@internal)

Withers: withPageSize, withMargins, withCompress, withAutoPageBreak, withLang, withFontsDirectory, withImageCacheBytes, withDeterministic, withCryptoPolicy, withBranding, withDegradationPolicy, withDegradationOverride, withCssRenderingMode, withCssFeatureFlags, withCssLayoutMode, withRetainedNodeBudget, withLayoutTelemetryCollector, withTelemetryEnabled, withOutputColorProfile.

Codevoorbeeld — Snelstart

Begin met de standaardwaarden en pas twee instellingen aan.

<?php

declare(strict_types=1);

use NextPDF\Core\Config;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

$config = (new Config())
    ->withPageSize(PageSize::Letter())
    ->withMargins(Margin::uniform(18.0));

// Each wither returns a new instance; the original is unchanged.

Codevoorbeeld — Productie

Stel een deterministische, gevalideerde configuratie samen en scherp de procesbrede CSS-limieten aan voor niet-vertrouwde invoer.

<?php

declare(strict_types=1);

use NextPDF\Core\Config;
use NextPDF\Core\CssRenderingMode;
use NextPDF\Core\NextPdfConfig;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

$config = (new Config())
    ->withPageSize(PageSize::A4())
    ->withMargins(Margin::symmetric(vertical: 20.0, horizontal: 15.0))
    ->withCompress(true)
    ->withCssRenderingMode(CssRenderingMode::Safe);

// Reject mutually exclusive modes before generation starts.
$config->validate();

// Process-wide hardening for hostile stylesheet input.
NextPdfConfig::setMaxCssBytes(262_144);   // 256 KB
NextPdfConfig::setMaxCssNestingDepth(4);

Randgevallen en valkuilen

• Config dwingt geen enkele regel over meerdere velden af totdat je validate() aanroept. Een wither kan een conflict tussen Safe en Retained niet zelf detecteren; roep validate() aan vóór de generatie.
• withRetainedNodeBudget() is de enige wither die werpt op zijn eigen invoer (InvalidArgumentException buiten [5_000, 100_000]).
• effectiveRetainedNodeBudget() geeft 0 terug in streamingmodus. Dat betekent „het Tier-1-budget is niet van toepassing”, niet „geen nodes toegestaan”.
• withLayoutTelemetryCollector() en withTelemetryEnabled() zijn onafhankelijk van elkaar. Een verzamelaar aansluiten zonder telemetrie in te schakelen, zet deze klaar voor een latere canary. Telemetrie inschakelen zonder verzamelaar is geldig en heeft geen effect.
• NextPdfConfig is procesbreed en statisch. Een wijziging beïnvloedt elk document in het proces totdat ze wordt teruggezet. Het is een veiligheidsgrens, geen voorkeur per document. Houd het buiten mutatiepaden per verzoek.
• NextPdfConfig::resetDefaults() is @internal. Roep deze niet aan in productiecode.

Prestaties

Een wither alloceert één nieuwe Config en kopieert verwijzingen naar bestaande waardeobjecten. De bewerking is O(1) ten opzichte van het aantal instellingen en voert geen diepe kopie uit, omdat elke opgeslagen waarde onveranderlijk is. NextPdfConfig-accessors zijn statische veldleesbewerkingen, O(1). Het standaard performance_budget voor deze referentiepagina is wall_ms: 1500, peak_mb: 64.

Beveiligingsnotities

NextPdfConfig begrenst het gebruik van parserbronnen. De standaardlimiet van 512 KB voor stylesheets en de nestinglimiet van diepte 8 beschermen tegen denial-of-service door pathologisch grote of diep geneste CSS. Verlaag beide limieten wanneer de stylesheetbron niet-vertrouwd is. Config::cryptoPolicy draagt een CryptoPolicyInterface voor het afdwingen van cryptografisch beleid, zoals een profiel volgens de Federal Information Processing Standards (FIPS). Ze is standaard null en wordt ingesteld via withCryptoPolicy(). Config::deterministic stuurt vaste tijdstempels en identifiers aan voor byte-identieke uitvoer en is vereist voor reproduceerbare builds.

Conformiteit

Deze module is engineconfiguratie en draagt geen normatieve standaardcitatie. Instellingen die standaardgedrag aansturen, waaronder outputColorProfile (OutputIntent-emissie), cryptoPolicy (FIPS) en deterministic (reproduceerbare builds), worden in de modules die ze emitteren bij hun clausules gedocumenteerd.

Zie ook

• /modules/core/document/ — de consument van Config
• /modules/core/valueobjects/ — PageSize, Margin gebruikt door Config
• /modules/core/contracts/ — CryptoPolicyInterface, DegradationPolicy
• /modules/core/event/ — Config meegedragen op DocumentCreatedEvent
• /modules/core/exception/ — InvalidConfigException, NotImplementedException

Woordenlijst: getypeerde wither · degradatiebeleid · waardeobject