Config: configurazione immutabile del documento

In breve

Config è l’oggetto di configurazione immutabile del documento. Ogni modifica di un’impostazione restituisce una nuova istanza tramite un wither tipizzato, quindi la configurazione può essere condivisa in sicurezza tra documenti e worker. NextPdfConfig è una classe statica distinta che contiene i limiti di sicurezza del parser CSS a livello di processo.

Installazione

composer require nextpdf/core:^3

Entrambe le classi fanno parte del pacchetto core. Config è disponibile dalla versione 1.7.0. NextPdfConfig è disponibile dalla versione 2.2.0.

Panoramica concettuale

Config è una classe final readonly contrassegnata con #[DisallowDynamicProperties]. Contiene solo scalari e value object final readonly, quindi l’intero grafo degli oggetti è profondamente immutabile. Non esiste un setter generico with(string, mixed). Ogni mutazione passa da un wither tipizzato dedicato. I wither sono 19 — withPageSize(), withMargins(), withCompress(), fino a withOutputColorProfile() — e ciascuno ricostruisce l’oggetto con argomenti denominati. La ricostruzione con argomenti denominati è una scelta deliberata. L’aggiunta di un parametro del costruttore non sposta mai silenziosamente un argomento posizionale in un wither esistente. Un test di compatibilità blocca l’elenco dei metodi pubblici e il numero di parametri tramite reflection. Qualsiasi scostamento nelle firme fa fallire la CI.

Il costruttore espone una superficie di configurazione con valori predefiniti sicuri:

Parametro	Tipo	Valore predefinito
`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`

Tre impostazioni prevedono limiti sui valori. retainedNodeBudget accetta l’intervallo chiuso [5_000, 100_000] (costanti RETAINED_NODE_BUDGET_MIN, RETAINED_NODE_BUDGET_MAX, predefinita RETAINED_NODE_BUDGET_DEFAULT). withRetainedNodeBudget() genera InvalidArgumentException al di fuori di tale intervallo. effectiveRetainedNodeBudget() restituisce 0 in modalità streaming. Negli altri casi, riconduce il valore all’interno dell’intervallo come controllo di difesa in profondità contro la costruzione posizionale diretta. validate() applica gli invarianti tra campi che i wither per singolo campo non possono rilevare isolatamente. CssLayoutMode::Auto è riservato e genera NotImplementedException. CssRenderingMode::Safe combinato con CssLayoutMode::Retained genera IncompatibleRenderingModeException. auditCollector è il raccoglitore dei report di audit fornito dal chiamante. Viene utilizzato solo quando cssRenderingMode è CssRenderingMode::Audit, dove alimenta un blocco XMP nextpdfAudit privato; nelle altre modalità di rendering viene ignorato.

NextPdfConfig copre un ambito diverso. È un’utilità statica non istanziabile che contiene i limiti del parser CSS a livello di processo. I limiti riguardano il numero massimo di byte del foglio di stile (predefinito 512 KB) e la profondità massima di annidamento CSS (predefinita 8). Sono confini di sicurezza contro l’esaurimento delle risorse dovuto a input ostile, non preferenze per singolo documento. Per questo motivo sono statici. I setter impongono un valore minimo (max(1024, …) byte, profondità max(1, …)). resetDefaults() è contrassegnato come @internal solo per l’uso nei test.

Superficie dell’API

Simbolo	Tipologia	Membri principali
`NextPDF\Core\Config`	classe final readonly	21 parametri del costruttore; 19 wither tipizzati; `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`	classe final	`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.

Esempio di codice — Avvio rapido

Creare una configurazione a partire dai valori predefiniti e modificare due impostazioni.

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

Esempio di codice — Produzione

Comporre una configurazione deterministica e convalidata e restringere i limiti CSS a livello di processo per input non attendibile.

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

Casi limite e insidie

Config non applica regole tra campi finché non si chiama validate(). Un wither non può rilevare da solo un conflitto Safe + Retained; chiamare validate() prima della generazione.
withRetainedNodeBudget() è l’unico wither che genera un’eccezione in base al proprio input (InvalidArgumentException al di fuori di [5_000, 100_000]).
effectiveRetainedNodeBudget() restituisce 0 in modalità streaming, a indicare che «il budget di livello 1 non si applica» — non che «non sono ammessi nodi».
withLayoutTelemetryCollector() e withTelemetryEnabled() sono indipendenti. Associare un raccoglitore senza abilitare la telemetria lo predispone per un canary successivo. Abilitare la telemetria senza un raccoglitore è valido e non ha alcun effetto.
NextPdfConfig è statico e a livello di processo. Una modifica riguarda ogni documento del processo finché non viene ripristinata. È un confine di sicurezza, non una preferenza per singolo documento. Tenerlo fuori dai percorsi di mutazione della singola richiesta.
NextPdfConfig::resetDefaults() è @internal. Non va chiamato nel codice di produzione.

Prestazioni

Un wither alloca un nuovo Config e copia i riferimenti ai value object esistenti. L’operazione è O(1) rispetto al numero di impostazioni e non esegue alcuna copia profonda, perché ogni valore contenuto è a sua volta immutabile. Gli accessor di NextPdfConfig sono letture O(1) di campi statici. Il performance_budget predefinito per questa pagina di riferimento è wall_ms: 1500, peak_mb: 64.

Note sulla sicurezza

NextPdfConfig esiste per delimitare l’uso delle risorse da parte del parser. Il limite predefinito di 512 KB per il foglio di stile e il limite di annidamento a profondità 8 proteggono dal denial-of-service causato da CSS patologicamente grande o profondamente annidato. Ridurre entrambi i limiti quando l’origine del foglio di stile non è attendibile. Config::cryptoPolicy contiene una CryptoPolicyInterface per applicare i criteri crittografici (ad esempio, un profilo FIPS). È null per impostazione predefinita e viene impostata tramite withCryptoPolicy(). Config::deterministic controlla timestamp e identificatori fissi per un output identico a livello di byte ed è necessario per build riproducibili.

Conformità

Questo modulo è la configurazione del motore e non riporta alcuna citazione di standard normativi. Le impostazioni che determinano il comportamento conforme agli standard — outputColorProfile (emissione di OutputIntent), cryptoPolicy (FIPS), deterministic (build riproducibili) — sono documentate con riferimento alle relative clausole nei moduli che le emettono.

Vedere anche

/modules/core/document/ — il consumatore di Config
/modules/core/valueobjects/ — PageSize, Margin utilizzati da Config
/modules/core/contracts/ — CryptoPolicyInterface, DegradationPolicy
/modules/core/event/ — Config trasportato su DocumentCreatedEvent
/modules/core/exception/ — InvalidConfigException, NotImplementedException

Glossario: wither tipizzato · criterio di degradazione · value object