Config: unveränderliche Dokumentkonfiguration

Auf einen Blick

Config ist das unveränderliche Objekt für die Dokumentkonfiguration. Jede Änderung einer Einstellung erzeugt über einen typisierten Wither eine neue Instanz, sodass die Konfiguration gefahrlos über Dokumente und Worker hinweg gemeinsam genutzt werden kann. NextPdfConfig ist eine separate statische Klasse für prozessweite Sicherheitslimits des CSS-Parsers.

Installation

composer require nextpdf/core:^3

Beide Klassen werden mit dem Core-Paket ausgeliefert. Config ist seit 1.7.0 verfügbar. NextPdfConfig ist seit 2.2.0 verfügbar.

Konzeptioneller Überblick

Config ist eine final readonly-Klasse und mit #[DisallowDynamicProperties] markiert. Sie enthält ausschließlich Skalare und final readonly-Value-Objects, sodass der gesamte Objektgraph durchgängig unveränderlich ist. Es gibt keinen generischen with(string, mixed)-Setter. Jede Mutation hat einen eigenen typisierten Wither. Es gibt 19 davon — withPageSize(), withMargins(), withCompress(), bis hin zu withOutputColorProfile() — und jeder rekonstruiert das Objekt mit benannten Argumenten. Diese Rekonstruktion mit benannten Argumenten ist bewusst gewählt. Das Hinzufügen eines Konstruktorparameters verschiebt niemals stillschweigend ein Positionsargument in einem bestehenden Wither. Ein Kompatibilitätstest hält die öffentliche Methodenliste und die Parameteranzahl per Reflection fest. Signaturabweichungen lassen die CI fehlschlagen.

Der Konstruktor stellt die Konfigurationsfläche mit sicheren Standardwerten bereit:

Parameter	Typ	Standard
`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`

Drei Einstellungen haben Wertegrenzen. retainedNodeBudget akzeptiert den geschlossenen Bereich [5_000, 100_000] (Konstanten RETAINED_NODE_BUDGET_MIN, RETAINED_NODE_BUDGET_MAX, Standard RETAINED_NODE_BUDGET_DEFAULT). withRetainedNodeBudget() löst außerhalb dieses Bereichs eine InvalidArgumentException aus. effectiveRetainedNodeBudget() liefert im Streaming-Modus 0. Andernfalls begrenzt es den Wert als zusätzliche Verteidigungsebene gegen direkte positionsbasierte Konstruktoraufrufe wieder auf diesen Bereich. validate() erzwingt feldübergreifende Invarianten, die die feldweisen Wither isoliert nicht prüfen können. CssLayoutMode::Auto ist reserviert und löst eine NotImplementedException aus. CssRenderingMode::Safe in Kombination mit CssLayoutMode::Retained löst eine IncompatibleRenderingModeException aus. auditCollector ist der vom Aufrufer bereitgestellte Collector für Audit-Berichte. Er wird nur verwendet, wenn cssRenderingMode gleich CssRenderingMode::Audit ist; dann steuert er einen privaten nextpdfAudit-XMP-Block. In anderen Rendering-Modi wird er ignoriert.

NextPdfConfig betrifft einen anderen Bereich. Es ist eine nicht instanziierbare statische Utility-Klasse, die prozessweite Limits des CSS-Parsers verwaltet. Die Limits betreffen die maximale Stylesheet-Größe (Standard 512 KB) und die maximale CSS-Verschachtelungstiefe (Standard 8). Es handelt sich um Sicherheitsgrenzen gegen Ressourcenerschöpfung durch feindliche Eingaben, nicht um dokumentbezogene Präferenzen. Aus diesem Grund sind sie statisch. Setter begrenzen nach unten auf einen Mindestwert (max(1024, …) Bytes, max(1, …) Tiefe). resetDefaults() ist mit @internal markiert und nur für Tests gedacht.

API-Oberfläche

Symbol	Art	Wichtige Member
`NextPDF\Core\Config`	final readonly class	21 Konstruktorparameter; 19 typisierte Wither; `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 class	`setMaxCssBytes()`, `getMaxCssBytes()`, `setMaxCssNestingDepth()`, `getMaxCssNestingDepth()`, `resetDefaults()` (`@internal`)

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

Codebeispiel — Schnellstart

Erstellen Sie eine Konfiguration aus den Standardwerten und passen Sie zwei Einstellungen an.

<?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.

Codebeispiel — Produktion

Stellen Sie eine deterministische, validierte Konfiguration zusammen und verschärfen Sie die prozessweiten CSS-Limits für nicht vertrauenswürdige Eingaben.

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

Sonderfälle & Fallstricke

Config erzwingt keine feldübergreifenden Regeln, bis Sie validate() aufrufen. Ein Wither kann einen Konflikt aus Safe + Retained nicht von selbst erkennen; rufen Sie vor der Generierung validate() auf.
withRetainedNodeBudget() ist der einzige Wither, der für seine eigene Eingabe eine Ausnahme auslöst (InvalidArgumentException außerhalb von [5_000, 100_000]).
effectiveRetainedNodeBudget() liefert im Streaming-Modus 0 und signalisiert damit „das Tier-1-Budget gilt nicht“ — nicht „keine Knoten erlaubt“.
withLayoutTelemetryCollector() und withTelemetryEnabled() sind unabhängig voneinander. Einen Collector einzubinden, ohne Telemetrie zu aktivieren, stellt ihn für einen späteren Canary bereit. Telemetrie ohne Collector zu aktivieren ist gültig und bleibt ein No-op.
NextPdfConfig ist prozessweit und statisch. Eine Änderung betrifft jedes Dokument im Prozess, bis sie zurückgesetzt wird. Dabei handelt es sich um eine Sicherheitsgrenze, nicht um eine dokumentbezogene Präferenz. Halten Sie es aus den Mutationspfaden pro Anfrage heraus.
NextPdfConfig::resetDefaults() ist @internal. Rufen Sie es nicht in Produktionscode auf.

Performance

Ein Wither erzeugt ein neues Config und kopiert Referenzen auf die bestehenden Value-Objects. Das ist O(1) bezogen auf die Anzahl der Einstellungen und führt keine tiefe Kopie aus, weil jeder gehaltene Wert selbst unveränderlich ist. Accessoren von NextPdfConfig sind statische Feldzugriffe und damit O(1). Das Standard-performance_budget für diese Referenzseite ist wall_ms: 1500, peak_mb: 64.

Sicherheitshinweise

NextPdfConfig existiert, um die Ressourcennutzung des Parsers zu begrenzen. Die standardmäßige Obergrenze von 512 KB pro Stylesheet und die Verschachtelungsgrenze mit Tiefe 8 schützen gegen Denial-of-Service durch pathologisch großes oder tief verschachteltes CSS. Senken Sie beide Limits, wenn die Stylesheet-Quelle nicht vertrauenswürdig ist. Config::cryptoPolicy enthält ein CryptoPolicyInterface zur Durchsetzung kryptografischer Richtlinien (zum Beispiel ein FIPS-Profil). Es ist standardmäßig null und wird über withCryptoPolicy() gesetzt. Config::deterministic steuert feste Zeitstempel und Bezeichner für bytegenau identische Ausgaben und ist für reproduzierbare Builds erforderlich.

Konformität

Dieses Modul stellt Engine-Konfiguration bereit und enthält keine normative Standardzitierung. Einstellungen, die das Standardverhalten steuern — outputColorProfile (OutputIntent-Emission), cryptoPolicy (FIPS), deterministic (reproduzierbare Builds) — werden in den Modulen, die sie ausgeben, mit Bezug auf ihre jeweiligen Klauseln dokumentiert.

Siehe auch

/modules/core/document/ — der Konsument von Config
/modules/core/valueobjects/ — PageSize und Margin, verwendet von Config
/modules/core/contracts/ — CryptoPolicyInterface, DegradationPolicy
/modules/core/event/ — Config, transportiert durch DocumentCreatedEvent
/modules/core/exception/ — InvalidConfigException, NotImplementedException

Glossar: typisierter Wither · Degradation Policy · Value Object