دورة حياة جلسة آمنة في العمليات الخلفية عبر NextPDF Connect
لمحة سريعة
قسم بعنوان «لمحة سريعة»استخدم دورة حياة جلسة محصورة في نطاق الطلب داخل عملية PHP خلفية طويلة الأمد (RoadRunner أو Swoole أو Laravel Octane). ينشئ كل طلب جلسة المستند الخاصة به ويدمّرها بعد output_pdf. تبقى حالة الخط والصفحة والمقبض ضمن حدود طلب العملية الخلفية. الأدوات هي create_pdf، وset_font، وadd_text، وoutput_pdf — وكلها من Core.
التثبيت
قسم بعنوان «التثبيت»composer require nextpdf/serverاربط وسيلة نقل. يعمل هذا النمط بالطريقة ذاتها مع أي وسيلة نقل.
نظرة مفاهيمية عامة
قسم بعنوان «نظرة مفاهيمية عامة»المعرّف document_id هو مقبض مبهم محصور بطلب واحد. اتّبع قاعدة واحدة: أنشئ لكل طلب، ودمّر لكل طلب، ولا تخزّن مؤقتًا ولا تشارك أبدًا. مع القيمة الافتراضية destroy: true، يصيّر output_pdf المستند ويحرّر الجلسة في خطوة ذرّية واحدة. يحصل الطلب التالي الذي يعمل على العملية الخلفية نفسها على جلسة جديدة ومستقلة. تختفي إعدادات خط الجلسة السابقة ومحتواها. تكون نتيجة كل أداة استجابة نقل عادية (PSR-18 §p2). يُعزَل كود الخادم ضمن حدود التحميل التلقائي (PSR-4 §3). مخزن الجلسات هو الحالة الوحيدة المشتركة بين الطلبات، وهو مفهرس بالمعرّف.
سطح API
قسم بعنوان «سطح API»| الأداة | الدور | مستوى الخطورة |
|---|---|---|
create_pdf | فتح جلسة لكل طلب | آمنة |
set_font | تحديد الخط النشط (لكل جلسة) | تنبيه |
add_text | كتابة المحتوى | تنبيه |
output_pdf | تصيير الجلسة وتدميرها | موافقة مطلوبة / مراجعة (base64) |
كتالوج الأدوات هو المرجع المعتمد. تتوقف الأدوات المتاحة لك على المستوى المثبَّت.
نموذج كود — بداية سريعة
قسم بعنوان «نموذج كود — بداية سريعة»الطلب 1: create_pdf → set_font → add_text → output_pdf (destroy: true). يبدأ الطلب 2، على العملية الخلفية نفسها، جلسة create_pdf جديدة. يصبح المعرّف القديم غير صالح الآن. حدّد الخط مجددًا، لأنه لا ينتقل بين الجلسات.
نموذج كود — بيئة الإنتاج
قسم بعنوان «نموذج كود — بيئة الإنتاج»غلّف دورة الحياة بما يضمن تنفيذ التنظيف دائمًا:
- احصل على الجلسة عند بدء الطلب.
- ابنِ المحتوى.
- في كتلة مكافئة لـ
finally، استدعِoutput_pdf، الذي يدمّر الجلسة. إذا استخدمتdestroy: falseلتدفق فحص بعد الإخراج، فدمّر الجلسة صراحةً بدلًا من ذلك.
لا تخزّن أبدًا document_id في حاوية عامة أو ساكنة أو مشتركة للعملية الخلفية. لا تمرّره أبدًا بين الإجراءات المتزامنة أو الألياف أو معالِجات الطلبات.
الحالات الحدّية والمزالق
قسم بعنوان «الحالات الحدّية والمزالق»- إعادة استخدام المعرّف بعد التدمير. ينتج عنه خطأ مستند غير معروف. أنشئ جلسة جديدة لكل طلب.
- نسيان
output_pdf. تنمو الذاكرة بصمت حتى تنتهي مدة بقاء الجلسة (TTL) أو تُعاد تهيئة العملية. أنهِ دورة الحياة دائمًا. - حد الجلسات تحت الحمل. للمخزن حد أقصى للجلسات المتزامنة. يساعدك التدمير الفوري على البقاء دونه.
destroy: falseدون تنظيف. تنمو الذاكرة تدريجيًا. استخدمها فقط لتدفق فحص صريح بعد الإخراج، ثم دمّر الجلسة.- معرّف مشترك بين طلبات متزامنة. يحدث تسابق يفسد الإخراج. يملك كل طلب جلسته الخاصة.
الأداء
قسم بعنوان «الأداء»يبلغ إخراج كل طلب بضعة KB. وتتمثل الفائدة في إبقاء ذاكرة العملية الخلفية محدودة طوال عمرها. السمة هي structural.
ملاحظات أمنية
قسم بعنوان «ملاحظات أمنية»عزل الجلسات خاصية تتعلق بالسرّية أيضًا. لا يصل محتوى طلب أبدًا إلى طلب آخر، لأن المقابض غير مشتركة والجلسة تُدمَّر عند الإخراج.
المطابقة
قسم بعنوان «المطابقة»| العبارة | المواصفة | البند | reference_id |
|---|---|---|---|
| نتيجة كل أداة هي استجابة نقل عادية. | PSR-18 | §p2 | |
| يُعزَل الكود عبر تعيين التحميل التلقائي من الصنف إلى الملف. | PSR-4 | §3 |
السياق التجاري
قسم بعنوان «السياق التجاري»غير منطبق — الأدوات كلها من Core.
توفّر وسائل النقل
قسم بعنوان «توفّر وسائل النقل»| وسيلة النقل | متوفّرة | ملاحظات |
|---|---|---|
| MCP (stdio) | نعم | المعتاد أن تكون عملية stdio واحدة لكل عملية خلفية. |
| REST | نعم | يتطابق حد طلب HTTP مع حد الجلسة. |
| gRPC | نعم | جلسة واحدة لكل تسلسل RPC. |
مستوى خطورة HITL
قسم بعنوان «مستوى خطورة HITL»create_pdf آمنة. set_font وadd_text بمستوى تنبيه. output_pdf بمستوى موافقة مطلوبة، ويُخفَّض إلى مراجعة في وضع base64. في العملية الخلفية، يكون إخراج base64 هو المسار الشائع ولا يضيف بوابة (مستويات خطورة HITL).
غلاف JSON لبوابة التأكيد
قسم بعنوان «غلاف JSON لبوابة التأكيد»إخراج base64 في العملية الخلفية:
{ "allowed": true }