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، حيث يتحكم في كتلة منصة البيانات الوصفية القابلة للتوسيع (⁨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	ثابت من نوع ⁨int⁩	5_000
NextPDF\Core\Config::RETAINED_NODE_BUDGET_MAX	ثابت من نوع ⁨int⁩	100_000
NextPDF\Core\Config::RETAINED_NODE_BUDGET_DEFAULT	ثابت من نوع ⁨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 في وضع التدفق. وهذا يعني أن “ميزانية المستوى الأول لا تنطبق”، لا أن “أي عُقد غير مسموح بها”.
• 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 لفرض سياسة التشفير، مثل ملف تعريف معايير معالجة المعلومات الفيدرالية (⁨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⁩ مُحدَّدة النوع · سياسة التدهور · كائن القيمة