مرجع الأخطاء

هذه هي القائمة المرجعية للاستثناءات التي يُطلقها ⁨NextPDF Core⁩، مُنظَّمةً بحسب المجال. توثّق كل صفحة فئة، لكل فئة، متى تُطلَق، والبيانات المُنظَّمة التي تحملها، وكيفية التعافي منها. إذا كنت تشخّص عَرَضًا بدلًا من اعتراض فئة محددة، فابدأ بدلًا من ذلك بـأدلة استكشاف الأخطاء وإصلاحها — فهي مُنظَّمة بحسب ما تلاحظه.

لمحة سريعة

• تمدّد معظم الاستثناءات فئة أساسية واحدة، NextPdfException، حتى تتمكن من اعتراض العائلة كاملةً بكتلة catch واحدة.
• NextPdfException مُدركة للسياق: فهي تطبّق ContextAwareExceptionInterface التي تعلن عن getContext(): array. تتجاوز فئات فرعية كثيرة getContext() لتُرجع مفاتيح تشخيصية مُنظَّمة؛ بينما ترث أخرى القيمة الافتراضية الفارغة وتكشف تفاصيلها عبر الرسالة وعبر مُلتقطات ذات أنواع.
• يمدّد عدد قليل من الاستثناءات منخفضة المستوى فئة ⁨PHP⁩ المسماة \RuntimeException مباشرةً بدلًا من NextPdfException. وهذه ليست مُدركة للسياق، وتحمل تفاصيلها على خصائص عامة للقراءة فقط. تُشير كل صفحة فئة إليها صراحةً.
• نوعان للمطابقة باسم ينتهي بـ…Violation (ComplianceViolation وRuleViolation) هما كائنا قيمة، لا استثناءان — فهما يصفان نتيجة من دون أن يُطلَقا.

النوع الأساسي وعقد السياق

NextPdfException فئة مُجرَّدة تمدّد \RuntimeException وتطبّق ContextAwareExceptionInterface. العقد صغير:

interface ContextAwareExceptionInterface
{
    /** @return array<string, mixed> structured, log-safe diagnostic context */
    public function getContext(): array;
}

ولذا يبدو المُعالِج الدفاعي على هذا النحو:

use NextPDF\Exception\NextPdfException;

try {
    // … NextPDF operation …
} catch (NextPdfException $e) {
    $logger->error($e->getMessage(), $e->getContext());
    // getContext() returns [] when a subclass does not override it;
    // the message and any typed getters still carry the detail.
}

ولأن بعض الإخفاقات تظهر بوصفها \RuntimeException مجرّدة (انظر الملاحظات الخاصة بكل فئة)، فقد يعترض حدٌّ مزدوج الاحتراز أيضًا \RuntimeException ويفحص النوع الفعلي.

الفئات

• أخطاء النواة والأخطاء العامة — إخفاقات المستند، والدمج، وإمكانية الوصول، والفاتورة الإلكترونية، وفضاء اللون، وكائن القيمة، والوضع الصارم، إضافةً إلى الأنواع الأساسية المشتركة.
• أخطاء الأمان والتوقيع والبنية التحتية للمفتاح العام (PKI) — إنشاء التوقيع والتحقق منه، والطوابع الزمنية، والتحقق من مسار البنية التحتية للمفتاح العام (PKI) ومن قيود الأسماء، والتجزئة، والسلامة، و⁨PKCS#11⁩.
• أخطاء العرض والإدخال/الإخراج — تخطيط ⁨HTML⁩ والوسائط المقسّمة على صفحات، والخطوط وتشكيل النص، والكاتب والقارئ، وبيانات ⁨XMP⁩ الوصفية.
• أخطاء وقت التشغيل والدعم — نقل ⁨HTTP⁩، والمرونة (قاطع الدارة، والوضع المتدهور)، وقابلية الملاحظة، ومعالجة بيان العرض.
• أخطاء المُسرِّع — نقل العربة الجانبية الاختيارية للتسريع.
• أخطاء المطابقة — متطلبات تجزئة البنود ودورة حياة المطابقة.

انظر أيضًا

• استكشاف الأخطاء وإصلاحها — أدلة مُنظَّمة بحسب العَرَض لأجل التحقق من التوقيع، والتشفير والأذونات، والخطوط والوسم، والتحقق من ⁨PDF⁩/A و ⁨PDF⁩/UA.