Config: değişmez belge yapılandırması

Bir bakışta

Config, değişmez bir belge yapılandırması nesnesidir. Bir ayarı değiştirdiğinizde, türlendirilmiş bir wither yeni bir örnek döndürür; böylece yapılandırmayı belgeler ve çalışanlar arasında güvenle paylaşabilirsiniz. NextPdfConfig, süreç genelinde geçerli Cascading Style Sheets (CSS) ayrıştırıcı güvenlik sınırlarını tutan ayrı bir statik sınıftır.

Kurulum

composer require nextpdf/core:^3

Her iki sınıf da core paketinin bir parçasıdır. Config, sürüm 1.7.0’dan beri vardır. NextPdfConfig, sürüm 2.2.0’dan beri vardır.

Kavramsal genel bakış

Config, final readonly bir sınıftır ve #[DisallowDynamicProperties] ile işaretlenmiştir. Yalnızca skaler değerleri ve final readonly değer nesnelerini sakladığından, grafiğin tamamı derinlemesine değişmezdir. Genel amaçlı bir with(string, mixed) ayarlayıcısı sunmaz. Her değişiklik, kendine özgü türlendirilmiş bir wither üzerinden yapılır. Bunlardan 19 tane vardır: withPageSize(), withMargins(), withCompress()’ten withOutputColorProfile()’e kadar uzanır ve her biri nesneyi adlandırılmış argümanlarla yeniden oluşturur. Adlandırılmış argümanlarla yeniden oluşturma bilinçli bir tasarım tercihidir. Bir yapıcı parametresi eklediğinizde, mevcut bir wither hiçbir zaman konumsal bir argümanı sessizce kaydırmaz. Bir uyumluluk testi, public yöntem listesini ve parametre sayılarını sabitlemek için yansımayı kullanır. İmza kayması, sürekli entegrasyonu (CI) başarısız kılar.

Yapıcı, yapılandırma yüzeyini güvenli varsayılanlarla sunar:

Parametre	Tür	Varsayılan
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

Üç ayar, değer sınırlarını uygular. retainedNodeBudget, [5_000, 100_000] kapalı aralığını kabul eder (sabitler RETAINED_NODE_BUDGET_MIN, RETAINED_NODE_BUDGET_MAX, varsayılan RETAINED_NODE_BUDGET_DEFAULT). withRetainedNodeBudget(), bu aralığın dışında InvalidArgumentException fırlatır. effectiveRetainedNodeBudget(), akış modunda 0 döndürür. Aksi durumda, doğrudan konumsal yapıma karşı katmanlı bir savunma denetimi olarak değeri yeniden aralığa kırpar. validate(), alan başına çalışan wither’ların tek başına göremediği alanlar arası değişmezleri uygular. CssLayoutMode::Auto ayrılmıştır ve NotImplementedException fırlatır. CssRenderingMode::Safe, CssLayoutMode::Retained ile birlikte IncompatibleRenderingModeException fırlatır. auditCollector, çağıran tarafından sağlanan denetim raporu toplayıcısıdır. Yalnızca cssRenderingMode değeri CssRenderingMode::Audit olduğunda kullanılır; bu durumda özel bir nextpdfAudit Extensible Metadata Platform (XMP) bloğu yayımlar. Diğer işleme modları bunu yok sayar.

NextPdfConfig ayrı bir amaca hizmet eder. Süreç genelinde geçerli CSS ayrıştırıcı sınırlarını tutan, örnek oluşturulamayan statik bir yardımcıdır. Bu sınırlar, maksimum stil sayfası bayt sayısı (varsayılan 512 KB) ve maksimum CSS iç içe yerleştirme derinliğidir (varsayılan 8). Bunlar, belge başına tercihler değil, düşmanca girdiden kaynaklanan kaynak tükenmesine karşı güvenlik sınırlarıdır. Bu nedenle statiktirler. Ayarlayıcılar değerleri alt sınırın altına düşmeyecek şekilde kırpar (max(1024, …) bayt, max(1, …) derinlik). resetDefaults(), yalnızca test amaçlı kullanım için @internal olarak işaretlenmiştir.

API yüzeyi

Simge	Tür	Temel üyeler
NextPDF\Core\Config	final readonly class	21 yapıcı parametresi; 19 türlendirilmiş 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 class	setMaxCssBytes(), getMaxCssBytes(), setMaxCssNestingDepth(), getMaxCssNestingDepth(), resetDefaults() (@internal)

Wither’lar şunlardır: withPageSize, withMargins, withCompress, withAutoPageBreak, withLang, withFontsDirectory, withImageCacheBytes, withDeterministic, withCryptoPolicy, withBranding, withDegradationPolicy, withDegradationOverride, withCssRenderingMode, withCssFeatureFlags, withCssLayoutMode, withRetainedNodeBudget, withLayoutTelemetryCollector, withTelemetryEnabled, withOutputColorProfile.

Kod örneği — hızlı başlangıç

Varsayılanlarla başlayın ve iki ayarı değiştirin.

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

Kod örneği — üretim

Deterministik ve doğrulanmış bir yapılandırma oluşturun; güvenilmeyen girdi için süreç genelinde geçerli CSS sınırlarını sıkılaştırın.

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

Uç durumlar ve dikkat edilmesi gerekenler

• Config, siz validate() çağırana kadar hiçbir alanlar arası kuralı uygulamaz. Bir wither, Safe + Retained çakışmasını kendi başına algılayamaz; oluşturmadan önce validate() çağırın.
• withRetainedNodeBudget(), kendi girdisi üzerinde özel durum fırlatan tek wither’dır (InvalidArgumentException, [5_000, 100_000] aralığının dışında).
• effectiveRetainedNodeBudget(), akış modunda 0 döndürür. Bu, “hiçbir düğüme izin verilmiyor” değil, “Tier-1 bütçesi geçerli değil” anlamına gelir.
• withLayoutTelemetryCollector() ve withTelemetryEnabled() birbirinden bağımsızdır. Telemetriyi etkinleştirmeden bir toplayıcı bağlamak, onu daha sonraki bir canary için hazır hâle getirir. Toplayıcı olmadan telemetriyi etkinleştirmek geçerlidir ve hiçbir etkisi yoktur.
• NextPdfConfig, süreç genelinde geçerlidir ve statiktir. Bir değişiklik, sıfırlanana kadar süreçteki her belgeyi etkiler. Belge başına bir tercih değil, bir güvenlik sınırıdır. Bunu istek başına değişiklik yapılan kod yollarının dışında tutun.
• NextPdfConfig::resetDefaults(), @internal niteliğindedir. Bunu üretim kodunda çağırmayın.

Performans

Bir wither, yeni bir Config örneği ayırır ve mevcut değer nesnelerine olan başvuruları kopyalar. İşlem, ayar sayısından bağımsız olarak O(1)‘dir ve derin kopyalama yapmaz; çünkü tutulan her değer değişmezdir. NextPdfConfig erişimcileri statik alan okumalarıdır ve O(1)‘dir. Bu başvuru sayfası için varsayılan performance_budget değeri wall_ms: 1500, peak_mb: 64’tür.

Güvenlik notları

NextPdfConfig, ayrıştırıcı kaynak kullanımını sınırlar. Varsayılan 512 KB stil sayfası üst sınırı ile 8 derinlik iç içe yerleştirme üst sınırı, patolojik biçimde büyük veya derin biçimde iç içe geçmiş CSS’ten kaynaklanan hizmet engellemeye karşı koruma sağlar. Stil sayfası kaynağı güvenilmez olduğunda her iki sınırı da düşürün. Config::cryptoPolicy, Federal Information Processing Standards (FIPS) profili gibi kriptografik ilke zorunlu kılma için bir CryptoPolicyInterface taşır. Varsayılan olarak null’dur ve withCryptoPolicy() aracılığıyla ayarlanır. Config::deterministic, bayt düzeyinde özdeş çıktı için sabit zaman damgalarını ve tanımlayıcıları denetler; yeniden üretilebilir derlemeler için gereklidir.

Uygunluk

Bu modül, motor yapılandırmasıdır ve normatif standart atıfları içermez. outputColorProfile (OutputIntent yayımı), cryptoPolicy (FIPS) ve deterministic (yeniden üretilebilir derlemeler) dahil olmak üzere standart davranışını yönlendiren ayarlar, bunları yayan modüllerde ilgili maddelerine göre belgelenir.

Ayrıca bakınız

• /modules/core/document/ — tüketicisi: Config
• /modules/core/valueobjects/ — PageSize, Margin; kullanan: Config
• /modules/core/contracts/ — CryptoPolicyInterface, DegradationPolicy
• /modules/core/event/ — Config; taşıyan: DocumentCreatedEvent
• /modules/core/exception/ — InvalidConfigException, NotImplementedException

Sözlük: türlendirilmiş wither · azaltma ilkesi · değer nesnesi