أخطاء وقت التشغيل والدعم

النطاق

توثّق هذه المداخل الاستثناءات التي تُطلقها طبقة دعم وقت التشغيل: سياسة التدهور، ونقل ⁨HTTP⁩ المدعوم بـ⁨cURL⁩، وقاطع دارة المرونة، ومُصدِر إدارة معلومات الأمن والأحداث (⁨SIEM⁩)، وبيان العرض، وفحص ⁨PDF⁩، والنظام الفرعي لهندسة الفوضى.

يمدّد كل استثناء في ⁨NextPDF⁩ الفئة NextPdfException، التي تطبّق ContextAwareExceptionInterface وتكشف getContext(): array للتسجيل التشخيصي المُنظَّم. ولا تملأ الفئة الفرعية تلك المصفوفة إلا حين تتجاوز getContext()؛ ويُرجع الأساس مصفوفة فارغة. تمدّد ثلاثة استثناءات في هذه الصفحة (DegradedException وCircuitBreakerOpenException وInspectException) فئة ⁨PHP⁩ المسماة RuntimeException مباشرةً وتكشف بياناتها عبر خصائص عامة readonly بدلًا من getContext(). ويذكر كل مدخل أدناه الخصائص أو مفاتيح السياق التي تحملها الفئة بالضبط، مأخوذةً من المصدر.

سياسة التدهور

DegradedException

• يُطلَق عند. ملاقاة خط أنابيب العرض قدرةً متدهورة تنتهك سياسة التدهور النشطة. تحت DegradationPolicy::Strict، يُطلقه أي تدهور عالي الأثر (ComplianceRisk أو SemanticLoss أو Blocking)؛ وتحت DegradationPolicy::Balanced، لا يُطلقه إلا أثر Blocking.
• الفئة. تمدّد RuntimeException مباشرةً (لا NextPdfException)، لذا لا تحمل getContext().
• البيانات المحمولة. خاصيتان عامتان readonly: $capability (كائن القيمة Capability الذي أطلق الرفض، بما في ذلك id وstatus وreason وfallbackTarget وimpact الخاصة به) و$policy (سياسة DegradationPolicy النشطة وقت الرفض). وتأخذ الرسالة الهيئة Feature "<id>" is <status>: <reason> (policy: <policy>).
• التعافي. افحص $capability لتحديد الميزة المفقودة وسببها. وإمّا أن تثبّت المكوّن الذي تحتاجه القدرة، أو تقبل إعدادًا أقل أثرًا، أو تخفّف السياسة من Strict إلى Balanced حين يكون التدهور مقبولًا لحالة الاستعمال. استدعِ $capability->isAvailable() / isDegraded() لقيادة الرسائل الموجَّهة للمستخدم.

نقل ⁨HTTP⁩

تنشأ هذه الاستثناءات الثلاثة في عميل ⁨PSR⁩-18 المدعوم بـ⁨cURL⁩ ومُزخرِفه المُدرك للأمان. يمدّد الأولان NextPdfException لكنهما لا يتجاوزان getContext()، لذا يُرجع getContext() لكليهما مصفوفة فارغة؛ ويُوصَل إلى البيانات التشخيصية عبر مُلتقِط ⁨PSR⁩-18 getRequest() وعبر القابل للإطلاق السابق المُتسلسل.

CurlNetworkException

• يُطلَق عند. تعذّر إتمام طلب ⁨HTTP⁩ بسبب عطل على مستوى الشبكة: إخفاق تحليل نظام أسماء النطاقات (⁨DNS⁩)، أو مهلة اتصال، أو خطأ مصافحة أمان طبقة النقل (⁨TLS⁩). وهو أيضًا الفئة التي يُطلقها المُزخرِف المُدرك للأمان لرفض أمني (رفض تزوير الطلب من جانب الخادم، أو رفض إعادة ربط ⁨DNS⁩، أو إعادة توجيه مرفوضة).
• الفئة. تطبّق ⁨PSR⁩-18 Psr\Http\Client\NetworkExceptionInterface.
• البيانات المحمولة. يُرجع getRequest() الكائن RequestInterface المُخفِق. وخطأ النقل المنشئ، عند وجوده، هو القابل للإطلاق السابق المُتسلسل. يُرجع getContext() مصفوفة فارغة (الافتراضي الأساسي).
• التعافي. قد يكون عطل الشبكة عابرًا — أعد المحاولة مع تراجع تدريجي إن كان الطلب مُتكرِّر النتيجة. أما الرفض الأمني فليس عابرًا ويجب أن يُخفق بأمان: لا تُعِد المحاولة؛ بل صحّح عنوان ⁨URL⁩ الهدف أو سياسة ⁨SSRF⁩. اقرأ الرسالة والقابل للإطلاق السابق للتفريق بين الاثنين.

CurlRequestException

• يُطلَق عند. تعذّر إرسال الطلب نفسه لأنه مُشوَّه، على سبيل المثال عنوان ⁨URL⁩ غير صالح أو طلب أخفق في التحقق من ⁨SSRF⁩ قبل أي استدعاء شبكة.
• الفئة. تطبّق ⁨PSR⁩-18 Psr\Http\Client\RequestExceptionInterface.
• البيانات المحمولة. يُرجع getRequest() الكائن RequestInterface المُخالف؛ والسبب الأساسي، عند وجوده، هو القابل للإطلاق السابق المُتسلسل. يُرجع getContext() مصفوفة فارغة.
• التعافي. هذا عيب في مُدخَل المُستدعي أو في السياسة، لا عطل عابر. لا تُعِد المحاولة من دون تغيير. أصلِح عنوان ⁨URL⁩ للطلب أو الترويسات أو الجسم، أو عدّل قائمة سماح ⁨SSRF⁩ إن كان الهدف مسموحًا به مشروعًا، ثم أعِد إصدار الطلب.

TransientHttpException

• يُطلَق عند. داخليًا، داخل SecurityAwareHttpClient، لوسم عطل نقل داخلي عابر فعلًا (⁨DNS⁩ أو اتصال أو مهلة يُطلقها عميل ⁨PSR⁩-18 الداخلي) بوصفه مؤهَّلًا لميزانية إعادة المحاولة المحدودة. وهو الفئة الوحيدة المؤهَّلة لإعادة المحاولة التي تتعرّف عليها حلقة إعادة المحاولة في المُزخرِف؛ ويُعامَل أي استثناء غير ملفوف (رفض أمني يُطلقه المُزخرِف) بوصفه قاتلًا.
• الفئة. تطبّق ⁨PSR⁩-18 Psr\Http\Client\NetworkExceptionInterface. مُعلَّمة بـ@internal — فهي تُنشَأ وتُفَكّ بالكامل داخل SecurityAwareHttpClient ولا تفلت أبدًا من المُزخرِف.
• البيانات المحمولة. يُرجع getRequest() الطلب المُخفِق. ويُحفَظ ClientExceptionInterface للنقل الداخلي الأصلي بوصفه القابل للإطلاق السابق المُتسلسل (getPrevious()) ويُعاد إظهاره حرفيًا للمُستدعي بمجرد استنفاد ميزانية إعادة المحاولة، فيبقى عقد ⁨PSR⁩-18 العام دون تغيير. يُرجع getContext() مصفوفة فارغة.
• التعافي. لا تعترض شفرة التطبيق هذا النوع مباشرةً. اعترض الاستثناء الداخلي المُعاد إظهاره الذي يُرجعه المُزخرِف بعد إنفاق ميزانية إعادة المحاولة، وعامِل الإخفاقات العابرة المتكرّرة بوصفها مشكلة توفّر في المنبع.

المرونة

CircuitBreakerOpenException

• يُطلَق عند. رفض CircuitBreaker في حالة CircuitBreakerState::Open استدعاءً بإخفاق سريع، قبل أي استدعاء لاحق. وهو موجود ليتيح للمُستدعين التمييز بين “الخدمة البعيدة غير قابلة للوصول الآن” (عطل نقل عابر يستحقّ التدهور) و”كان سيُستنزَف مجمع الاتصالات بهذا الاستدعاء” (إخفاق سريع، دون محاولة شبكة) — وهو تخفيف حجب الخدمة المُجمَّع المطلوب لعملاء البنية التحتية للمفتاح العام (⁨PKI⁩).
• الفئة. تمدّد RuntimeException مباشرةً، لذا لا تحمل getContext().
• البيانات المحمولة. خاصيتان عامتان readonly: $breakerName (مُعرِّف القاطع المفتوح) و$secondsUntilHalfOpen (فترة التهدئة التقريبية المتبقّية قبل أن ينتقل القاطع إلى نصف مفتوح). وتأخذ الرسالة الهيئة Circuit breaker "<name>" is OPEN (cooldown ~<n>s remaining); call rejected fail-fast.
• التعافي. لا تطرق القاطع — انتظر $secondsUntilHalfOpen على الأقل قبل إعادة المحاولة، أو دهوِر العملية. لم تُحاوَل أي استدعاء شبكة، لذا فهذا ليس دليلًا على أن الخدمة البعيدة نفسها أخفقت؛ بل هو ضغط عكسي يحمي مجمع الاتصالات.

قابلية الملاحظة

SiemEmitterException

• يُطلَق عند. تعذّر على مُصدِر أحداث ⁨SIEM⁩ استمرار سجلّ أو سلسلته. وهو يُظهِر الإخفاقات على مستوى نظام الملفات (open وlock وseek وwrite وfflush وread) وأعطال سلامة سلسلة التجزئة (chain: فهرس خارج الترتيب، أو سجلّ ذيل مُشوَّه، أو انحراف ذهابًا وإيابًا في ⁨JSON⁩) المشتركة بين سجلّ أحداث سلسلة التجزئة ومُهايِئات مُصدِر ملف أسطر ⁨JSON⁩.
• الفئة. تمدّد NextPdfException وتتجاوز getContext().
• مفاتيح السياق. operation (واحدة من open وlock وseek وwrite وfflush وread وchain)، وpath (مسار السجلّ الهدف)، وdetail (تفصيل قابل للقراءة مثل عدد البايتات أو الفهرس المتوقَّع مقابل الفعلي). ويُوصَل إليها أيضًا عبر getOperation() وgetPath() وgetDetail(). وتأخذ الرسالة الهيئة SIEM emitter <operation> failed for <path>: <detail>.
• التعافي. هذا قابل للمعالجة من قِبَل البنية التحتية أو عمليات الأمن، لا من قِبَل منطق التطبيق. تحقّق من حامل وحدة تخزين السجلّ، وأذونات الدليل، وواصفات الملفات المتاحة، وصحة نظام الملفات. ويُشير إخفاق عملية chain إلى إشارة عبث أو تلف في سجلّ التدقيق وينبغي التحقيق فيه، لا إعادة محاولته بصمت.

بيان العرض

RenderManifestException

• يُطلَق عند. تعذّر إنشاء RenderManifest أو فكّ تسلسله أو قراءته بسبب خطأ بنيوي أو خطأ نوع أو خطأ توافق مخطط. والبيان عقد عام مُؤرَّخ يُقدِّمه كل نقل (⁨CLI⁩، وطابور ⁨Laravel⁩، و⁨Symfony⁩، وواجهة ⁨API⁩ لـ⁨SaaS⁩)، لذا يُظهَر البيان المُشوَّه أو غير المتوافق مباشرةً بدلًا من إجباره على القيم الافتراضية.
• الفئة. تمدّد NextPdfException وتتجاوز getContext(). وتضبط المُنشئات المسماة رمزًا ثابتًا قابلًا للقراءة آليًا في فضاء الأسماء SPEC-MANIFEST-*:
  • RenderManifestException::shape() ← SPEC-MANIFEST-001 — خطأ شكل أو نوع أثناء RenderManifest::fromArray().
  • RenderManifestException::incompatibleVersion() ← SPEC-MANIFEST-002 — إصدار مخطط رئيسي غير متوافق (لا يمكن قراءته).
  • RenderManifestException::missingField() ← SPEC-MANIFEST-003 — حقل مطلوب مفقود أثناء إنهاء البنّاء.
  • RenderManifestException::unsupported() ← SPEC-MANIFEST-004 — بيان سليم الشكل يُشير إلى مُدخَل أو قالب لا يستطيع المُصيِّر الحالي حلّه (على سبيل المثال مُدخَل ⁨URI⁩ أو محرّك قوالب يعمل على المضيف فقط).
• مفاتيح السياق. manifest_code (مُعرِّف SPEC-MANIFEST-*) وreason (وصف الإخفاق القابل للقراءة). ويُوصَل إليهما أيضًا عبر getManifestCode() وgetReason(). وتأخذ الرسالة الهيئة [<code>] <reason>.
• التعافي. تفرّع بحسب manifest_code. بالنسبة إلى SPEC-MANIFEST-001 وSPEC-MANIFEST-003، أصلِح حمولة البيان (صحّح نوع الحقل أو وفّر الحقل المفقود). وبالنسبة إلى SPEC-MANIFEST-002، أعد توليد البيان مقابل إصدار مخطط رئيسي مدعوم أو رقِّ المُصيِّر. وبالنسبة إلى SPEC-MANIFEST-004، وفّر مُدخَلًا أو محرّك قوالب يستطيع الإصدار الحالي حلّه.

الفحص

InspectException

• يُطلَق عند. إخفاق فحص ⁨PDF⁩.
• الفئة. تمدّد RuntimeException مباشرةً (لا NextPdfException)، لذا لا تحمل getContext().
• البيانات المحمولة. خاصيتان عامتان readonly: $inspectCode (رمز قابل للقراءة آليًا في فضاء الأسماء INSPECT-*) و$retryable (قيمة منطقية تُشير إلى ما إذا كان ينبغي للمُستدعي إعادة المحاولة — على سبيل المثال عندما تكون عربة فحص جانبية مُعطَّلة مؤقتًا). والسبب المنشئ، عند وجوده، هو القابل للإطلاق السابق المُتسلسل.
• التعافي. تفرّع بحسب $inspectCode لأجل فئة الإخفاق المحددة. عندما تكون $retryable هي true، أعد المحاولة مع تراجع تدريجي لأن الإخفاق يُتوقَّع أن يكون عابرًا (مثل إعادة تشغيل عربة جانبية)؛ وعندما تكون false، عامِل المُدخَل أو الإعداد بوصفه العيب ولا تُعِد المحاولة من دون تغيير.

هندسة الفوضى

ChaosReportWriteException

• يُطلَق عند. تعذّر على ChaosScenarioRunner::writeReport() استمرار تقرير يوم الفوضى المُجمَّع إلى القرص. وهو بديل ذو نوع للمجال يحلّ محل خطأ وقت تشغيل عام، فيمكن للمُستدعين اعتراض إخفاق قرص التقرير المحدد دون خلطه بالأخطاء المُطلَقة داخل مُحاكيات السيناريو نفسها (يلتقط المُشغِّل تلك بوصفها حقول ChaosOutcome).
• الفئة. تمدّد NextPdfException وتتجاوز getContext().
• مفاتيح السياق. output_path (المسار المطلق الذي حاول المُشغِّل الكتابة إليه). ويُوصَل إليه أيضًا عبر getOutputPath(). وتأخذ الرسالة الهيئة ChaosScenarioRunner: failed to write report to "<path>".
• التعافي. هذا إخفاق على جانب الكتابة لمصبّ التقرير، لا للسيناريوهات. تحقّق من وجود دليل الخرج وقابليته للكتابة وتوفّر مساحة على القرص، ثم أعد تشغيل كتابة التقرير. ولا تتأثر نتائج الفوضى نفسها.

RetrievalUnavailableException

• يُطلَق عند. عدم توفّر نقطة نهاية استرجاع (على سبيل المثال خدمة التوليد المُعزَّز بالاسترجاع من ⁨Voyage⁩) وسقوط النظام احتياطيًا إلى الوضع المعتمد على المخزن فقط أو إخفاقه بأمان.
• الفئة. تمدّد NextPdfException وتتجاوز getContext().
• مفاتيح السياق. mode (وضع التشغيل بعد الإخفاق — CACHED_ONLY عندما تُقدَّم النتائج من المخزن الدلالي فقط، أو FAIL_CLOSED عندما يُرفض الطلب كليًا دون بيانات قديمة) وendpoint (نقطة النهاية التي صارت غير قابلة للوصول). ويُوصَل إليهما أيضًا عبر getMode() وgetEndpoint(). وتأخذ الرسالة الهيئة Retrieval endpoint "<endpoint>" is unavailable; operating in <mode> mode.
• التعافي. اقرأ mode لتعرف كيف تدهور النظام. تحت CACHED_ONLY، قد تكون النتائج قديمة؛ حدّثها بمجرد تعافي نقطة النهاية. وتحت FAIL_CLOSED، رُفض الطلب عمدًا ويجب إعادة محاولته بعد أن تصير نقطة النهاية قابلة للوصول. أعد اتصال نقطة النهاية (الشبكة، والاعتمادات، وصحة الخدمة) قبل الاعتماد على استرجاع حديث.

انظر أيضًا

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