Config: неизменяемая конфигурация документа

Кратко

Config — неизменяемый объект конфигурации документа. Когда вы меняете настройку, типизированный wither-метод возвращает новый экземпляр, поэтому одну конфигурацию можно безопасно использовать в нескольких документах и рабочих процессах. NextPdfConfig — отдельный статический класс: он хранит ограничения безопасности парсера CSS, действующие на весь процесс.

Установка

composer require nextpdf/core:^3

Оба класса входят в пакет core. Config доступен с версии 1.7.0. NextPdfConfig доступен с версии 2.2.0.

Концептуальный обзор

Config — класс final readonly, помеченный атрибутом #[DisallowDynamicProperties]. Он хранит только скалярные значения и объекты-значения final readonly, поэтому весь граф глубоко неизменяем. Универсального сеттера with(string, mixed) у него нет. Каждое изменение выполняется отдельным типизированным wither-методом. Таких методов 19: withPageSize(), withMargins(), withCompress() и далее до withOutputColorProfile(), и каждый из них пересоздаёт объект с именованными аргументами. Пересоздание через именованные аргументы сделано намеренно: при добавлении параметра конструктора существующий wither-метод никогда не сместит позиционный аргумент незаметно. Тест совместимости использует рефлексию, чтобы зафиксировать список публичных методов и количество параметров. Расхождение сигнатур приводит к сбою непрерывной интеграции (CI).

Конструктор задаёт поверхность конфигурации с безопасными значениями по умолчанию:

Параметр	Тип	По умолчанию
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

Три настройки контролируют границы допустимых значений. retainedNodeBudget принимает значения из замкнутого диапазона [5_000, 100_000] (константы RETAINED_NODE_BUDGET_MIN, RETAINED_NODE_BUDGET_MAX, значение по умолчанию RETAINED_NODE_BUDGET_DEFAULT). withRetainedNodeBudget() выбрасывает InvalidArgumentException вне этого диапазона. effectiveRetainedNodeBudget() возвращает 0 в потоковом режиме. В остальных случаях метод зажимает значение обратно в диапазон как дополнительную проверку эшелонированной защиты от прямого позиционного создания объекта. validate() обеспечивает соблюдение инвариантов между полями, которые отдельные wither-методы сами по себе увидеть не могут. CssLayoutMode::Auto зарезервирован и вызывает NotImplementedException. CssRenderingMode::Safe в сочетании с CssLayoutMode::Retained вызывает IncompatibleRenderingModeException. auditCollector — сборщик отчётов аудита, предоставленный вызывающим кодом. Он используется только тогда, когда cssRenderingMode равен CssRenderingMode::Audit; в этом режиме он формирует приватный блок Extensible Metadata Platform (XMP) nextpdfAudit. Остальные режимы отрисовки его игнорируют.

NextPdfConfig решает отдельную задачу. Это статическая утилита, экземпляр которой не создаётся; она хранит ограничения парсера CSS, действующие на весь процесс. Эти ограничения — максимальный размер таблицы стилей в байтах (по умолчанию 512 КБ) и максимальная глубина вложенности CSS (по умолчанию 8). Это защитные границы от исчерпания ресурсов из-за враждебного ввода, а не предпочтения уровня документа. Поэтому они статические. Сеттеры поднимают значения до нижней границы (max(1024, …) байт, max(1, …) глубина). resetDefaults() помечен как @internal и предназначен только для тестов.

Поверхность API

Символ	Вид	Ключевые члены
NextPDF\Core\Config	класс final readonly	21 параметр конструктора; 19 типизированных 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	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.

Пример кода — быстрый старт

Начните со значений по умолчанию и измените две настройки.

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

Пример кода — продакшен

Соберите детерминированную, проверенную конфигурацию и ужесточите ограничения CSS на уровне процесса для недоверенного ввода.

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

Граничные случаи и подводные камни

• Config не применяет правила между полями, пока вы не вызовете validate(). Wither-метод не может сам обнаружить конфликт Safe + Retained; вызывайте validate() перед генерацией.
• withRetainedNodeBudget() — единственный wither-метод, который выбрасывает исключение для собственного входного значения (InvalidArgumentException вне [5_000, 100_000]).
• effectiveRetainedNodeBudget() возвращает 0 в потоковом режиме. Это означает «бюджет уровня 1 неприменим», а не «узлы запрещены».
• withLayoutTelemetryCollector() и withTelemetryEnabled() независимы друг от друга. Подключение сборщика без включения телеметрии подготавливает его к последующему канареечному запуску. Включение телеметрии без сборщика допустимо и не имеет эффекта.
• NextPdfConfig статический и действует на весь процесс. Изменение влияет на каждый документ в процессе вплоть до сброса. Это граница безопасности, а не предпочтение уровня документа. Не используйте его в путях, где состояние меняется на уровне отдельного запроса.
• NextPdfConfig::resetDefaults() помечен как @internal. Не вызывайте его в продакшен-коде.

Производительность

Wither-метод выделяет один новый Config и копирует ссылки на существующие объекты-значения. Операция выполняется за O(1) по числу настроек и не делает глубокого копирования, поскольку каждое хранимое значение неизменяемо. Методы доступа NextPdfConfig читают статические поля, O(1). Бюджет performance_budget по умолчанию для этой справочной страницы — wall_ms: 1500, peak_mb: 64.

Замечания по безопасности

NextPdfConfig ограничивает использование ресурсов парсером. Ограничение размера таблицы стилей по умолчанию 512 КБ и ограничение глубины вложенности 8 защищают от отказа в обслуживании из-за патологически больших или глубоко вложенных CSS. Снижайте оба ограничения, когда источник таблицы стилей недоверенный. Config::cryptoPolicy содержит CryptoPolicyInterface для применения криптографической политики, например профиля Federal Information Processing Standards (FIPS). По умолчанию он равен null и задаётся через withCryptoPolicy(). Config::deterministic управляет фиксированными временными метками и идентификаторами для побайтово идентичного вывода и обязателен для воспроизводимых сборок.

Соответствие

Этот модуль описывает конфигурацию движка и не содержит ссылок на нормативные стандарты. Настройки, которые управляют поведением, связанным со стандартами, включая outputColorProfile (генерация OutputIntent), cryptoPolicy (FIPS) и deterministic (воспроизводимые сборки), задокументированы со ссылками на соответствующие пункты в модулях, где они формируются.

См. также

• /modules/core/document/ — использует Config
• /modules/core/valueobjects/ — PageSize, Margin, используемые в Config
• /modules/core/contracts/ — CryptoPolicyInterface, DegradationPolicy
• /modules/core/event/ — Config, передаваемый в DocumentCreatedEvent
• /modules/core/exception/ — InvalidConfigException, NotImplementedException

Глоссарий: типизированный wither-метод · политика деградации · объект-значение