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 があります。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`

3 つの設定には値の範囲があります。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 の場合にのみ使用され、その場合はプライベートな nextpdfAudit XMP ブロックを駆動します。他のレンダリングモードでは無視されます。

NextPdfConfig は別の責務を担います。プロセス全体に適用される CSS パーサー制限を保持する、インスタンス化できない静的ユーティリティです。対象となる制限は、スタイルシートの最大バイト数（デフォルト 512 KB）と 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。

コードサンプル — クイックスタート

デフォルトから構成を作成し、2 つの設定を調整します。

<?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 を返します。これは「Tier-1 のバジェットが適用されない」ことを示すものであり、「ノードが一切許可されない」ことを意味するものではありません。
withLayoutTelemetryCollector() と withTelemetryEnabled() は独立しています。テレメトリーを有効にせずにコレクターを接続すると、後続のカナリアに向けた準備として保持されます。コレクターなしでテレメトリーを有効にすることは有効な設定ですが、何も行われません。
NextPdfConfig はプロセス全体に適用され、静的です。変更は、リセットされるまでプロセス内のすべてのドキュメントに影響します。これはセキュリティ境界であり、ドキュメントごとの設定ではありません。リクエストごとに変更されるコードパスからは外してください。
NextPdfConfig::resetDefaults() は @internal です。本番コードでは呼び出さないでください。

パフォーマンス

wither は新しい Config を 1 つ確保し、既存の値オブジェクトへの参照をコピーします。これは設定数に対して O(1) であり、保持される値自体がすべて不変であるため、ディープコピーは行いません。NextPdfConfig のアクセサーは静的フィールドの読み取りであり、O(1) です。このリファレンスページのデフォルトの performance_budget は wall_ms: 1500、peak_mb: 64 です。

セキュリティに関する注意

NextPdfConfig は、パーサーのリソース使用量を制限するために存在します。デフォルトの 512 KB のスタイルシート上限と深度 8 のネスト上限は、極端に大きい、または深くネストされた CSS によるサービス拒否から保護します。スタイルシートのソースが信頼できない場合は、両方の制限を引き下げてください。Config::cryptoPolicy は、暗号ポリシーの強制（たとえば FIPS プロファイル）のために CryptoPolicyInterface を保持します。これはデフォルトで null であり、withCryptoPolicy() を通じて設定されます。Config::deterministic は、バイト単位で同一の出力を得るための固定タイムスタンプと識別子を制御し、再現可能なビルドに必要です。

準拠性

このモジュールはエンジン構成であり、規範的な標準の引用はありません。標準に関わる動作を制御する設定、outputColorProfile（OutputIntent の出力）、cryptoPolicy（FIPS）、deterministic（再現可能なビルド）は、それらを出力するモジュール側で、対応する条項に照らして文書化されています。