Config: configuración inmutable del documento

Visión general

Config es el objeto inmutable de configuración del documento. Cada cambio en un ajuste devuelve una nueva instancia mediante un wither tipado, por lo que la configuración puede compartirse de forma segura entre documentos y workers. NextPdfConfig es una clase estática independiente que contiene los límites de seguridad del analizador de CSS para todo el proceso.

Instalación

composer require nextpdf/core:^3

Ambas clases están incluidas en el paquete del núcleo. Config existe desde la versión 1.7.0. NextPdfConfig existe desde la versión 2.2.0.

Visión conceptual

Config es una clase final readonly marcada como #[DisallowDynamicProperties]. Solo contiene escalares y value objects final readonly, de modo que todo el grafo de objetos es profundamente inmutable. No hay un setter genérico with(string, mixed). Cada mutación tiene un wither tipado dedicado. Hay 19 de ellos — withPageSize(), withMargins(), withCompress(), hasta withOutputColorProfile() — y cada uno reconstruye el objeto con argumentos con nombre. La reconstrucción mediante argumentos con nombre es deliberada. Añadir un parámetro al constructor nunca desplaza en silencio un argumento posicional en un wither existente. Una prueba de compatibilidad fija mediante reflexión la lista de métodos públicos y el número de parámetros. Cualquier desviación de la firma hace que falle la CI.

El constructor expone la superficie de configuración con valores predeterminados seguros:

Parámetro	Tipo	Predeterminado
`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`

Tres ajustes imponen límites de valor. retainedNodeBudget acepta el rango cerrado [5_000, 100_000] (constantes RETAINED_NODE_BUDGET_MIN, RETAINED_NODE_BUDGET_MAX, predeterminado RETAINED_NODE_BUDGET_DEFAULT). withRetainedNodeBudget() lanza InvalidArgumentException fuera de ese rango. effectiveRetainedNodeBudget() devuelve 0 en el modo de streaming. En caso contrario, vuelve a recortar el valor al rango como comprobación de defensa en profundidad frente a la construcción posicional directa. validate() aplica invariantes entre campos que los withers específicos de campo no pueden ver de forma aislada. CssLayoutMode::Auto está reservado y genera NotImplementedException. CssRenderingMode::Safe combinado con CssLayoutMode::Retained genera IncompatibleRenderingModeException. auditCollector es el recopilador de informes de auditoría proporcionado por quien llama. Solo se consume cuando cssRenderingMode es CssRenderingMode::Audit, donde alimenta un bloque XMP privado nextpdfAudit; en los demás modos de renderizado se ignora.

NextPdfConfig tiene una responsabilidad distinta. Es una utilidad estática no instanciable que contiene los límites del analizador de CSS para todo el proceso. Estos límites son el tamaño máximo en bytes de la hoja de estilos (512 KB de forma predeterminada) y la profundidad máxima de anidamiento de CSS (8 de forma predeterminada). Son límites de seguridad frente al agotamiento de recursos provocado por entradas hostiles, no preferencias por documento. Por eso son estáticos. Los setters aplican un mínimo (max(1024, …) bytes, max(1, …) de profundidad). resetDefaults() está marcado como @internal y se reserva para pruebas.

Superficie de la API

Símbolo	Tipo	Miembros clave
`NextPDF\Core\Config`	clase final readonly	21 parámetros del constructor; 19 withers tipados; `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`	clase final	`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.

Ejemplo de código — Inicio rápido

Crear una configuración a partir de los valores predeterminados y ajustar dos opciones.

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

Ejemplo de código — Producción

Componer una configuración determinista y validada, y ajustar los límites de CSS para todo el proceso frente a entradas no confiables.

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

Casos límite y trampas

Config no aplica ninguna regla entre campos hasta llamar a validate(). Un wither no puede detectar por sí solo un conflicto entre Safe y Retained; llamar a validate() antes de la generación.
withRetainedNodeBudget() es el único wither que lanza una excepción en función de su propia entrada (InvalidArgumentException fuera de [5_000, 100_000]).
effectiveRetainedNodeBudget() devuelve 0 en el modo de streaming, lo que indica «the Tier-1 budget does not apply» y no «no nodes allowed».
withLayoutTelemetryCollector() y withTelemetryEnabled() son independientes. Conectar un collector sin habilitar la telemetría deja la configuración preparada para un canary posterior. Habilitar la telemetría sin un collector es válido y no hace nada.
NextPdfConfig es estático y abarca todo el proceso. Un cambio afecta a todos los documentos del proceso hasta que se restablece. Es un límite de seguridad, no una preferencia por documento. Mantenerlo fuera de las rutas de mutación por solicitud.
NextPdfConfig::resetDefaults() es @internal. No debe llamarse en código de producción.

Rendimiento

Un wither crea un nuevo Config y copia las referencias a los value objects existentes. Esto es O(1) en el número de ajustes y no realiza ninguna copia profunda, porque cada valor contenido también es inmutable. Los accesores de NextPdfConfig son lecturas O(1) de campos estáticos. El performance_budget predeterminado de esta página de referencia es wall_ms: 1500, peak_mb: 64.

Notas de seguridad

NextPdfConfig existe para acotar el uso de recursos del analizador. El límite predeterminado de 512 KB para la hoja de estilos y el límite de profundidad de anidamiento 8 protegen frente a la denegación de servicio causada por CSS patológicamente grande o profundamente anidado. Reducir ambos límites cuando el origen de la hoja de estilos no sea confiable. Config::cryptoPolicy contiene una CryptoPolicyInterface para aplicar la política criptográfica (por ejemplo, un perfil FIPS). Es null de forma predeterminada y se establece mediante withCryptoPolicy(). Config::deterministic controla las marcas de tiempo y los identificadores fijos para producir una salida idéntica byte a byte y es obligatorio para las compilaciones reproducibles.

Conformidad

Este módulo es configuración del motor y no incluye ninguna cita normativa de estándares. Los ajustes que rigen el comportamiento respecto de los estándares — outputColorProfile (emisión de OutputIntent), cryptoPolicy (FIPS), deterministic (compilaciones reproducibles) — se documentan junto con sus cláusulas en los módulos que los emiten.

Véase también

/modules/core/document/ — el consumidor de Config
/modules/core/valueobjects/ — PageSize, Margin que utiliza Config
/modules/core/contracts/ — CryptoPolicyInterface, DegradationPolicy
/modules/core/event/ — Config transportado en DocumentCreatedEvent
/modules/core/exception/ — InvalidConfigException, NotImplementedException

Glosario: typed wither · degradation policy · value object