Config: konfigurasi dokumen imutabel

Sekilas

Config adalah objek konfigurasi dokumen imutabel. Saat Anda mengubah pengaturan, wither bertipe mengembalikan instance baru, sehingga konfigurasi dapat dibagikan dengan aman di berbagai dokumen dan worker. NextPdfConfig adalah kelas statis terpisah yang menyimpan batas keamanan parser Cascading Style Sheets (CSS) yang berlaku di seluruh proses.

Pemasangan

composer require nextpdf/core:^3

Kedua kelas ini merupakan bagian dari paket core. Config tersedia sejak 1.7.0. NextPdfConfig tersedia sejak 2.2.0.

Tinjauan konseptual

Config adalah kelas final readonly yang ditandai dengan #[DisallowDynamicProperties]. Kelas ini hanya menyimpan skalar dan objek nilai final readonly, sehingga seluruh graf objek bersifat imutabel hingga lapisan terdalam. Kelas ini tidak menyediakan setter generik with(string, mixed). Setiap perubahan menggunakan wither khusus yang bertipe. Ada 19 wither: withPageSize(), withMargins(), withCompress(), hingga withOutputColorProfile(), dan masing-masing menyusun ulang objek dengan argumen bernama. Penggunaan argumen bernama dalam penyusunan ulang ini disengaja. Ketika Anda menambahkan parameter konstruktor, wither yang sudah ada tidak akan pernah menggeser argumen posisional secara diam-diam. Sebuah uji kompatibilitas berbasis refleksi mengunci daftar metode publik dan jumlah parameter. Perubahan tanda tangan menyebabkan continuous integration (CI) gagal.

Konstruktor memaparkan permukaan konfigurasi dengan nilai bawaan yang aman:

Parameter	Tipe	Bawaan
`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`

Tiga pengaturan menerapkan batas nilai. retainedNodeBudget menerima rentang tertutup [5_000, 100_000] (konstanta RETAINED_NODE_BUDGET_MIN, RETAINED_NODE_BUDGET_MAX, bawaan RETAINED_NODE_BUDGET_DEFAULT). withRetainedNodeBudget() melempar InvalidArgumentException jika nilainya di luar rentang tersebut. effectiveRetainedNodeBudget() mengembalikan 0 dalam mode streaming. Selain itu, nilai tersebut dibatasi kembali ke dalam rentang sebagai pemeriksaan defense-in-depth terhadap konstruksi posisional langsung. validate() menerapkan invarian lintas-bidang yang tidak dapat dideteksi sendiri oleh wither per bidang. CssLayoutMode::Auto dicadangkan dan melempar NotImplementedException. CssRenderingMode::Safe dengan CssLayoutMode::Retained melempar IncompatibleRenderingModeException. auditCollector adalah pengumpul laporan audit yang disediakan oleh pemanggil. Pengumpul ini hanya digunakan ketika cssRenderingMode bernilai CssRenderingMode::Audit; dalam mode itu, pengumpul menggerakkan blok Extensible Metadata Platform (XMP) nextpdfAudit privat. Mode rendering lain mengabaikannya.

NextPdfConfig menangani tanggung jawab terpisah. Kelas ini adalah utilitas statis yang tidak dapat diinstansiasi dan menyimpan batas parser CSS untuk seluruh proses. Batas tersebut mencakup ukuran maksimum stylesheet dalam byte (bawaan 512 KB) dan kedalaman penyarangan CSS maksimum (bawaan 8). Ini merupakan batas keamanan terhadap kehabisan sumber daya akibat masukan berbahaya, bukan preferensi per-dokumen. Karena itu, batas ini bersifat statis. Setter menerapkan batas bawah (max(1024, …) byte, kedalaman max(1, …)). resetDefaults() ditandai @internal dan hanya ditujukan untuk pengujian.

Permukaan API

Simbol	Jenis	Anggota utama
`NextPDF\Core\Config`	kelas final readonly	21 parameter konstruktor; 19 wither bertipe; `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`	kelas 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.

Contoh kode — Mulai cepat

Mulai dari nilai bawaan dan sesuaikan dua pengaturan.

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

Contoh kode — Produksi

Susun konfigurasi deterministik yang sudah divalidasi, lalu perketat batas CSS yang berlaku di seluruh proses untuk masukan tidak tepercaya.

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

Kasus tepi & jebakan

Config tidak menerapkan aturan lintas-bidang apa pun hingga Anda memanggil validate(). Wither tidak dapat mendeteksi konflik Safe + Retained dengan sendirinya; panggil validate() sebelum pembuatan dokumen.
withRetainedNodeBudget() adalah satu-satunya wither yang melempar untuk masukannya sendiri (InvalidArgumentException di luar [5_000, 100_000]).
effectiveRetainedNodeBudget() mengembalikan 0 dalam mode streaming. Nilai itu menandakan “anggaran Tier-1 tidak berlaku”, bukan “tidak ada simpul yang diizinkan”.
withLayoutTelemetryCollector() dan withTelemetryEnabled() bersifat independen. Memasang pengumpul tanpa mengaktifkan telemetri akan menyiapkannya untuk canary di kemudian hari. Mengaktifkan telemetri tanpa pengumpul tetap valid dan tidak berdampak apa pun.
NextPdfConfig berlaku untuk seluruh proses dan bersifat statis. Perubahan apa pun memengaruhi setiap dokumen dalam proses tersebut hingga disetel ulang. Ini adalah batas keamanan, bukan preferensi per-dokumen. Jangan tempatkan di jalur mutasi per permintaan.
NextPdfConfig::resetDefaults() bersifat @internal. Jangan memanggilnya dalam kode produksi.

Performa

Setiap wither mengalokasikan satu Config baru dan menyalin referensi ke objek nilai yang sudah ada. Operasi ini bersifat O(1) terhadap jumlah pengaturan dan tidak melakukan penyalinan mendalam, karena setiap nilai yang dipegang bersifat imutabel. Pengakses NextPdfConfig adalah pembacaan bidang statis, O(1). performance_budget bawaan untuk halaman referensi ini adalah wall_ms: 1500, peak_mb: 64.

Catatan keamanan

NextPdfConfig membatasi penggunaan sumber daya parser. Batas bawaan 512 KB untuk stylesheet dan batas kedalaman penyarangan 8 melindungi dari denial-of-service akibat CSS yang sangat besar atau bersarang sangat dalam. Turunkan kedua batas tersebut ketika sumber stylesheet tidak tepercaya. Config::cryptoPolicy membawa CryptoPolicyInterface untuk penegakan kebijakan kriptografi, seperti profil Federal Information Processing Standards (FIPS). Nilai bawaannya null dan ditetapkan melalui withCryptoPolicy(). Config::deterministic mengendalikan stempel waktu dan pengenal tetap agar keluaran identik secara byte, dan diperlukan untuk reproducible build.

Kesesuaian

Modul ini merupakan konfigurasi mesin dan tidak membawa rujukan standar normatif apa pun. Pengaturan yang mengarahkan perilaku berbasis standar, termasuk outputColorProfile (emisi OutputIntent), cryptoPolicy (FIPS), dan deterministic (reproducible build), didokumentasikan bersama klausul masing-masing di modul yang memancarkan perilaku tersebut.

Lihat juga

/modules/core/document/ — konsumen Config
/modules/core/valueobjects/ — PageSize, Margin yang digunakan oleh Config
/modules/core/contracts/ — CryptoPolicyInterface, DegradationPolicy
/modules/core/event/ — Config yang dibawa oleh DocumentCreatedEvent
/modules/core/exception/ — InvalidConfigException, NotImplementedException

Glosarium: typed wither · degradation policy · value object