أخطاء النواة والأخطاء العامة

النطاق

تغطي هذه المداخل الاستثناءات الأساسية والعامة الغرض التي يُطلقها ⁨NextPDF⁩. ويمدّد معظمها الأساس NextPdfException، الذي يمدّد بدوره \RuntimeException ويطبّق ContextAwareExceptionInterface. وتكشف تلك الواجهة طريقةً واحدة، getContext(): array، تُرجع خريطة مسطّحة بنمط ⁨snake_case⁩ من العناصر الأولية الآمنة للتسلسل إلى سجلّ أو حمولة ⁨APM⁩.

اعترض عائلة NextPdfException بـcatch (NextPdfException $e) واحدة. وأضِف catch (\RuntimeException $e) أيضًا لتغطية الأخطاء القليلة منخفضة المستوى في هذه المجموعة التي تمدّد \RuntimeException مباشرةً (مذكورة أدناه). يُرجع الأساس NextPdfException::getContext() مصفوفة فارغة؛ وتتجاوزه الفئات الفرعية لإضافة حقول مجال. وحيث لا تتجاوز فئة getContext()، فإنها ترث المصفوفة الفارغة وتعيش التفاصيل التشخيصية في الرسالة وفي المُلتقِطات ذات الأنواع بدلًا من ذلك.

أربعة أنواع في هذه المجموعة لا تمدّد NextPdfException: تمدّد BlackPointCompensationUnsupportedException وUnsupportedSourceDocumentException فئة \RuntimeException مباشرةً (اعترضها بوصفها \RuntimeException)، وComplianceViolation وRuleViolation كائنا قيمة، لا استثناءان — وهما مُوثَّقان هنا لأنهما يُنمذِجان بيانات الخطأ والانتهاك التي يُرجعها المحرك.

الاستثناء الأساسي

NextPdfException

• ما هو. أساس abstract لكل استثناء يُطلقه ⁨NextPDF⁩ core وحزم امتداده. يمدّد \RuntimeException ويطبّق ContextAwareExceptionInterface. واعتراض هذا النوع الواحد يعترض أي خطأ في المكتبة.
• السياق. يُرجع الأساس getContext() مصفوفة فارغة. وتتجاوزه الفئات الفرعية لإرجاع حقول خاصة بالمجال.
• التعافي. لا يُطلَق مباشرةً. استخدمه بوصفه نوع الاقتناص الجامع؛ وتفرّع على الفئة الفرعية الفعلية للمعالجة المحددة.

التهيئة وبوّابة الميزات

InvalidConfigException

• متى يُطلَق. عندما تكون قيمة Config أو تركيبة قيم غير صالحة — إعداد مطلوب مفقود، أو خيار مُتنافٍ، أو قيمة خارج نطاقها المقبول. وهذا يُشير إلى خطأ مطوِّر: قدّمت الشفرة المُستدعية تهيئةً يجب تصحيحها قبل إعادة المحاولة. وتُبلّغ الرسالة عن المفتاح، والنوع أو النطاق المتوقَّع، ونوع التصحيح الفعلي للقيمة المُقدَّمة.
• السياق. يُرجع getContext() القيم config_key وgiven_value وexpected_type. المُلتقِطات ذات الأنواع: getConfigKey() وgetGivenValue() وgetExpectedType().
• التعافي. إجراء مطوِّر: أصلِح مفتاح التهيئة المسمى إلى قيمة من النوع أو النطاق المتوقَّع قبل استدعاء ⁨NextPDF⁩ مرة أخرى.

NotImplementedException

• متى يُطلَق. عند بلوغ نقطة دخول واجهة ⁨API⁩ عامة بينما يكون تطبيقها غائبًا عمدًا في الإصدار الحالي. يُستخدَم لطبقات التوافق المُهملة الموجودة لتمنح المُستدعين السابقين للتقسيم الثنائي إخفاقًا صاخبًا قابلًا للتنفيذ بدلًا من عدم تنفيذ صامت. وتجمع الرسالة وسم feature قابلًا للبحث بـ⁨grep⁩ ومرجع followUp (مُعرِّف عيب، أو مرساة تتبّع، أو اسم سباق سريع).
• السياق. لا يتجاوز getContext()، فيُرجع مصفوفة فارغة. والقيمتان $feature و$followUp خاصيتان عامتان للقراءة فقط ومُضمَّنتان في الرسالة.
• التعافي. إجراء مُستدعي المكتبة: أزِل الاستدعاء، أو ثبّت على إصدار مستقبلي يُنزِل المتابعة المسماة.

IncompatibleFeatureFlagsException

• متى يُطلَق. وقت بناء Config (Config::validate()) عندما تكون تركيبة CssFeatureFlags غير متّسقة داخليًا — راية تفترض مسبقًا أخرى مُعطَّلة. والتركيبة الوحيدة الممنوعة اليوم هي layoutSubgrid = true مع layoutGrid = false: فمحور مُشبَّك فرعيًا يشتقّ أسطر شبكته من حاوية شبكة أصل (⁨CSS Grid Layout Module Level 2 §1⁩)، لذا فالشبكة الفرعية دون شبكة تصف شبكةً لا يمكن أن توجد. ويعمل الفحص مقابل الرايات المُحلّلة، فيُقنِّع CssRenderingMode::Safe (الذي يُجبر كل ميزة من ⁨Phase 4⁩ فما فوق على الإيقاف) التركيبة بدلًا من تعثّرها. يمدّد StrictModeViolation.
• السياق. يدمج getContext() حقول الوضع الصارم للأب (cssDeviation وexcId وchunkSha256 وlocation) مع القيمتين المنطقيتين layoutGrid وlayoutSubgrid. ويكون location هو Config::validate() ويُرمِّز cssDeviation زوج الرايتين.
• التعافي. إجراء مُستدعي المكتبة: فعّل layoutGrid إلى جانب layoutSubgrid، أو عطّل layoutSubgrid.

IncompatibleRenderingModeException

• متى يُطلَق. وقت بناء Config عندما يقع اقتران CssRenderingMode وCssLayoutMode خارج الخلايا المتوافقة في مصفوفة الأوضاع. والاقتران الوحيد الممنوع اليوم هو CssRenderingMode::Safe + CssLayoutMode::Retained — يُجبر ⁨Safe⁩ كل ميزة من ⁨Phase 4⁩ فما فوق على الإيقاف، فيترك سياقات تنسيق الوضع المُحتفَظ به (⁨Grid⁩ و⁨Subgrid⁩ و@container) بلا مستهلكين، لذا تُرفض التركيبة بدلًا من السماح لها بالتدهور بصمت. يمدّد StrictModeViolation.
• السياق. يدمج getContext() حقول الوضع الصارم للأب مع mode1 (قيمة وضع العرض) وmode2 (قيمة وضع التخطيط). ويُرمِّز cssDeviation زوج الأوضاع؛ وlocation هو Config::validate().
• التعافي. إجراء مُستدعي المكتبة: اختر Safe + Streaming للتراجع، أو وضع عرض غير ⁨Safe⁩ (Normal / Strict / Audit) مع Retained لأجل ⁨Grid⁩ / ⁨Subgrid⁩ / استعلامات الحاوية.

StrictModeViolation

• متى يُطلَق. أساس abstract لأي استثناء انحراف عن المواصفة يُطلَق تحت CssRenderingMode::Strict. في الوضع الصارم، يُطلق أي انحراف ⁨CSS⁩ مُكتشَف غير مرتبط بمدخل استثناء EXC-NNN مُسجَّل نسخةً من هذه الفئة (أو فئة فرعية) عند نقطة الاكتشاف. لا يُطلَق مباشرةً؛ انظر IncompatibleFeatureFlagsException وIncompatibleRenderingModeException.
• السياق. يُرجع getContext() حقول ⁨ADR-023⁩ الأربعة: cssDeviation (وسم قصير للبنية المنحرفة)، وexcId (مُعرِّف السجلّ عند التسجيل، وإلّا null)، وchunkSha256 (تجزئة كتلة استشهاد المواصفة عند معرفتها، وإلّا null)، وlocation (أصل قابل لقراءة المُستدعي، وإلّا null).
• التعافي. إجراء مُستدعي المكتبة: سجّل الانحراف بوصفه مدخل EXC-NNN جديدًا مُوقَّعًا، أو أصلِح المُصيِّر لإزالة الانحراف.

مُدخَل ⁨HTML⁩ و ⁨CSS⁩

HtmlParsingException

• متى يُطلَق. عندما يُخفق تحليل مُدخَل ⁨HTML⁩ أو بناء ⁨DOM⁩: تصاريح مجموعة محارف غير صالحة، وانتهاكات حدّ حجم المُدخَل، وعمق تداخل مُفرِط، وفيوض عدّ العناصر، وأخطاء بنية الجدول مثل أقصى عدّ للصفوف. ويُبلِّغ عن استنزاف الموارد الخاص بـ⁨CSS⁩ بدلًا من ذلك CssParserLimitExceededException وCssResolutionBudgetExceededException.
• السياق. يُرجع getContext() القيم html_snippet (مقتطف قصير مُقتطَع من ⁨HTML⁩ المُخالف)، وposition (إزاحة بايت، أو -1 إن كانت غير معروفة)، وrule (قيد المُحلِّل المُنتهَك). المُلتقِطات ذات الأنواع: getHtmlSnippet() وgetPosition() وgetRule().
• التعافي. إجراء مطوِّر: بسّط مُدخَل ⁨HTML⁩ أو عدّل حدود المُحلِّل.

CssParserLimitExceededException

• متى يُطلَق. عندما يتجاوز مُدخَل ⁨CSS⁩ حدّ سلامة مُهيّأ للمُحلِّل. وتُغطّى فئتان عبر المُنشئات المسماة: forByteLimit() (ورقة أنماط كبيرة أكثر من اللازم لمعالجة آمنة بالتعبيرات النمطية) وforNestingDepth() (عمق تكرار تداخل ⁨CSS⁩ كبير أكثر من اللازم). وتذكر كلتا الرسالتين القيمة الفعلية والحدّ.
• السياق. يُرجع getContext() القيم limit_type (byte أو nesting_depth)، وactual، وlimit.
• التعافي. إجراء مطوِّر: قسّم ورقة الأنماط إلى أوراق أصغر، أو قلّل عمق التداخل، أو ارفع الحدّ المُهيّأ.

CssResolutionBudgetExceededException

• متى يُطلَق. عندما يتجاوز حلّ ⁨CSS⁩ :has() ميزانية اجتيازه. ويفرض مُحلِّل :has() ثنائي التمريرة ميزانية زيارة عُقد صارمة لمنع المُحدِّدات المرضية من إحداث مرور تربيعي على المستند؛ وبمجرد تجاوز عدّ الزيارات الكلي الحدّ، تُرفض ورقة الأنماط بوصفها معقّدة أكثر من اللازم. وتذكر الرسالة عدّ الزيارات والميزانية.
• السياق. يُرجع getContext() القيمتين visits وbudget. المُلتقِطات ذات الأنواع: getVisits() وgetBudget().
• التعافي. إجراء مطوِّر: قلّل تعقيد المُحدِّد، أو ارفع الميزانية المُهيّأة.

الخطوط والصور

FontNotFoundException

• متى يُطلَق. عندما لا يمكن تحديد موقع ملف خط أو قراءته على مستوى نظام الملفات: العائلة أو المسار المطلوب غير موجود، أو غير قابل للقراءة، أو دليل الخطوط المُهيّأ غير قابل للوصول. وقد تكون بيانات الخط صالحة — فهذا يُشير فقط إلى أنه لا يمكن بلوغها. وتسرد الرسالة المسارات المُبحوث فيها.
• السياق. يُرجع getContext() القيم font_name، وsearch_paths (قائمة)، وfallback_attempted (قيمة منطقية). المُلتقِطات ذات الأنواع: getFontName() وgetSearchPaths() وwasFallbackAttempted().
• التعافي. إجراء مطوِّر: تحقّق من مسار الخط. إجراء بنية تحتية: أصلِح أذونات الملفات على ملف الخط أو الدليل.

FontParsingException

• متى يُطلَق. عندما يوجد ملف خط لكن محتوياته غير قابلة للاستعمال: فهو تالف، أو بصيغة غير مدعومة، أو يفتقد جداول مطلوبة. ويغطي إخفاقات التحقق البنيوي أثناء تحليل ⁨TrueType⁩ و⁨Type 1⁩ و⁨CFF⁩ و⁨OpenType⁩ — ترويسات مُقتطَعة، وأدلة جداول غير صالحة، وجداول إلزامية مفقودة (head وhhea وOS/2)، وأخطاء فكّ التحزيم، وانتهاكات الحجم. وتذكر الرسالة الملف وخطأ التحليل.
• السياق. يُرجع getContext() القيمتين font_file وparse_error. المُلتقِطات ذات الأنواع: getFontFile() وgetParseError().
• التعافي. إجراء مطوِّر: استبدل ملف الخط بآخر صالح.

ImageProcessingException

• متى يُطلَق. عندما لا يمكن فكّ ترميز صورة، أو تكون بصيغة غير مدعومة، أو تُخفق في معالجة ⁨GD/Imagick⁩: بايتات سحرية غير مُتعرَّف عليها، وبيانات ⁨JPEG⁩ تالفة، وأنواع ⁨MIME⁩ غير مدعومة، وانتهاكات حدّ حجم الملف، وإخفاقات تخصيص موارد ⁨GD⁩. وكانت الصورة قابلة للوصول لكن بيانات بكسلاتها لم يمكن استخراجها للتضمين.
• السياق. يُرجع getContext() القيم image_path (فارغ للبيانات المُضمَّنة)، وformat (المُكتشَف أو المتوقَّع، على سبيل المثال jpeg، png، unknown)، وoperation (على سبيل المثال decode، resize، embed). المُلتقِطات ذات الأنواع: getImagePath() وgetFormat() وgetOperation().
• التعافي. إجراء مطوِّر: وفّر ملف صورة صالحًا ومدعومًا.

الخرج والتخطيط والتسلسل

CompressionException

• متى يُطلَق. عندما يُخفق ضغط ⁨FlateDecode⁩ (⁨zlib⁩) أو فكّ ضغطه — إخفاقات gzcompress/gzuncompress على دفوق المحتوى، وبيانات الخط، ومحتوى الصفحة، وبيانات المرفقات، ودفوق المراجع المتقاطعة. وعادةً دفق مُدخَل تالف، أو ذاكرة غير كافية، أو امتداد ⁨zlib⁩ مفقود.
• السياق. يُرجع getContext() القيمتين algorithm (اسم المُرشِّح، على سبيل المثال FlateDecode، LZWDecode) وstream_length (طول البايت، أو -1 إن كان غير معروف). المُلتقِطات ذات الأنواع: getAlgorithm() وgetStreamLength().
• التعافي. إجراء بنية تحتية: تحقّق من تحميل ext-zlib ومن كفاية الذاكرة.

WriterException

• متى يُطلَق. عندما يُخفق تسلسل ⁨PDF⁩ أو خطيّته أو خرج الإدخال/الإخراج: أخطاء كتابة دفق PdfWriter، وتلف جدول المراجع المتقاطعة، وإخفاقات توليد الترويسة/المُذيَّل، وإخفاقات حلّ مرجع الكائن، وأخطاء كتابة الملف، وفيوض مخزن الخرج المؤقت. ولم يمكن تسلسل مستند صالح في الذاكرة إلى دفق بايتات صالح. وتذكر الرسالة المرحلة.
• السياق. يُرجع getContext() القيمتين output_path (فارغ لخرج السلسلة) وwriter_state (المرحلة، على سبيل المثال header، body، xref، trailer). المُلتقِطات ذات الأنواع: getOutputPath() وgetWriterState().
• التعافي. إجراء بنية تحتية: تحقّق من مساحة القرص، وأذونات الملفات، ودفق الخرج.

PageLayoutException

• متى يُطلَق. عندما لا يمكن استيفاء قيود تخطيط الصفحة: انتهاكات تخطيط الأعمدة (عرض غير كافٍ، عدّ أعمدة غير صالح)، وفيض المحتوى خارج حدود الصفحة، وتعارضات الهوامش. والتخطيط المطلوب مستحيل هندسيًا لأبعاد الصفحة والمحتوى المُعطَيين. وتذكر الرسالة رقم الصفحة عند معرفته والقيد المُنتهَك.
• السياق. يُرجع getContext() القيمتين page_number (مبدوءًا من واحد، أو 0 إن كان غير معروف) وconstraint. المُلتقِطات ذات الأنواع: getPageNumber() وgetConstraint().
• التعافي. إجراء مطوِّر: عدّل حجم الصفحة، أو الهوامش، أو إعدادات الأعمدة، أو المحتوى.

TemplateException

• متى يُطلَق. عندما تُخفق عملية استيراد قالب ⁨PDF⁩ أو إعادة استخدامه في TemplateManager: انتقالات حالة قالب غير صالحة (بدء القوالب أو إنهاؤها خارج التسلسل)، والإشارة إلى قالب غير موجود، وإخفاقات ضغط الدفق أثناء تسلسل القالب. وتذكر الرسالة العملية ومُعرِّف القالب عند تخصيصه.
• السياق. يُرجع getContext() القيمتين template_id (فارغ إن لم يُخصَّص بعد) وoperation (على سبيل المثال begin، end، use، serialize). المُلتقِطات ذات الأنواع: getTemplateId() وgetOperation().
• التعافي. إجراء مطوِّر: أصلِح تسلسل استخدام القالب أو ملف ⁨PDF⁩ المصدر.

ثوابت دفق المحتوى

ContentStreamBalanceException

• متى يُطلَق. عندما يكتشف ContentStreamBuilder زوج عوامل غير متوازن عند إغلاق الدفق (أو في منتصف الدفق عند تأكيد الثوابت بحماسة). ويلتقط عدّادات العمق التي أخفقت في ثابت التوازن حتى يستطيع التسجيل تحديد أي مُصدِر سرّب q أو BT أو BMC دون مطابِقه Q أو ET أو EMC. وفق ⁨ISO 32000-2:2020 §8.4.2⁩ (مكدّس حالة الرسوميات)، و§⁨9.4.1⁩ (كائنات النص)، و§⁨14.6⁩ (المحتوى المُعلَّم).
• السياق. يُرجع getContext() القيم graphics_depth، وtext_block_depth، وmarked_content_depth، وoffending_operator. المُلتقِطات ذات الأنواع: getGraphicsDepth() وgetTextBlockDepth() وgetMarkedContentDepth() وgetOffendingOperator().
• التعافي. إجراء مطوِّر: حدّد موقع المُصدِر الذي فتح بنيةً دون إغلاقها.

GraphicsStateBalanceException

• متى يُطلَق. عندما يُغلَق دفق محتوى ⁨PDF⁩ بعوامل q/Q غير متوازنة. يتطلب ⁨ISO 32000-2:2020 §8.4.2⁩ أن يُطابَق كل حفظ لحالة الرسوميات (q) باستعادة واحدة بالضبط (Q) قبل انتهاء الدفق؛ ويُسرِّب عدم التوازن التحويل، ومسار القَصّ، والألوان، ونيّة العرض إلى الصفحات اللاحقة أو إلى ⁨Form XObjects⁩. لا يُطلَق إلّا عند تفعيل الفحص الصارم لحالة الرسوميات (NEXTPDF_GFXSTATE_STRICT=1)؛ وفي الوضع المُرخى يُصدَر تحذير عبر trigger_error() بدلًا من ذلك.
• السياق. يُرجع getContext() القيمة save_depth (موجبة لكثرة عمليات الحفظ، سالبة لكثرة عمليات الاستعادة). المُلتقِط ذو النوع: getSaveDepth().
• التعافي. إجراء مطوِّر: حدّد موقع زوج save()/restore() غير المُطابَق.

MissingShadingResourceException

• متى يُطلَق. عندما يُستدعى ConicGradientRenderer::render() دون سياق سجلّ موارد التظليل. أزال التغيير الكاسر في ⁨v10.0.0⁩ مسار البديل السابق المعتمد على خريطة العلامات الضمنية: يجب على المُستدعين بناء المُصيِّر بـShadingResourceRegistryInterface حتى يُسجَّل الكائن غير المباشر /ShadingType 4 مقابل القاموس الفرعي لموارد التظليل في الصفحة (⁨ISO 32000-2 §8.7.4.2⁩ / §8.7.4.3). وتذكر الرسالة سياق المُستدعي وتُشير إلى ملاحظة الترحيل من ⁨v9.x⁩ إلى ⁨v10.0⁩.
• السياق. يُرجع getContext() القيمة context (وسم سياق مُستدعي قصير، على سبيل المثال ConicGradientRenderer::render).
• التعافي. إجراء مُستدعي المكتبة: صِل نسخة سجلّ موارد تظليل في مُنشئ المُصيِّر قبل استدعاء render().

الخطية (العرض السريع على الويب)

LinearizationInvariantException

• متى يُطلَق. عندما يكتشف Linearizer ثلاثي التمريرة من الإصدار ⁨v2⁩ أن تأكيداته ⁨MEASURE → PLACE → FILL⁩ قد انتُهكت: عدّ بايتات في التمريرة 3 لا يطابق طول الملف المتوقَّع في التمريرة 1 (انحراف الإزاحة)، أو عنصر نائب لقاموس الخطية صغير أكثر من اللازم للعرض المُسلسَل، أو إزاحة دفق تلميح /H [offset length] لا تطابق الخرج النهائي. وإظهار هذا بدلًا من إصدار ⁨PDF⁩ معطوب ضمان سلامة مُعلَن.
• السياق. يُرجع getContext() القيم invariant (اسم الثابت المُنتهَك)، وexpected، وactual، وdelta (الفرق المُوقَّع). المُلتقِطات ذات الأنواع: getInvariant() وgetExpectedValue() وgetActualValue().
• التعافي. إجراء مُشرِف: أعِدّ تقرير عيب — فهذه الثوابت ينبغي أن تصمد لكل المُدخَلات سليمة الشكل. التقط الاستثناء السابق المُتسلسل.

LinearizationUnimplementedException

• متى يُطلَق. عندما تُضبَط راية ميزة المُخطِّط على خلفية مُعطَّلة عمدًا. يُطلَق حاليًا فقط لـlinearizerVersion === 'v1-noop'، إعداد التخفيض الطارئ الذي يرفض كل محاولات الخطية في وقت التشغيل دون تغيير شفرة أو إعادة نشر — مفيد لمفتاح إيقاف العرض السريع على الويب في الإنتاج.
• السياق. يُرجع getContext() القيمة reason (شرح قصير قابل لقراءة الإنسان). المُلتقِط ذو النوع: getReason().
• التعافي. إجراء مُشغِّل / هندسة إصدار: عدّل التهيئة أو رقِّ إلى إصدار خلفية مُصلَح.

ثوابت المطابقة وملف التعريف

ConformanceViolationException

• متى يُطلَق. عندما لا يمكن إصدار ميزة مطلوبة دون كسر عقد مطابقة ⁨ISO⁩ المُعلَن للمستند، ويُخفق المحرك بأمان بدلًا من كتابة كائن غير مطابق. والمُطلِق المعياري هو تعليق Screen متعدد الوسائط أو إجراء Rendition (⁨ISO 32000-2:2020 §12.5.6.18⁩ / §⁨13.2⁩) تحت ملف تعريف ⁨PDF/A⁩ أرشيفي، وهو ما يمنعه كل جزء من ⁨PDF/A⁩ (سلسلة ⁨ISO 19005⁩) — فالملف سيُخفق في التحقق بـ⁨veraPDF⁩، لذا يرفض المحرك مُسبقًا.
• السياق. يُرجع getContext() القيمتين conformance_mode (الوضع المُعلَن، على سبيل المثال pdfa4) وfeature (الميزة المرفوضة، على سبيل المثال Screen annotation). وكلاهما خاصيتان عامتان للقراءة فقط. والسبب هو رسالة الاستثناء.
• التعافي. إجراء مطوِّر: أسقِط استدعاء الوسائط المتعددة للخرج الأرشيفي، أو استهدف ملف تعريف مطابقة غير أرشيفي (الافتراضي ConformanceMode::Plain).

PdfRViolationException

• متى يُطلَق. عندما يُنتهَك ثابت مطابقة ⁨PDF/R-1⁩ (⁨ISO 23504-1:2020⁩)، إمّا عند بناء كائن القيمة (ملفات تعريف PdfRStrip وPdfRPage وPdfRDocument) أو وقت المُتحقِّق (PdfRValidator). ويلتقط البند المعياري المُخالف ووصف انتهاك من سطر واحد حتى يستطيع مستهلكو التدقيق توجيه النتائج إلى البند الفرعي ⁨§6⁩ الصحيح دون تحليل نصّ حرّ.
• السياق. يُرجع getContext() القيم standard (دائمًا ISO 23504-1:2020)، وclause (مسار البند، على سبيل المثال 6.6.1)، وviolation. المُلتقِطات ذات الأنواع: getClause() وgetViolation().
• التعافي. إجراء مطوِّر: صحّح المُدخَل المرفوض أو أعد بناء المستند ليطابق البند المُستشهَد به.

توليد الرموز الشريطية

BarcodeException

• متى يُطلَق. عندما يُخفق توليد الرمز الشريطي بسبب بيانات غير صالحة أو أخطاء ترميز عبر كل الرموز المدعومة (⁨Code 39/128⁩، ⁨UPC-A/E⁩، ⁨EAN-8/13⁩، ⁨Interleaved/Standard 2-of-5⁩، ⁨POSTNET⁩، ⁨PLANET⁩، ⁨MSI⁩، ⁨ISBN⁩، ⁨ISSN⁩، ⁨QR Code⁩، ⁨PDF417⁩، ⁨DataMatrix⁩، ⁨JabCode⁩)، وإخفاقات عرض ⁨GD⁩ أثناء إنشاء الصورة. وتُحدَّد قيمة الرمز الشريطي بمقتطف لا يتجاوز 128 بايت في الرسالة والسياق — فالحمولات المُفرِطة الطول أو الثنائية تُخزَّن مُقتطَعة مع علامة ... (<N> bytes, truncated) حتى لا يمكن نسخها كاملةً إلى سجلّ.
• السياق. يُرجع getContext() القيمتين barcode_type (الرمز، على سبيل المثال QRCODE، EAN13، CODE128) وvalue (القيمة المُقتطَعة). المُلتقِطات ذات الأنواع: getBarcodeType() وgetValue().
• التعافي. إجراء مطوِّر: صحّح بيانات الرمز الشريطي أو اختيار الرمز.

BarcodeEncoderNotFoundException

• متى يُطلَق. من BarcodeEncoderRegistry عندما يكون نوع المُرمِّز المطلوب غير معروف أو تكون بوّابة قدرته مُغلقة. ويطبّق أيضًا ⁨PSR⁩-11 Psr\Container\NotFoundExceptionInterface، فيكون السجلّ حاويةً مطابقة للمعايير. وتذكر الرسالة الرمز والسبب.
• السياق. لا يتجاوز getContext()، فيُرجع مصفوفة فارغة. والقيمتان type وreason متاحتان عبر المُلتقِطين getType() وgetReason() وفي الرسالة.
• التعافي. إجراء مطوِّر: سجّل المُرمِّز، أو ثبّت الحزمة التي توفّره (على سبيل المثال nextpdf/pro لأجل ⁨Micro QR⁩ / ⁨DotCode⁩ / ⁨HanXin⁩ / ⁨JabCode⁩).

التشفير والترميز والتوقيعات

EncryptionException

• متى يُطلَق. عندما يُخفق تشفير ⁨PDF⁩ أو فكّ تشفيره: إخفاقات تشفير/فكّ تشفير ⁨AES-256-CBC⁩، وأخطاء ⁨OpenSSL⁩، وأحجام متجه تهيئة غير صالحة، وإخفاقات حساب التجزئة، وأخطاء حساب قيمتي ⁨UE/OE⁩. وعادةً امتداد ⁨OpenSSL⁩ مفقود أو سيئ الإعداد، أو مادة مفتاح غير صالحة، أو بيانات مُشفَّرة تالفة. وتذكر الرسالة العملية والخوارزمية.
• السياق. يُرجع getContext() القيمتين algorithm (على سبيل المثال AES-256-CBC) وoperation (على سبيل المثال encrypt، decrypt، key_derivation). المُلتقِطات ذات الأنواع: getAlgorithm() وgetOperation().
• التعافي. إجراء بنية تحتية: تأكّد من توفّر ⁨OpenSSL⁩ وإعداده بصورة صحيحة. انظر التشفير والأذونات.

UnsupportedAlgorithmException

• متى يُطلَق. عندما لا يمكن تنفيذ خوارزمية تشفير في وقت التشغيل الحالي: امتداد ⁨PHP⁩ مطلوب غير متاح، أو تفتقر المكتبة الأساسية إلى الأداة الأولية، أو لا يستطيع امتداد hash المُجمَّع تركيب متغيّر ⁨SHAKE/XOF⁩، أو الخوارزمية غير مُسجَّلة في SignatureAlgorithmRegistry. ويجب ألا يتدهور المحرك بصمت إلى أداة أولية أضعف، فيُظهِر هذا بدلًا من ذلك. ويُطلقه المصنع الساكن nonFipsHostUnderFipsProfile() (مع مُعرِّف الخوارزمية regulatory-profile:fips) عندما يُختار RegulatoryProfile::FIPS لكن لا يمكن تأكيد مزوّد ⁨OpenSSL⁩ مُدقَّق بـ⁨FIPS⁩ (يُخفق كلٌّ من FIPS_ABSENT وINDETERMINATE بأمان).
• السياق. يُرجع getContext() القيمتين algorithm (الاسم أو ⁨OID⁩، على سبيل المثال shake256، Ed25519، AES-256-GCM) وreason (قابل لتنفيذ المُشغِّل). المُلتقِطات ذات الأنواع: getAlgorithm() وgetReason().
• التعافي. إجراء مُشغِّل: ثبّت الامتداد المفقود أو رقِّ وقت التشغيل؛ ولبوّابة ⁨FIPS⁩، ثبّت بناء ⁨OpenSSL⁩ مُدقَّقًا بـ⁨FIPS⁩ أو اضبط NEXTPDF_FIPS_MODE صراحةً. إجراء مطوِّر: سجّل واصف خوارزمية مخصّصًا عبر SignatureAlgorithmRegistry::register().

SignatureException

• متى يُطلَق. عندما تُخفق عملية توقيع رقمي: معالجة الشهادات والمفاتيح الخاصة (تحليل ⁨PKCS#12⁩، وفكّ ترميز ⁨PEM/DER⁩، والتحقق من ⁨X.509⁩)، وبناء ⁨PKCS#7/CMS⁩، وصيغة توقيع ⁨ECDSA⁩، وانتهاكات حجم الحاوية، وترميز ⁨DER⁩، وتنسيق ⁨PAdES⁩. وتُبلِّغ عن أخطاء ⁨TSA⁩ المحددة بدلًا من ذلك TsaException الأكثر تحديدًا. فضّل المصانع المسماة ذات الأنواع على المُنشئ الموضعي؛ فكلٌّ منها يربط السبب الجذري بذيل الرسالة. أمثلة: ltvCapabilityMissing() (يحتاج ⁨B-LT/B-LTA⁩ إلى nextpdf/enterprise)، وtsaRequired() / tsaUrlEmpty() / tsaEmptyToken()، وhttpClientMissing()، وhsmSignerMissing() / hsmSignatureEmpty()، وsignatureContentsNotFound() / signatureContentsPaddingCorrupt()، وunexpectedKeyType()، وpemDecodingFailed()، وعائلة ⁨Ed25519⁩ (ed25519SignatureMalformed()، وed25519RoundTripVerifyFailed()، وed25519KeyParseFailed()، وed25519SeedInvalid()، وed25519SecretKeyMalformed()، وed25519PublicKeyInvalid())، وdocumentTimestampNotEmitted()، وalgorithmPolicyRejected()، وdigestOnlyAlgorithmRefused()، وencryptedLtvUnsupported()، وincrementalUpdateWriterMissing()، وزوج حالة ⁨OCSP⁩ nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus() (⁨RFC 6960 §4.2.1⁩). وتُخفق هذه المصانع بأمان بدلًا من إصدار توقيع مُخفَّض المستوى بصمت.
• السياق. يُرجع getContext() القيم cert_info (الاسم المميَّز للموضوع أو البصمة، أو فارغ)، وsignature_level (مستوى ⁨PAdES⁩ المُحاوَل، على سبيل المثال B-B، B-T، B-LT، B-LTA)، وdetail (التشخيص القابل للتنفيذ، فارغ للمُنشئ الموضعي القديم). المُلتقِطات ذات الأنواع: getCertInfo() وgetSignatureLevel() وgetDetail().
• التعافي. إجراء مطوِّر: أصلِح تهيئة الشهادة/المفتاح. ولمصانع القدرة المفقودة، ثبّت الحزمة المسماة. انظر إخفاقات التوقيع والطابع الزمني لأجل مداخل العَرَض والحلّ لكل مصنع.

BlackPointCompensationUnsupportedException

• متى يُطلَق. من NullBlackPointCompensationTransform::transform() عندما يطلب مُستدعٍ من المُهايِئ الفارغ تطبيق تحويل تعويض النقطة السوداء وفق ⁨ISO 18619⁩ غير Default. والمُهايِئ الفارغ هو البديل الآمن للبيئات التي لا خلفية إدارة لون فيها؛ فإنتاج عيّنة مُحوَّلة دون وحدة إدارة لون حقيقية كان سيُبلِّغ خطأً عن التحويل بصمت. وخلافًا لمعظم المداخل هنا، يمدّد هذا \RuntimeException مباشرةً، لا NextPdfException، فتبقى مسارات catch (\RuntimeException) القائمة تعمل.
• السياق. لا getContext()؛ فهو \RuntimeException عادي. والتفاصيل في الرسالة.
• التعافي. إجراء مطوِّر: سجّل BlackPointCompensationTransform حقيقيًا (⁨LittleCMS⁩، ⁨Argyll⁩، ⁨PHP⁩ صرف)، أو احصر /UseBlackPtComp على BlackPointCompensation::Default.

تجميع المستند وإمكانية الوصول

UnsupportedSourceDocumentException

• متى يُطلَق. عندما لا يمكن نسخ مستند مصدر بأمان إلى خرج دمج/تقسيم وتُخفق العملية بأمان بدلًا من إصدار نتيجة تالفة أو منقوصة الأمان. استخدم المصانع المسماة: encrypted() (⁨ISO 32000-2 §7.6⁩ — لا يمكن نسخ المحتوى دون المفتاح)، وsigned() (§⁨12.8⁩ — نسخ الصفحات سيُبطِل مدى بايتات التوقيع)، وunsupportedStreamFilter() (مُرشِّح لا يستطيع قارئ مخطط الكائنات إرجاعه ذهابًا وإيابًا)، وmultipleInteractiveForms() (قيد مُوثَّق: يحمل أكثر من مصدر واحد /AcroForm غير فارغ، §⁨12.7⁩)، وsplitWithInteractiveForm() (قيد مُوثَّق: تقسيم صفحات مصدر يحمل نموذجًا سيُيتِّم الأدوات). يمدّد \RuntimeException مباشرةً، لا NextPdfException.
• السياق. لا getContext()؛ فهو \RuntimeException عادي. والسبب ورقم الكائن المتأثر مذكوران في الرسالة.
• التعافي. إجراء مطوِّر: فكّ تشفير المصدر أولًا أو وفّر المفتاح؛ وللمصادر المُوقَّعة، وقّع بعد الدمج بدلًا من ذلك؛ ولعمليات دمج متعددة النماذج، سطّح حقول النموذج لكل المصادر إلّا واحدًا أو أزِلها؛ ولعمليات تقسيم تحمل نموذجًا، سطّح النموذج قبل التقسيم.

InvalidBcp47TagException

• متى يُطلَق. من Bcp47Validator::validate() عندما يكون وسم لغة مُرشَّح مُشوَّهًا وفق ⁨RFC 5646 §2.1⁩ ⁨ABNF⁩، أو يُخفق في البحث في السجلّ المُنتقى. خاص بمجال ⁨BCP-47⁩ / ⁨ISO 14289-2:2024 §8.4.4⁩، متميّز عن InvalidConfigException حتى يستطيع المُستدعون في مصبّ حدّ إمكانية الوصول اعتراض نوع ضيّق. ويبقى زوج المحمولات Bcp47Validator::isWellFormed() / isValid() سطح القيمة المُرجَعة المتوافق رجعيًا للمُستدعين الذين يُفضِّلون التفرّع على الاستثناءات.
• السياق. يُرجع getContext() القيمتين tag (المُرشَّح كما قُدِّم بالضبط) وreason (رمز رفض ثابت قابل للقراءة آليًا، على سبيل المثال empty-string، well-formed-shape، unregistered-primary، duplicate-variant). المُلتقِطات ذات الأنواع: getTag() وgetReason().
• التعافي. إجراء مطوِّر: صحّح وسم اللغة إلى وسم ⁨BCP-47⁩ سليم الشكل مُسجَّل. انظر الخطوط والوسم.

FormFieldAccessibilityException

• متى يُطلَق. عندما يعتمد حقل نموذج تفاعلي على اسم قابل للوصول مُصطنَع (غير مُقدَّم من المؤلِّف) أثناء إنتاج مستند ⁨PDF/UA⁩ مع تفعيل الإنفاذ الصارم لاسم الحقل القابل للوصول. ويُصدر خرج ⁨PDF/UA⁩ الافتراضي اسم بديل مُصطنَعًا في /Contents للأداة حتى لا يكون أي حقل بلا اسم؛ بينما يتطلب الوضع الصارم بدلًا من ذلك أن يُقدِّم المؤلِّف اسمًا ذا معنى (تلميحًا، أو تسمية توضيحية لزرّ دفع بلا إجراء) حتى يحصل مستخدمو قارئ الشاشة على وصف حقيقي (⁨ISO 14289-2:2024 §8.10.2⁩).
• السياق. لا يتجاوز getContext()، فيُرجع مصفوفة فارغة. والقيمة $fieldId خاصية عامة للقراءة فقط؛ والسبب هو الرسالة.
• التعافي. إجراء مطوِّر: وفّر تلميحًا / اسمًا قابلًا للوصول للحقل المسمى قبل إنتاج مستند ⁨PDF/UA⁩ صارم، أو عطّل الوضع الصارم. انظر التحقق من ⁨PDF⁩/A و ⁨PDF⁩/UA.

VendorExtensionRegistryConflictException

• متى يُطلَق. من VendorExtensionRegistry::register() عندما يُعيد مُستدعٍ تسجيل سابقة بائع امتداد مطوِّر ⁨PDF⁩ معروفة (⁨ISO 32000-2:2020 §7.12.1⁩) بوصف يختلف مع البيانات الوصفية المُسجَّلة سابقًا. والواصفات للإلحاق فقط ومُكتشَفة التعارض؛ وقد حلّ الاستثناء ذو النوع محلّ \RuntimeException عام حتى يستطيع المُستدعون اعتراض هذه الفئة المحددة.
• السياق. يُرجع getContext() القيم prefix، وexisting_description، وattempted_description. المُلتقِطات ذات الأنواع: getPrefix() وgetExistingDescription() وgetAttemptedDescription().
• التعافي. إجراء مطوِّر: سجّل السابقة بالوصف القائم، أو استخدم سابقة متمايزة؛ لا تكتب فوق البيانات الوصفية المُسجَّلة.

تصدير التدقيق

AuditExportException

• متى يُطلَق. عندما يُخفق تجميع حزمة تصدير التدقيق، أو توليد مصفوفة التتبّع، أو إسقاط المخطط في وقت التشغيل. ويغطي الإدخال/الإخراج مقابل claims.json / manifest.json، وترميز/فكّ ترميز ⁨JSON⁩ للحزمة المعيارية، وعدم تطابق إصدار المخطط في مسار التوافق الرجعي AuditExporter::projectToV1(). وتذكر الرسالة المرحلة، والقطعة الأثرية عند معرفتها، والتفصيل.
• السياق. يُرجع getContext() القيم stage (على سبيل المثال read_claims، encode_bundle، project_v1)، وdetail، وartefact (المسار أو ⁨schema_version⁩ الذي أطلق الإخفاق). المُلتقِطات ذات الأنواع: getStage() وgetDetail() وgetArtefact().
• التعافي. إجراء مطابقة / ⁨DevOps⁩: تحقّق من مسارات القطع الأثرية المُدخَلة، أو أعد توليد claims.json من تشغيل نظيف، أو أعد بناء البيان قبل إعادة محاولة التصدير.

كائنات قيمة الانتهاك

هذه ليست استثناءات. إنها كائنات قيمة غير قابلة للتغيير يُرجعها المحرك لوصف انتهاك فردي؛ وهي لا تحمل getContext().

ComplianceViolation

• ما هو. كائن قيمة final readonly يمثّل إخفاق قاعدة واحدة يُبلِّغ عنه مُتحقِّق خارجي (⁨veraPDF⁩ أو مكافئ)، بما في ذلك مرجع بند ⁨ISO⁩ والموقع داخل بنية ⁨PDF⁩.
• الحقول. خصائص عامة للقراءة فقط: ruleId (مُعرِّف قاعدة المُتحقِّق، على سبيل المثال 6.1.2-1)، وclause (مرجع بند ⁨ISO⁩، على سبيل المثال ISO 19005-1:2005, 6.1.2)، وseverity (على سبيل المثال error، warning)، وlocation (مسار الكائن داخل بنية ⁨PDF⁩)، وmessage (وصف قابل لقراءة الإنسان).
• الاستخدام. افحص المجموعة التي يُرجعها مُتحقِّق المطابقة؛ ووجّه كل مدخل أو اعرضه بحسب severity وclause. انظر التحقق من ⁨PDF⁩/A و ⁨PDF⁩/UA.

RuleViolation

• ما هو. كائن قيمة final readonly يمثّل انتهاك قاعدة عمل واحدة وفق ⁨Schematron⁩ / ⁨EN 16931⁩، يُرجعه SchematronRunnerInterface::runRules() ويُجمَّع داخل ValidationResult::$ruleViolations. والاستقرار تجريبي.
• الحقول. خصائص عامة للقراءة فقط: ruleId (مُعرِّف ⁨EN 16931⁩ مثل BR-{n}، BR-CO-{n}، BR-CL-{n}، BR-DEC-{n}، أو حزمة خاصة بمرتبة)، وseverity (تعداد RuleSeverity)، وmessage (نصّ القاعدة، ⁨en-GB⁩)، وxpath (⁨XPath⁩ في ⁨XML⁩ المُضمَّن، null لقواعد المستند بأكمله)، وsemanticPath (مسار ⁨BG/BT⁩ بترميز نقطي مثل BG-22.BT-106، null للانتهاكات البنيوية).
• الاستخدام. افحص المجموعة على نتيجة التحقق؛ ووجّه كل مدخل أو اعرضه بحسب severity وruleId والمُحدِّد.

انظر أيضًا

• فهرس مرجع الأخطاء
• فهرس قاعدة المعرفة
• إخفاقات التوقيع والطابع الزمني
• التشفير والأذونات
• الخطوط والوسم
• التحقق من ⁨PDF⁩/A و ⁨PDF⁩/UA