مسار الإخراج

لمحة سريعة

يشغّل مسار الإخراج بيان خطوات ⁨PDF⁩ تصريحيًا بترتيب الاعتمادية، مع إعادة محاولة لكل خطوة وخيار توقّف عند الخطأ. وتتطلّب بعض أنواع الخطوات قدرة ⁨Enterprise Pack⁩ إضافية.

التوفّر والترخيص

تُشحَن هذه الميزة في ⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل بمظروف ترخيص من طبقة ⁨Pro⁩. ولا يحمّل نشرٌ بلا ذلك الاستحقاق أصناف الميزة. قارِن الإصدارات واحصل على ترخيص.

مُنفِّذ المسار نفسه جزء من إصدار ⁨Pro⁩. وتتطلّب ثلاثة أنواع خطوات إضافيةً قدرةً مُسمّاة من ⁨Enterprise Pack⁩: تتطلّب خطوة الحجب قدرة ⁨Privacy Pack⁩، وتتطلّب خطوتا الاستخراج وتراكب ⁨OCR⁩ قدرات ⁨Intelligence Pack⁩. وتفشل الخطوة المُضبَّطة غير المُرخَّصة بإغلاق آمن عند التنفيذ — إذ تُنتِج نتيجة خطوة مُخفِقة ولا يُستدعى مُحلّها أبدًا — بدلًا من إجهاض التشغيل كله.

التثبيت

composer require nextpdf/pro:^3

تعيش الشيفرة تحت فضاء الأسماء NextPDF\Pro\OutputPipeline.

نظرة مفاهيمية

يأخذ PipelineExecutor كائن PipelineManifest، ويرتّب الخطوات بترتيب طوبولوجي، ويوزّع كل خطوة على مُحلّ مسجَّل في StepResolverRegistry. وتُخزَّن مخرجات الخطوات في PipelineContext للخطوات اللاحقة. ويفرض المُنفِّذ مهلة شاملة، ويدعم إعادة المحاولة لكل خطوة، ويمكنه الاستئناف من خطوة مُسمّاة. وهو مُصمَّم للتشغيل داخل عامل مهام لا متزامن، لا مباشرةً من مُعالِج طلب.

تشمل أنواع الخطوات المُدمَجة التوليد، والدمج، والتقسيم، والفحص، والضغط، والتوقيع، والتحويل. أما أنواع خطوات الحجب والاستخراج وتراكب ⁨OCR⁩ فهي مُرخَّصة بالقدرات وتُربَط بقدرات ⁨Enterprise Pack⁩.

لماذا يعمل بهذه الطريقة

المُنفِّذ تنسيقٌ فقط. فهو يرتّب الخطوات، ويفرض بوّابة الترخيص، ويوزّع كلًّا منها على مُحلّ مسجَّل، لكنه لا يُجري أي عمل ⁨PDF⁩ بنفسه. ويتيح هذا الفصل تشغيل بيان واحد إمّا عبر مسار ⁨PHP⁩ التسلسلي هذا أو عبر عامل خارج النطاق يوزّع الخطوات على التوازي، دون تغيير في الشيفرة المُستدعِية. ويستهدف التصميم عامل مهام لا متزامن بدلًا من مُعالِج طلب، لأن مسارًا متعدّد الخطوات كثيرًا ما يتجاوز ميزانية الطلب، وطابور يوسّع الإنتاجية بإضافة عمّال. وتُفحَص المهلة الشاملة بين الخطوات للسبب نفسه: الخطوة كاملةً هي وحدة العمل المُسلَّمة إلى مُحلّ، ويظلّ المنسّق خارج تشغيل ذلك المُحلّ. وتظهر الإخفاقات كقيم StepResult لكل خطوة بدلًا من استثناءات مرمية، فلا تُسقِط خطوةٌ مُخفِقة واحدة نتيجةَ PipelineResult المُجمَّعة التي يبلّغها العامل.

خلفية التصميم: توليد المستندات عالي الحجم.

عقد السلوك

• يعيد execute($manifest, $variables) نتيجةً بحالة شاملة، ونتائج كل خطوة، ومدّة، وأعداد الخطوات المكتملة والمُخفِقة.
• تعمل الخطوات بترتيب طوبولوجي؛ ويُنتِج مُحلّ مفقود لنوع خطوة خطوةً مُخفِقة برسالة واضحة.
• يوقف PipelineOptions::$stopOnError التنفيذ عند أول إخفاق؛ وإلا يستمرّ التنفيذ وتعكس الحالة النهائية أي إخفاقات.
• تُفشِل المهلة الشاملة، حين تُضبَط، المسارَ إذا تُجووِزت قبل بدء الخطوة التالية.
• تُقيَّد إعادة المحاولة لكل خطوة بالحدّ الأقصى المُعَدّ؛ ولا تُعاد محاولة إلا الإخفاقات غير النهائية.
• يتخطّى الاستئناف من خطوة الخطوات السابقة حتى الوصول إلى الخطوة المُسمّاة.
• تفشل أنواع الخطوات المُضبَّطة بالقدرات بإغلاق آمن عند التنفيذ برمز خطأ ترخيص حين تغيب قدرة ⁨Pack⁩ المطلوبة؛ ولا يُستدعى المُحلّ أبدًا.

مثال شيفرة — بداية سريعة

يعكس ما يلي الواجهة البرمجية العامة الموثَّقة. ولا يشحن المستودع مثالًا قابلًا للتشغيل لهذه الوحدة.

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$result = (new PipelineExecutor($stepResolverRegistry))->execute($manifest);

مثال شيفرة — إنتاجي

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$executor = new PipelineExecutor($stepResolverRegistry);

// Invoke from an async job worker, not a request handler.
$result = $executor->execute($manifest, ['customerName' => 'Acme']);

if ($result->status !== \NextPDF\Pro\OutputPipeline\PipelineStatus::Completed) {
    foreach ($result->stepResults as $stepResult) {
        // Inspect per-step error detail.
    }
}

الحالات الحدّية والمزالق

• يُقصَد تشغيل المسار لا متزامنًا عبر نظام مهام. وتشغيله مدمَجًا يحجز المُستدعِي لمدّة المسار كاملةً.
• يُخفِق نوع خطوة بلا مُحلّ مسجَّل تلك الخطوةَ بدلًا من إجهاض المسار كله (ما لم يُضبَط التوقّف عند الخطأ).
• تُفحَص المهلة الشاملة بين الخطوات، لا في أثناء خطوة؛ فقد تتجاوز خطوة طويلة التشغيل الميزانية قبل إطلاق الفحص.

الأداء

المدّة الإجمالية هي مجموع مُدد الخطوات إضافةً إلى عبء إعادة المحاولة. وتُقيِّد المهلة الشاملة أسوأ زمن جدار في الحالة القصوى. ولا يوجد رقم منشور للإنتاجية؛ فكلفة المسار تهيمن عليها الخطوات التي تدرجها. قِس ببيانات تمثيلية.

ملاحظات أمنية

يمرّر المُنفِّذ مستندات المدخلات والمتغيّرات إلى مُحلّي الخطوات؛ عامِلها بوصفها غير موثوقة وتحقّق منها داخل كل مُحلّ. وتفشل الخطوات المُضبَّطة بالقدرات بإغلاق آمن حين تكون غير مُرخَّصة. ولا يسجّل المُنفِّذ أي محتوى مستند.

المطابقة

لا يُجري المُنفِّذ أي عمل مطابقة تنسيق بنفسه؛ فالمطابقة تعتمد على مُحلّي الخطوات الفرديين (التوليد، والدمج، والتقسيم، والتوقيع، والتحويل). ولم تكن مجموعة ⁨RAG⁩ متاحة وقت التأليف، لذا لا تؤكّد هذه الصفحة أي مُعرِّفات بنود خارجية.

ملاحظة عن حدّ ⁨Enterprise⁩

يضيف ⁨Enterprise⁩ قدرات ⁨Pack⁩ التي تفتح أنواع الخطوات المُضبَّطة (الحجب، والاستخراج، وتراكب ⁨OCR⁩) على مستوى السلوك. ومن دون تلك الحزم يبقى المسار يشغّل كل خطوة غير مُضبَّطة. وبواطن ⁨Pack⁩ خارج النطاق هنا.

الرجوع إلى ⁨Core⁩ / البديل

من دون ⁨Pro⁩، نسّق عمليات ⁨PDF⁩ أمريًا بواجهات ⁨NextPDF Core⁩ البرمجية؛ أما البيان التصريحي وترتيب الاعتمادية وإعادة المحاولة فهي إضافات من ⁨Pro⁩..

حدّ النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح الواجهة البرمجية العامة المدعوم فقط. أما مسارات فضاء الأسماء الداخلية، والأصناف المساعِدة، وجداول الآليات، وأسماء ملفّات أدلة التشغيل، وبادئات التذاكر فهي خارج النطاق.

انظر أيضًا

• مسار الإخراج — مرجع معمّق
• المستند
• الدمج
• أداة التسريع