العلامة التجارية — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع المتعمّق لوحدة NextPDF\Enterprise\Branding. تُعلّم الوحدة مُخرجات التقييم وتترك المُخرجات المدفوعة دون مساس. يختار BrandingMode المُحلّ من الترخيص استراتيجيةً؛ ويطبّق BrandingApplicator الاستراتيجيةَ المُحلّة على بايتات الـ ⁨PDF⁩ المُصيَّرة. في ظل ترخيص مدفوع يكون التحويل هو الهوية: تبقى المُخرجات دون تغيير بايتاً ببايت، دون الحاجة إلى أي تغيير في الكود. للاطّلاع على سير عمل التقييم، اقرأ أولاً صفحة قدرة العلامة التجارية.

التوفّر والترخيص

تُشحن هذه القدرة في ⁨NextPDF Enterprise⁩ (nextpdf/enterprise) وتُفعَّل بمظروف ترخيص من فئة ⁨Enterprise⁩. لا يُحمّل النشرُ الذي يفتقر إلى ذلك الاستحقاق أصنافَ القدرة. قارن الإصدارات واحصل على ترخيص.

يحمل النظام الفرعي رمز القدرة المخصّص enterprise.branding لأنه يحكم سلوك التقييم عبر جميع الإصدارات. يُحلّ وضع العلامة التجارية من مظروف الترخيص الموقّع في وقت التشغيل؛ ولا يختاره أي علَم في التطبيق. يُحلّ الترخيص المدفوع الوضعَ إلى None ولا يُنتج أبداً مُخرجات ذات علامة. لا يوجد بناء إنتاج لتبديله.

سطح واجهة برمجة التطبيقات العامة

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
BrandingMode	—	None ('none'): لا تعديل	—	—	تعداد مدعوم بسلسلة نصية؛ EvaluationWatermark ('evaluation') يُفعّل العلامة التجارية التقييمية.
BrandingStrategy	—	عقد تستهلكه نقاط التكامل	—	—	واجهة؛ لا يتفرّع المستدعون على BrandingMode مباشرةً.
BrandingStrategy::isActive	—	false للاستراتيجية العدمية، true لاستراتيجية التقييم	bool	—	false يعني أن كل طريقة أخرى تُعيد قيم الهوية.
BrandingStrategy::buildPageWatermark	float $pageWidth، float $pageHeight (نقاط)	سلسلة فارغة عند الخمول؛ عوامل تشغيل علامة مائية قُطرية عند النشاط	string	—	يفترض التدفّق وجود مورد خط /helvetica في الصفحة.
BrandingStrategy::decorateProducer	string $producer	الهوية عند الخمول؛ يُلحق لاحقة التقييم عند النشاط	string	—	اللاحقة الافتراضية: [EVALUATION].
BrandingStrategy::decorateSubject	string $subject	الهوية عند الخمول؛ يُضيف بادئة التقييم في المقدّمة عند النشاط	string	—	يُنتج الموضوع الفارغ العلامة بعد الاقتطاع.
BrandingStrategyFactory::create	BrandingMode $mode، ?EvaluationBrandingConfig $config = null	يربط None بـ NullBrandingStrategy، وEvaluationWatermark بـ EvaluationBrandingStrategy	BrandingStrategy	—	ثابت؛ يستخدم التكوين null القيم الافتراضية.
EvaluationBrandingConfig::__construct	ستة معاملات مسمّاة اختيارية (النص، اللاحقة، البادئة، الحجم، الرمادي، الزاوية)	الافتراضيات: 48 pt، رمادي 0.85، 45 درجة	نسخة	InvalidArgumentException عند نص فارغ، أو حجم خط غير موجب، أو رمادي خارج 0.0–1.0	final readonly؛ غير قابل للتغيير.
EvaluationBrandingStrategy	EvaluationBrandingConfig اختياري	يطبّق العلامة المائية وتزيين البيانات الوصفية	—	—	final readonly؛ يُنفّذ BrandingStrategy.
NullBrandingStrategy	—	الهوية في كل طريقة	—	—	يُختار في ظل ترخيص مدفوع.
BrandingApplicator::apply	string $pdfBytes، BrandingStrategy $strategy	استراتيجية خاملة: يُعاد الإدخال بايتاً ببايت؛ نشطة: تُلحق تحديثة تزايدية واحدة	string	BrandingApplicationException عندما يتعذّر تطبيق العلامة النشطة بأمان	تحويل بايتات نقيّ وحتمي.
BrandingApplicationException	—	إشارة فشل نهائية بالإغلاق الآمن	—	—	يحمل SPEC_CODE (SPEC-BRANDING-UNAPPLICABLE)؛ المصنع unsupportedStructure().

توقيعات نقاط الدخول

enum BrandingMode: string
{
    case None = 'none';
    case EvaluationWatermark = 'evaluation';
}

public static function create(
    BrandingMode $mode,
    ?EvaluationBrandingConfig $config = null,
): BrandingStrategy

public function __construct(
    public string $watermarkText = 'EVALUATION COPY — Not for Production Use',
    public string $producerSuffix = ' [EVALUATION]',
    public string $subjectPrefix = '[EVALUATION] ',
    public float $watermarkFontSize = 48.0,
    public float $watermarkGray = 0.85,
    public float $watermarkAngle = 45.0,
)

public function apply(string $pdfBytes, BrandingStrategy $strategy): string

عقد السلوك

حلّ الوضع والاستراتيجية. تختار حالةُ الترخيص — لا كودُ التطبيق — BrandingMode. يربط BrandingStrategyFactory::create بين None وNullBrandingStrategy، وبين EvaluationWatermark وEvaluationBrandingStrategy. تستهلك نقاط التكامل واجهة BrandingStrategy ولا تفحص الوضع مباشرةً أبداً، فيبقى منطق العلامة التجارية مركزياً. في ظل ترخيص مدفوع تُختار الاستراتيجية العدمية وتكون المُخرجات مطابقةً للمُخرجات المُنتَجة دون أي نظام فرعي للعلامة التجارية إطلاقاً.

توليد العلامة المائية. يُصدر buildPageWatermark عوامل تشغيل تدفّق محتوى ⁨PDF⁩ لصفحة واحدة: حالة رسوميات معزولة (q/Q)، وخط ⁨Helvetica⁩ ضمن الخطوط الأربعة عشر القياسية عبر اسم المورد /helvetica، ووضع تصيير نص بالملء، ومصفوفة تدوير تضع النص قُطرياً عبر مركز الصفحة. النمط الافتراضي هو نص بحجم 48 pt بمستوى رمادي ⁨0.85⁩، مُدار بزاوية 45 درجة. تقرّب المَركزةُ عرضَ النص عبر عدد المحارف الرسومية — عناقيد المحارف الرسومية عند تحميل ⁨intl⁩، ونقاط ترميز ⁨Unicode⁩ عبر ⁨mbstring⁩ خلاف ذلك، وطول البايت كملاذ أخير. لا يُستشار أي عرض تقدّم لكل محرف رسومي بحكم التصميم. يُهرَّب نص العلامة المائية كسلسلة حرفية في ⁨PDF⁩ وفق ⁨ISO 32000-2⁩:2020 §7.3.4.2 (الشرطة المائلة العكسية والأقواس).

تزيين البيانات الوصفية. يُلحق decorateProducer لاحقةَ المنتِج بقيمة /Producer. ويُضيف decorateSubject بادئةَ الموضوع في مقدّمة قيمة /Subject؛ ويُنتج الموضوعُ الفارغ العلامةَ بعد اقتطاعها، فيبقى المستند الذي لا يملك بيانات وصفية للموضوع مُعلَّماً.

تطبيق البايتات. ‏BrandingApplicator::apply هو المستهلك النهائي لعنصر تحكّم العلامة التجارية. مع استراتيجية خاملة يُعيد الإدخال بايتاً ببايت. ومع استراتيجية نشطة يُلحق تحديثة تزايدية واحدة بالشكل المُعرّف في ⁨ISO 32000-2⁩:2020 §⁨7.5.6⁩: تبقى البايتات الأصلية سليمة، ويحمل الجسمُ المُلحق كائن ⁨Info⁩ مُزيَّناً (بإعادة استخدام رقم الكائن الموجود)، وتدفّق محتوى علامة مائية واحد إضافةً إلى كائن صفحة مُحدَّث واحد لكل صفحة، وتدفّق مرجع متقاطع جديداً (/Type /XRef، /W [1 4 2]) يشير /Prev فيه إلى startxref السابق. التحويل نقيّ وحتمي لإدخال وتكوين مُعطَيَين.

عقد الإغلاق الآمن. عندما تكون الاستراتيجية نشطة، يجب أن يكون الإدخال قابلاً لوضع العلامة: ترويسة %PDF-، ولا مدخل /Encrypt، ولا تدفّقات كائنات (/ObjStm)، وذيل تدفّق مرجع متقاطع، ومورد خط /helvetica قابل للحلّ من كل صفحة. يرفع أي انتهاك BrandingApplicationException بدلاً من إعادة بايتات دون علامة. يجب على المستدعين معاملة الاستثناء كنهائي وعدم اعتماد البايتات الأصلية غير المُعلَّمة.

الحالات الحدّية وأنماط الفشل

• المُخرجات ذات العلامة تعني أن حالة الترخيص من نمط تقييمي. وهذا يعكس حالة الترخيص، لا خللاً.
• العلامة المائية مُتمركزة وقُطرية بحكم التصميم. وهي غير قابلة للضبط للاستخدام الإنتاجي؛ ويزيلها الترخيص المدفوع بالكامل.
• يرفض EvaluationBrandingConfig نصَّ علامة مائية فارغاً، وحجمَ خط غير موجب، ومستوى رمادي خارج ⁨0.0⁩–⁨1.0⁩ عبر InvalidArgumentException.
• تُرفَض الاستراتيجية النشطة التي لا تُنتج أي تغيير في المنتِج أو الموضوع أو العلامة المائية عبر BrandingApplicationException بدلاً من إصدار بايتات تبدو مدفوعة.
• تُوضَع العلامة المائية على الصفحة التي تفتقر إلى /MediaBox قابل للاستخدام (غائب أو موروث) وفق الافتراضي ISO 216 A4 البالغ ⁨595.276⁩ × ⁨841.890⁩ نقطة.
• يُدعَم /Contents بصيغتَي المرجع المفرد والمصفوفة معاً؛ ويُلحق مرجعُ العلامة المائية أخيراً كي يُرسَم في الأعلى. وتتلقّى الصفحةُ التي لا تملك /Contents واحداً.
• تدور قيم سلاسل ⁨Info⁩ وتعود بتمثيلها الأصلي: تبقى السلاسل الست عشرية (UTF-16BE) ست عشرية، وتبقى السلاسل الحرفية حرفية. ويُلحق المفتاح الغائب، مُرمَّزاً ست عشرياً عندما تحتوي القيمة على محارف غير ⁨ASCII⁩.
• تُرفَض المستندات المشفّرة: إذ تتطلّب إعادةُ كتابة كائنات السلاسل في ظل /Encrypt مفتاحَ تشفير المستند.
• تحمل حالات الفشل الرمز الثابت SPEC-BRANDING-UNAPPLICABLE (BrandingApplicationException::SPEC_CODE) كي تتمكّن خطوط الأنابيب المستهلِكة من عزل الرسائل الميتة وتدقيق المُخرجات غير القابلة لوضع العلامة.
• لا تُجري الوحدة أي عمليات تشفيرية. يعود التحقّق من توقيع مظروف الترخيص إلى نظام الترخيص الفرعي؛ انظر المرجع المتعمّق للترخيص.

المطابقة

الادعاء	المعيار	البند
التحديثات التزايدية تُلحق التغييرات بنهاية الملف وتترك المحتويات الأصلية سليمة.	ISO 32000-2	§7.5.6
يغطّي قسمُ المرجع المتقاطع للتحديث الكائناتِ المتغيّرة فقط، ويحمل المُذيّلُ المُضاف مدخلَ Prev يحدّد موقع قسم المرجع المتقاطع السابق.	ISO 32000-2	§7.5.6
تُكتب السلاسل الحرفية بين أقواس؛ وتتطلّب الأقواس غير المتوازنة والشرطة المائلة العكسية معالجةً بالتهريب.	ISO 32000-2	§7.3.4.2

جميع البنود مُعاد صياغتها؛ ولا تستنسخ ⁨NextPDF⁩ النصَّ المعياري. لا تقدّم ⁨NextPDF⁩ أي ادعاء بالاعتماد. يكتب المُطبِّق التحديثات التزايدية بالشكل المُستشهَد به من ⁨ISO 32000-2⁩ كبيان قدرة؛ وهو ليس كاتباً معتمَداً أو مُتحقَّقاً منه بشكل مستقل. تصف هذه الصفحة سلوك وقت التشغيل فقط. ولا تقدّم أي ضمان، ولا أي بيان بشأن الأهلية أو الأثر القانوني، ولا تُشكّل مشورة قانونية؛ وتُحدَّد شروط التقييم أو الاشتراك حصراً باتفاقية الترخيص.

ملاحظات التطوير

• تحمل BrandingMode وBrandingStrategy والاستراتيجيتان كلتاهما والتكوين @since 3.0.0؛ ويحمل BrandingApplicator وBrandingApplicationException @since 3.1.0.
• لا يُجري النظام الفرعي أي استدعاءات شبكية. ولا يقرأ المُطبِّق سوى الحقول البنيوية التي يعيد كتابتها: سلاسل قاموس ⁨Info⁩، وقواميس الصفحات، وذيل المرجع المتقاطع.
• مظروف الترخيص أثرٌ موقّع يتحقّق وقتُ التشغيل من توقيع مُصدِره. وتقع تهيئة الترخيص وتجديده وتخزينه الآمن على عاتق المُشغّل.
• جميع الأنواع المحسوسة final؛ والاستراتيجيتان والتكوين readonly أيضاً. أنشئ نسخة تكوين جديدة لتغيير نمط العلامة المائية.
• إعادةُ BrandingStrategy::isActive() القيمةَ false تضمن قيم الهوية من كل طريقة أخرى؛ ويجوز للمستدعين اختصار المسار بناءً عليها لأجل الأداء.
• يشير تدفّق العلامة المائية إلى اسم المورد /helvetica. يسجّل ⁨Core⁩ هذا المورد لعلامته التجارية الخاصة؛ ويجب على أي تكامل يعطّل علامة ⁨Core⁩ التجارية أن يضمن وجود المورد.
• لا يحسب المُطبِّق أي بصمة؛ ويعيد المُستدعي حساب بصمة البايتات ذات العلامة قبل اعتمادها.
• تبقى تفاصيل الآلية الداخلية في التوثيق الداخلي لمستودع المصدر وهي خارج نطاق هذا الدليل.

حدود النشر

توثّق هذه الصفحة السلوكَ القابل للملاحظة خارجياً وسطحَ واجهة برمجة التطبيقات العامة المدعوم فقط. أما مسارات فضاءات الأسماء الداخلية، وأصناف المساعِدة، وجداول الآليات، وأسماء ملفات أدلة التشغيل، وبادئات التذاكر فهي خارج النطاق.

انظر أيضاً

• العلامة التجارية — صفحة القدرة للنظام الفرعي لعلامة التقييم التجارية.
• العلامة التجارية للتجربة والتقييم — قصة التقييم الشاملة من طرف إلى طرف.
• الترخيص — مرجع متعمّق
• نظرة عامة على Enterprise