Config: configuração imutável do documento

Em resumo

Config é um objeto imutável de configuração do documento. Quando você altera uma configuração, um wither tipado retorna uma nova instância, permitindo compartilhar a configuração com segurança entre documentos e workers. NextPdfConfig é uma classe estática separada que armazena os limites de segurança do parser de Cascading Style Sheets (CSS) válidos para todo o processo.

Instalação

composer require nextpdf/core:^3

As duas classes fazem parte do pacote core. Config existe desde a versão 1.7.0. NextPdfConfig existe desde a versão 2.2.0.

Visão geral conceitual

Config é uma classe final readonly marcada com #[DisallowDynamicProperties]. Ela armazena apenas escalares e value objects final readonly, de modo que o grafo completo seja profundamente imutável. Ela não fornece um setter genérico with(string, mixed). Cada mutação usa um wither tipado dedicado. São 19 no total: withPageSize(), withMargins(), withCompress(), até withOutputColorProfile(), e cada um reconstrói o objeto com argumentos nomeados. A reconstrução com argumentos nomeados é intencional. Quando você adiciona um parâmetro ao construtor, um wither existente nunca desloca silenciosamente um argumento posicional. Um teste de compatibilidade usa reflexão para fixar a lista de métodos públicos e a contagem de parâmetros. Qualquer desvio de assinatura faz a integração contínua (CI) falhar.

O construtor expõe a superfície de configuração com padrões seguros:

Parâmetro	Tipo	Padrão
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

Três configurações impõem limites de valor. retainedNodeBudget aceita o intervalo fechado [5_000, 100_000] (constantes RETAINED_NODE_BUDGET_MIN, RETAINED_NODE_BUDGET_MAX, padrão RETAINED_NODE_BUDGET_DEFAULT). withRetainedNodeBudget() lança InvalidArgumentException fora desse intervalo. effectiveRetainedNodeBudget() retorna 0 no modo de streaming. Caso contrário, ela recoloca o valor dentro do intervalo como uma verificação de defesa em profundidade contra a construção posicional direta. validate() impõe invariantes entre campos que os withers por campo não conseguem enxergar isoladamente. CssLayoutMode::Auto é reservado e levanta NotImplementedException. CssRenderingMode::Safe com CssLayoutMode::Retained levanta IncompatibleRenderingModeException. auditCollector é o coletor de relatórios de auditoria fornecido pelo chamador. Ele é usado apenas quando cssRenderingMode é CssRenderingMode::Audit e, nesse caso, alimenta um bloco privado nextpdfAudit do Extensible Metadata Platform (XMP). Os demais modos de renderização o ignoram.

NextPdfConfig resolve uma preocupação separada. Ele é um utilitário estático não instanciável que mantém os limites do parser de CSS válidos para todo o processo. Os limites são o máximo de bytes da folha de estilo (padrão 512 KB) e a profundidade máxima de aninhamento de CSS (padrão 8). Essas são fronteiras de segurança contra exaustão de recursos por entrada hostil, não preferências por documento. Por essa razão, elas são estáticas. Os setters aplicam um piso (max(1024, …) bytes, max(1, …) de profundidade). resetDefaults() é marcado como @internal apenas para uso em testes.

Superfície da API

Símbolo	Tipo	Membros principais
NextPDF\Core\Config	classe final readonly	21 parâmetros de construtor; 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	classe 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.

Exemplo de código — Início rápido

Comece com os padrões e ajuste duas configurações.

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

Exemplo de código — Produção

Componha uma configuração determinística e validada, e restrinja os limites de CSS válidos para todo o processo quando a entrada não for confiável.

<?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 extremos e pegadinhas

• Config não impõe nenhuma regra entre campos até que você chame validate(). Um wither não consegue detectar sozinho um conflito de Safe + Retained; chame validate() antes da geração.
• withRetainedNodeBudget() é o único wither que lança exceção com base na própria entrada (InvalidArgumentException fora de [5_000, 100_000]).
• effectiveRetainedNodeBudget() retorna 0 no modo de streaming. Isso sinaliza “o orçamento de Tier-1 não se aplica”, não “nenhum nó permitido”.
• withLayoutTelemetryCollector() e withTelemetryEnabled() são independentes. Conectar um coletor sem habilitar a telemetria o deixa pronto para um canary posterior. Habilitar a telemetria sem um coletor é válido e não tem efeito.
• NextPdfConfig é estático e válido para todo o processo. Uma alteração afeta todos os documentos do processo até ser redefinida. Ele é uma fronteira de segurança, não uma preferência por documento. Mantenha-o fora dos caminhos de mutação por requisição.
• NextPdfConfig::resetDefaults() é @internal. Não o chame em código de produção.

Desempenho

Um wither aloca um novo Config e copia referências para value objects existentes. A operação é O(1) em relação ao número de configurações e não realiza nenhuma cópia profunda, porque todo valor mantido é imutável. Os acessores de NextPdfConfig são leituras de campo estático, O(1). O performance_budget padrão para esta página de referência é wall_ms: 1500, peak_mb: 64.

Notas de segurança

NextPdfConfig limita o uso de recursos do parser. O limite padrão de 512 KB para folha de estilo e o limite de aninhamento com profundidade 8 protegem contra negação de serviço decorrente de CSS patologicamente grande ou profundamente aninhado. Reduza ambos os limites quando a origem da folha de estilo não for confiável. Config::cryptoPolicy carrega uma CryptoPolicyInterface para imposição de política criptográfica, como um perfil dos Federal Information Processing Standards (FIPS). Ela é null por padrão e é definida por meio de withCryptoPolicy(). Config::deterministic controla timestamps e identificadores fixos para saída byte-idêntica e é obrigatório para builds reproduzíveis.

Conformidade

Este módulo configura o engine e não carrega nenhuma citação normativa de norma. As configurações que orientam comportamento relacionado a normas, incluindo outputColorProfile (emissão de OutputIntent), cryptoPolicy (FIPS) e deterministic (builds reproduzíveis), são documentadas em relação às suas cláusulas nos módulos que as emitem.

Veja também

• /modules/core/document/ — o consumidor de Config
• /modules/core/valueobjects/ — PageSize, Margin usados por Config
• /modules/core/contracts/ — CryptoPolicyInterface, DegradationPolicy
• /modules/core/event/ — Config transportado em DocumentCreatedEvent
• /modules/core/exception/ — InvalidConfigException, NotImplementedException

Glossário: wither tipado · política de degradação · objeto de valor