أخطاء المطابقة

النطاق

تغطي هذه المداخل الاستثناءين الواقعين في فضاء الأسماء NextPDF\Compliance\Exception. ويُطلق كليهما النظام الفرعي للمطابقة: خط أنابيب تجزئة البنود المعياري، ودورة حياة المطابقة (مخزن أدلة مطابقة المستند، والمُرقِّي من المُدقَّق إلى النهائي، ومُراقب فترة التهدئة).

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

متطلبات وقت تشغيل تجزئة البنود

ClauseHashRequirementException

• متى يُطلَق. من ClauseHash::compute() عندما يفتقد وقت تشغيل ⁨PHP⁩ المضيف متطلبًا صارمًا من خط أنابيب تجزئة البنود المعياري. المتطلب الوحيد من هذا النوع حاليًا هو ext-intl، المُستخدَم لتطبيع صيغة التطبيع ⁨Unicode⁩ ⁨KC⁩ (⁨NFKC⁩). يُطلق موضع الإطلاق الوحيد الرسالة ClauseHash requires ext-intl for NFKC normalisation.
• لماذا يُخفق بأمان. يُلزِم composer.json بـext-intl، لذا لا يُطلَق هذا إلا في بيئة لاحقة سيئة الإعداد تحزّم ⁨NextPDF⁩ من دون ⁨intl⁩. يرفض خط الأنابيب حساب موجَز غير مُطبَّع وفق ⁨NFKC⁩ بدلًا من أن يُصدر بصمت تجزئةً غير متوافقة مع كل مستهلك آخر لتجزئة البنود.
• السياق. يُرجع getContext() مصفوفة فارغة. السبب مذكور في الرسالة.
• التعافي. إجراء المُشغِّل: ثبّت امتداد ⁨PHP⁩ المسمى intl وفعّله على المضيف، ثم أعد المحاولة. لا يوجد حلٌّ بديل داخل الشفرة؛ فالموجَز المُطبَّع لا يمكن إنتاجه من دونه.

إخفاقات دورة حياة المطابقة

ComplianceLifecycleException

• متى يُطلَق. من النظام الفرعي لدورة حياة المطابقة عند انتهاك ثابت بنيوي على claims.json أو على خط أنابيب استمراره في وقت التشغيل. وتمتد مواضع الإطلاق إلى المُرقِّي من المُدقَّق إلى النهائي، ومُراقب فترة التهدئة، والمخزن التزايدي لأدلة مطابقة المستند. والمُطلِقات الفعلية هي:
  • مستند جذر مُشوَّه — لا يُفكّ ترميز claims.json إلى كائن، أو ليس claims.standards كائن ⁨JSON⁩ (على سبيل المثال claims.json must decode to an object، وclaims.standards must be a JSON object، وclaims.json invalid JSON: <detail>).
  • إخفاقات القراءة — claims.json مفقود أو غير قابل للقراءة (على سبيل المثال claims.json not found at: <path>، وclaims.json unreadable at <path>).
  • إخفاقات الإدخال/الإخراج للكتابة الذرية في خط أنابيب الاستمرار — فتح الملف المؤقت، وflock، والكتابة القصيرة، وfflush، وإعادة التسمية الذرية rename، وكتابة العربة الجانبية (على سبيل المثال tmp open failed at <path>، وtmp flock failed at <path>، وtmp write short for <path>، وtmp fflush failed at <path>، وatomic rename failed for <path>، وsha256 sidecar write failed at <path>).
  • إخفاقات جانب المُرمِّز — يرفض json_encode() الحمولة الصادرة (على سبيل المثال claims.json encode failed: <detail>).
  • إخفاقات تهيئة مخزن الأدلة — يتعذّر على المخزن التزايدي إنشاء دليله الجذر أو الكتابة إليه (على سبيل المثال IncrementalEvidenceCache: cannot create rootDir <path>، وIncrementalEvidenceCache: write failed for <path>، وIncrementalEvidenceCache: rename failed for <path>).
  • انتهاكات ثابت داخلي — على سبيل المثال gmdate produced empty timestamp أو fqClauseId: empty clauseKey.
• لماذا توجد. هذا بديل ذو نوع للمجال يحلّ محل الاستخدام السابق لـ\RuntimeException في شفرة دورة الحياة والمخزن. وهو لا يغيّر عقد وقت التشغيل، لأن NextPdfException تمدّد \RuntimeException أصلًا؛ فتبقى عبارات catch (\RuntimeException $e) القائمة تعمل.
• السياق. يُرجع getContext() مصفوفة فارغة. المسار المُخالف والإخفاق المحدد مذكوران في الرسالة؛ كما تُسلسِل إخفاقات فكّ ترميز ⁨JSON⁩ وترميزه الاستثناء الأساسي \JsonException بوصفه الاستثناء السابق، فاقرأ getPrevious() لها.
• التعافي.
  • بالنسبة إلى أخطاء الشكل والقراءة، هذا إجراء مُشغِّل: افحص claims.json في المسار المذكور في الرسالة، وتأكّد من أنه ⁨JSON⁩ سليم الشكل جذره وعضو standards فيه كائنان، وتأكّد من وجوده وقابليته للقراءة.
  • بالنسبة إلى أخطاء الكتابة الذرية وتهيئة المخزن، تحقّق من وجود الدليل الهدف وأذوناته ومساحته الخالية، ثم أعد المحاولة.
  • بالنسبة إلى إخفاقات جانب المُرمِّز، هذا إجراء مطوِّر: الحمولة المُسلَّمة إلى json_encode() غير قابلة للترميز. التقط الاستثناء السابق المُتسلسل والرسالة لإعداد تقرير عيب.

انظر أيضًا

• فهرس مرجع الأخطاء
• التحقق من ⁨PDF⁩/A و ⁨PDF⁩/UA