Config: niezmienna konfiguracja dokumentu

W skrócie

Config to niezmienny obiekt konfiguracji dokumentu. Przy zmianie ustawienia typowana metoda wither zwraca nową instancję, dzięki czemu konfigurację można bezpiecznie współdzielić między dokumentami i procesami roboczymi. NextPdfConfig to osobna klasa statyczna, która przechowuje globalne dla procesu limity bezpieczeństwa parsera Cascading Style Sheets (CSS).

Instalacja

composer require nextpdf/core:^3

Obie klasy wchodzą w skład pakietu core. Config istnieje od wersji 1.7.0, a NextPdfConfig od wersji 2.2.0.

Przegląd koncepcyjny

Config to klasa final readonly oznaczona atrybutem #[DisallowDynamicProperties]. Przechowuje wyłącznie skalary i obiekty wartości final readonly, dzięki czemu cały graf obiektów jest głęboko niezmienny. Nie udostępnia ogólnego settera with(string, mixed). Każda zmiana korzysta z dedykowanej, typowanej metody wither. Jest ich 19: withPageSize(), withMargins(), withCompress(), aż po withOutputColorProfile(), a każda rekonstruuje obiekt przy użyciu argumentów nazwanych. Taki sposób rekonstrukcji jest celowy. Po dodaniu parametru konstruktora istniejąca metoda wither nigdy po cichu nie przesuwa argumentu pozycyjnego. Test zgodności wykorzystuje refleksję do ustalenia listy metod publicznych i liczby parametrów. Rozbieżność sygnatur powoduje niepowodzenie ciągłej integracji (CI).

Konstruktor udostępnia zakres konfiguracji z bezpiecznymi wartościami domyślnymi:

Parametr	Typ	Wartość domyślna
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

Trzy ustawienia wymuszają ograniczenia wartości. retainedNodeBudget przyjmuje przedział domknięty [5_000, 100_000] (stałe RETAINED_NODE_BUDGET_MIN, RETAINED_NODE_BUDGET_MAX, domyślnie RETAINED_NODE_BUDGET_DEFAULT). withRetainedNodeBudget() rzuca InvalidArgumentException dla wartości spoza tego przedziału. effectiveRetainedNodeBudget() zwraca 0 w trybie strumieniowym. W przeciwnym razie ponownie przycina wartość do przedziału jako kontrolę defense-in-depth wobec bezpośredniej konstrukcji pozycyjnej. validate() wymusza niezmienniki obejmujące wiele pól, których pojedyncze metody wither nie są w stanie samodzielnie wykryć. CssLayoutMode::Auto jest zarezerwowany i powoduje zgłoszenie NotImplementedException. CssRenderingMode::Safe w połączeniu z CssLayoutMode::Retained powoduje zgłoszenie IncompatibleRenderingModeException. auditCollector to dostarczony przez wywołującego kolektor raportów audytu. Jest używany tylko wtedy, gdy cssRenderingMode ma wartość CssRenderingMode::Audit; steruje wtedy prywatnym blokiem Extensible Metadata Platform (XMP) nextpdfAudit. Pozostałe tryby renderowania go ignorują.

NextPdfConfig realizuje odrębne zadanie. To statyczne narzędzie bez możliwości tworzenia instancji, które przechowuje globalne dla procesu limity parsera CSS. Limity te obejmują maksymalną liczbę bajtów arkusza stylów (domyślnie 512 KB) oraz maksymalną głębokość zagnieżdżenia CSS (domyślnie 8). Są to granice bezpieczeństwa chroniące przed wyczerpaniem zasobów spowodowanym wrogim wejściem, a nie preferencje dla pojedynczego dokumentu. Z tego powodu są statyczne. Settery przycinają wartości od dołu (max(1024, …) bajtów, max(1, …) głębokości). resetDefaults() jest oznaczona jako @internal i służy wyłącznie do użytku w testach.

Powierzchnia API

Symbol	Rodzaj	Najważniejsze składowe
NextPDF\Core\Config	klasa final readonly	21 parametrów konstruktora; 19 typowanych metod 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	klasa final	setMaxCssBytes(), getMaxCssBytes(), setMaxCssNestingDepth(), getMaxCssNestingDepth(), resetDefaults() (@internal)

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

Przykład kodu — szybki start

Zacznij od wartości domyślnych i dostosuj dwa ustawienia.

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

Przykład kodu — produkcja

Zbuduj deterministyczną, zweryfikowaną konfigurację i zaostrz globalne dla procesu limity CSS dla niezaufanego wejścia.

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

Przypadki brzegowe i pułapki

• Config nie wymusza żadnej reguły obejmującej wiele pól, dopóki nie wywołasz validate(). Pojedyncza metoda wither nie jest w stanie samodzielnie wykryć konfliktu Safe + Retained; wywołaj validate() przed generowaniem.
• withRetainedNodeBudget() to jedyna metoda wither, która rzuca wyjątek na podstawie własnego wejścia (InvalidArgumentException poza [5_000, 100_000]).
• effectiveRetainedNodeBudget() zwraca 0 w trybie strumieniowym. Oznacza to „budżet Tier-1 nie ma zastosowania”, a nie „brak dozwolonych węzłów”.
• withLayoutTelemetryCollector() i withTelemetryEnabled() są niezależne. Podłączenie kolektora bez włączenia telemetrii przygotowuje go do późniejszej wersji kanarkowej. Włączenie telemetrii bez kolektora jest prawidłowe i nie ma żadnego efektu.
• NextPdfConfig jest globalny dla procesu i statyczny. Zmiana wpływa na każdy dokument w procesie aż do zresetowania. To granica bezpieczeństwa, a nie preferencja dla pojedynczego dokumentu. Nie używaj go na ścieżkach mutacji wykonywanych dla pojedynczego żądania.
• NextPdfConfig::resetDefaults() jest oznaczona jako @internal. Nie wywołuj jej w kodzie produkcyjnym.

Wydajność

Metoda wither alokuje jeden nowy obiekt Config i kopiuje referencje do istniejących obiektów wartości. Operacja jest O(1) względem liczby ustawień i nie wykonuje głębokiego kopiowania, ponieważ każda przechowywana wartość jest niezmienna. Metody dostępowe NextPdfConfig to odczyty pól statycznych, O(1). Domyślny performance_budget dla tej strony referencyjnej to wall_ms: 1500, peak_mb: 64.

Uwagi dotyczące bezpieczeństwa

NextPdfConfig ogranicza zużycie zasobów przez parser. Domyślny limit 512 KB arkusza stylów oraz limit zagnieżdżenia do głębokości 8 chronią przed atakiem typu „odmowa usługi” spowodowanym patologicznie dużym lub głęboko zagnieżdżonym CSS. Obniż oba limity, gdy źródło arkusza stylów jest niezaufane. Config::cryptoPolicy przechowuje CryptoPolicyInterface do egzekwowania polityki kryptograficznej, takiej jak profil Federal Information Processing Standards (FIPS). Domyślnie ma wartość null i jest ustawiany za pomocą withCryptoPolicy(). Config::deterministic steruje stałymi znacznikami czasu i identyfikatorami dla bajtowo identycznego wyjścia i jest wymagany do powtarzalnych kompilacji.

Zgodność

Ten moduł to konfiguracja silnika i nie odwołuje się do normatywnego standardu. Ustawienia sterujące zachowaniem zgodnym ze standardami, w tym outputColorProfile (emisja OutputIntent), cryptoPolicy (FIPS) oraz deterministic (powtarzalne kompilacje), są udokumentowane względem właściwych klauzul w modułach, które je emitują.

Zobacz także

• /modules/core/document/ — komponent używający Config
• /modules/core/valueobjects/ — PageSize, Margin używane przez Config
• /modules/core/contracts/ — CryptoPolicyInterface, DegradationPolicy
• /modules/core/event/ — Config przekazywany w DocumentCreatedEvent
• /modules/core/exception/ — InvalidConfigException, NotImplementedException

Słownik: typowana metoda wither · polityka degradacji · obiekt wartości