قاعدة معرفة لاستكشاف الأخطاء وإصلاحها

ما الذي تغطّيه قاعدة المعرفة هذه

استخدم قاعدة المعرفة هذه لربط الإخفاق الذي تراه بسببه وحلّه. يستند كل مدخل إلى أصناف الاستثناءات في المحرك، واختبارات مسارات الإخفاق، وحراس المصدر، لا إلى التخمين. إذا لم يكن في المحرك مسار شفرة لإخفاق معيّن، فلا تختلق قاعدة المعرفة هذه مسارًا له.

تتضمن قاعدة المعرفة أربع صفحات موضوعية:

• التحقّق من التوقيع — التواقيع غير الصالحة، والسلاسل غير المكتملة، والإبطال غير المعروف، وإخفاقات الطابع الزمني.
• التحقّق من ⁨PDF/A⁩ و⁨PDF/UA⁩ — مشكلات ⁨Portable Document Format/Archive⁩ (⁨PDF/A⁩) و⁨Portable Document Format/Universal Accessibility⁩ (⁨PDF/UA⁩)، بما في ذلك غياب قصد الإخراج، والمحتوى غير الموسوم، وغياب اللغة، وإخفاقات الخطوط المضمّنة.
• الخطوط والوسم — تعذّر العثور على الخط، وإنشاء المجموعات الجزئية، وتغطية ⁨CJK⁩، ومشكلات شجرة البنية.
• التشفير والأذونات — إخفاقات فكّ التشفير وحدّ راية الأذونات.

كيفية قراءة المدخل

يتكوّن كل مدخل من خمسة أجزاء:

1. العَرَض — ما تراه: صنف استثناء، أو جزء من رسالة، أو حكم مدقّق لاحق.
2. السبب المُرجَّح — شرط الإدخال أو التهيئة الذي يبلّغ عنه المحرك.
3. الدليل / التشخيص — كيف تؤكد السبب. يذكر هذا الجزء صنف الاستثناء المحدّد بدقّة، أو حقل getContext()، أو الاختبار الذي يُظهر السلوك، حتى تتحقق منه بدلاً من التخمين.
4. الحل — خطوات مرتّبة لإزالة السبب.
5. ذو صلة — صفحة مرجع الوحدة أو المدخل الشقيق الذي ينبغي أن تقرأه تالياً.

تحديد الإخفاق حسب نوع الاستثناء

يحدّد ⁨NextPDF⁩ الخطأ عبر صنف ⁨PHP⁩ الخاص به، لا عبر رمز خطأ نصّي. لا يوجد أي ثابت NPDF-#### في أصناف الاستثناءات. التقط الاستثناء الطرفي عندما تحتاج إلى استجابة موجّهة، واقرأ ContextAwareExceptionInterface::getContext() للحصول على حقول تشخيصية منظّمة. استخدم NextPDF\Exception\NextPdfException بوصفه النوع الأساسي؛ وتستخدم إخفاقات الأمان كذلك NextPDF\Security\Exception\SecurityException.

للاطّلاع على التسلسل الهرمي الكامل وقواعد ترتيب الالتقاط، اقرأ مرجع الاستثناءات.

<?php

declare(strict_types=1);

use NextPDF\Exception\NextPdfException;
use NextPDF\Contracts\ContextAwareExceptionInterface;

try {
    // ... engine call ...
} catch (NextPdfException $e) {
    $context = $e instanceof ContextAwareExceptionInterface
        ? $e->getContext()
        : [];
    \error_log($e->getMessage());
    // $context carries snake_case primitive fields safe to serialize.
}

النطاق والحدود

توضح قاعدة المعرفة هذه كيف يكتشف المحرك الإخفاقات ويبلّغ عنها. ولا تغطي أحكام المطابقة الصادرة عن مدقّقات خارجية، مثل ⁨veraPDF⁩ أو ⁨callas⁩؛ فتلك الأدوات تطبّق مجموعات قواعدها الخاصة. عندما يرفض المحرك عملية للحفاظ على مستند ضمن تشكيلة، مثل رفض التشفير تحت ⁨PDF/A⁩، يورد المدخل المعني البند الحاكم والاستثناء الذي يفرضه.

انظر أيضًا

• مرجع الاستثناءات — التسلسل الهرمي الكامل، وترتيب الالتقاط، وعقد getContext()
• مرجع المطابقة — مُدقّقات تشكيلات ⁨PDF/A⁩ و⁨PDF/UA⁩ و⁨PDF/X⁩

المسرد: الاستثناء المدرك للسياق