خط أنابيب الإخراج — مرجع متعمّق

نظرة سريعة

هذه الصفحة هي المرجع المتعمّق للسطح العام للفئة NextPDF\Pro\OutputPipeline. تغطّي بناء البيان والتحقق منه، وترتيب التنفيذ الطوبولوجي، ودلالات إعادة المحاولة والمهلة الزمنية، وسلوك الاستئناف، وبوابة قدرات الحزمة المغلقة عند الفشل. وتوضّح المعاملات والقيم الافتراضية وأنماط الفشل لكل رمز عام. اطّلع أولاً على صفحة قدرة خط أنابيب الإخراج للحصول على إرشادات سير العمل.

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

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

لا يحمل المُنفِّذ وسبعة من أنواع الخطوات العشرة أي راية خاصة بكل ميزة. وتتطلّب ثلاثة أنواع من الخطوات إضافةً إلى ذلك قدرة حزمة (⁨Pack⁩):

نوع الخطوة	قيمة البيان	القدرة المطلوبة	الحزمة (⁨Pack⁩)
⁨Redact⁩	redact	pack.privacy.redact	⁨Privacy Pack⁩
⁨Extract⁩	extract	pack.intelligence.extract	⁨Intelligence Pack⁩
⁨OCR overlay⁩	ocr_overlay	pack.intelligence.searchable_pdf	⁨Intelligence Pack⁩

تُطبَّق البوابة في وقت التنفيذ، مغلقةً عند الفشل، قبل أن تصل الخطوة إلى مُحلِّلها. تُنتج أي خطوة مبوَّبة غير مرخَّصة نتيجة خطوة بحالة ⁨Failed⁩ تحمل الرمز SPEC-LIC-001 والقدرة المطلوبة؛ ولا يُستدعى المُحلِّل مطلقاً. وأي خط أنابيب لا يملك مُحلِّل قدرات مُحقَناً يرفض كل خطوة مبوَّبة.

سطح واجهة برمجة التطبيقات العامة

composer require nextpdf/pro:^3

تُثبِّت الحزمة الوصفية nextpdf/premium شفرة nextpdf/pro؛ وتقع هذه الوحدة ضمن مساحة الأسماء NextPDF\Pro\OutputPipeline.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يطرح استثناءً أو يفشل بـ	ملاحظات
PipelineExecutor::__construct	StepResolverRegistry $registry، ?CapabilityResolverInterface $capabilityResolver = null	يربط سجل المُحلِّلات المُدمج ومصدر الاستحقاق الاختياري	PipelineExecutor	لا شيء معلن	مُحلِّل قدرات فارغ (null) يرفض كل خطوة مبوَّبة بحزمة
PipelineExecutor::execute	PipelineManifest $manifest، array $variables = []	يشغّل الخطوات بالترتيب الطوبولوجي ويجمّع النتائج	PipelineResult	لا شيء معلن؛ تُلتقط إخفاقات المُحلِّل كنتائج خطوة بحالة ⁨Failed⁩	مُصمَّم للتشغيل داخل عامل مهام غير متزامن
PipelineManifest::__construct	string $id، array $steps، PipelineOptions $options = new PipelineOptions()، ?string $resumeFromStepId = null	يتحقّق من رسم الخطوات البياني عند الإنشاء	PipelineManifest	InvalidArgumentException عند قائمة خطوات فارغة، أو مُعرّفات خطوات مكرّرة، أو تبعيّات غير معروفة، أو دورات، أو عدم تطابق نوع الإخراج، أو خطوة استئناف مفقودة؛ وOverflowException فوق 10 000 خطوة	يكتمل كل التحقّق قبل أي تنفيذ
PipelineManifest::topologicalOrder	لا يوجد	يرتّب الخطوات بحيث تسبق التبعيّات مُعتمِديها	list<PipelineStep>	لا شيء معلن	حتمي لبيان مُعطى
PipelineManifest::getStep	string $stepId	بحث خطّي عبر مُعرّف الخطوة	?PipelineStep	لا شيء معلن	null لمُعرّف غير معروف
PipelineManifest::rootSteps	لا يوجد	يُعيد الخطوات التي لا تبعيّات لها	list<PipelineStep>	لا شيء معلن	الخطوات الجذرية تُشغَّل أولاً
PipelineManifestBuilder::create	string $manifestId	يبدأ بانياً جديداً	self	لا شيء معلن	المُنشئ خاص؛ هذا هو المدخل الوحيد
PipelineManifestBuilder::addStep	string $id، PipelineStepType $type، array $parameters = []، array $dependsOn = []، ?StepOutputType $outputType = null	يُلحق خطوة؛ ويُستنتج نوع الإخراج الفارغ (null) من نوع الخطوة	self	لا شيء معلن	يُؤجَّل التحقّق إلى build()
PipelineManifestBuilder::stopOnError	bool $stop = true	يضبط الإيقاف عند أول فشل	self	لا شيء معلن	القيمة الافتراضية true
PipelineManifestBuilder::maxRetries	int $retries	يضبط سقف إعادة المحاولة لكل خطوة	self	لا شيء معلن	القيمة الافتراضية 0 (بلا إعادة محاولة)
PipelineManifestBuilder::timeout	int $timeoutMs	يضبط المهلة الزمنية الكلية لخط الأنابيب	self	لا شيء معلن	0 يُعطِّل المهلة الزمنية
PipelineManifestBuilder::resumeFrom	string $stepId	يضبط نقطة الاستئناف	self	لا شيء معلن	يجب أن توجد الخطوة عند وقت build()
PipelineManifestBuilder::build	لا يوجد	يُنشئ البيان المُتحقَّق منه	PipelineManifest	كما في PipelineManifest::__construct	—
PipelineOptions::__construct	bool $stopOnError = true، int $maxRetries = 0، int $timeoutMs = 0	خيارات تنفيذ غير قابلة للتغيير	PipelineOptions	لا شيء معلن	كائن قيمة للقراءة فقط
PipelineStep::__construct	string $id، PipelineStepType $type، array $parameters = []، array $dependsOn = []، StepOutputType $outputType = StepOutputType::Pdf	تعريف خطوة غير قابل للتغيير	PipelineStep	لا شيء معلن	يجعل الإنشاء المباشر نوع الإخراج ⁨PDF⁩ افتراضياً لكل نوع
PipelineStep::isRoot	لا يوجد	صحيح عندما لا تكون للخطوة تبعيّات	bool	لا شيء معلن	—
PipelineStepType (تعداد)	—	عشر حالات مدعومة بسلاسل نصية: generate، merge، split، inspect، compress، sign، convert، إضافةً إلى الحالات المبوَّبة redact، extract، ocr_overlay	—	—	حالة واحدة لكل عملية مُدمجة
PipelineStepType::requiresPack	لا يوجد	صحيح لـ ⁨Redact⁩ و⁨Extract⁩ و⁨OcrOverlay⁩	bool	لا شيء معلن	تُعيد كل الحالات الأخرى false
PipelineStepType::requiredCapability	لا يوجد	يربط الحالات المبوَّبة برموز قدراتها	?string	لا شيء معلن	null للحالات غير المبوَّبة
PipelineStatus (تعداد)	—	خمس حالات: pending، running، completed، failed، cancelled	—	—	مشتركة بين نتائج خط الأنابيب والخطوة
PipelineStatus::isTerminal	لا يوجد	صحيح لـ ⁨Completed⁩ و⁨Failed⁩ و⁨Cancelled⁩	bool	لا شيء معلن	⁨Pending⁩ و⁨Running⁩ غير نهائيتين
StepOutputType (تعداد)	—	ثلاث حالات: pdf، json، metadata	—	—	يقود التحقّق من الحواف في وقت البناء
StepOutputType::forStepType	PipelineStepType $stepType	نوع الإخراج الافتراضي لنوع الخطوة	self	لا شيء معلن	⁨Inspect⁩ و⁨Extract⁩ يُقابلان ⁨JSON⁩؛ وكل الأنواع الأخرى تُقابل ⁨PDF⁩
StepOutputType::isCompatibleWith	self $expectedInput	صحيح لتطابق النوع نفسه أو لإخراج ⁨PDF⁩	bool	لا شيء معلن	مساعد؛ ⁨PDF⁩ هو المدخل الشامل
PipelineContext::__construct	string $manifestId، array $variables = []، ?string $resumeFromStepId = null	سياق في الذاكرة لكل تشغيل	PipelineContext	لا شيء معلن	بلا ⁨TTL⁩ أو انتهاء صلاحية أو استمرار أو مخزن داعم
PipelineContext::setStepResult / ::getStepResult	string $stepId (+ StepResult عند التعيين)	يسجّل نتيجة خطوة أو يقرؤها	void / ?StepResult	لا شيء معلن	null لخطوة لم تُنفَّذ بعد
PipelineContext::setStepOutput / ::getStepOutput	string $stepId (+ mixed عند التعيين)	يخزّن إخراجاً وسيطاً أو يقرؤه	void / mixed	لا شيء معلن	null لإخراج مفقود
PipelineContext::hasStepResult	string $stepId	ما إذا كانت خطوة قد نُفِّذت بالفعل	bool	لا شيء معلن	يدعم فحوص الاستئناف
PipelineContext::allStepResults	لا يوجد	كل النتائج المُسجَّلة حتى الآن	array<string, StepResult>	لا شيء معلن	مُفهرَسة بمُعرّف الخطوة
PipelineContext::isResume	لا يوجد	ما إذا كان التشغيل يستأنف من خطوة	bool	لا شيء معلن	—
PipelineResult::isSuccess	لا يوجد	صحيح فقط للحالة الكلية ⁨Completed⁩	bool	لا شيء معلن	النتيجة يُنتجها المُنفِّذ
PipelineResult::getStepResult	string $stepId	يجد نتيجة خطوة واحدة عبر المُعرّف	?StepResult	لا شيء معلن	null للخطوات المتخطّاة أو غير المعروفة
PipelineResult::failedSteps	لا يوجد	يُرشِّح نتائج الخطوات الفاشلة	list<StepResult>	لا شيء معلن	قائمة فارغة عند النجاح التام
StepResult::isSuccess	لا يوجد	صحيح فقط لحالة الخطوة ⁨Completed⁩	bool	لا شيء معلن	يحمل stepId وtype وstatus وdurationMs وerror وoutput
CapabilityResolverInterface::hasCapability	string $capability	اختبار استحقاق إيجابي لرمز قدرة واحد	bool	يجب ألا يطرح استثناءً	الرفض بالإغفال: false للرموز غير المعروفة أو المنتهية أو غير المُقابَلة

توقيعات نقاط الدخول

final class PipelineExecutor
{
    public function __construct(
        private readonly StepResolverRegistry $registry,
        private readonly ?CapabilityResolverInterface $capabilityResolver = null,
    )

    public function execute(PipelineManifest $manifest, array $variables = []): PipelineResult
}

final class PipelineManifestBuilder
{
    public static function create(string $manifestId): self

    public function addStep(
        string $id,
        PipelineStepType $type,
        array $parameters = [],
        array $dependsOn = [],
        ?StepOutputType $outputType = null,
    ): self

    public function stopOnError(bool $stop = true): self

    public function maxRetries(int $retries): self

    public function timeout(int $timeoutMs): self

    public function resumeFrom(string $stepId): self

    public function build(): PipelineManifest
}

interface CapabilityResolverInterface
{
    public function hasCapability(string $capability): bool;
}

عقد السلوك

التحقّق من البيان

يجري التحقّق في مُنشئ PipelineManifest، قبل أي تنفيذ. وبالترتيب: يجب ألّا تكون قائمة الخطوات فارغة؛ ويُحدَّد سقف عدد الخطوات عند 10 000، محوِّلاً سلاسل التبعيّات العميقة عدائياً إلى OverflowException قابل للالتقاط بدلاً من استنفاد المكدس الأصلي؛ ويجب أن تكون مُعرّفات الخطوات فريدة؛ ويجب أن تُحَلّ كل إشارة dependsOn؛ ويجب أن يكون رسم التبعيّات البياني خالياً من الدورات؛ ويجب أن تكون أنواع الإخراج متوافقة؛ ويجب أن توجد خطوة الاستئناف المُعلنة. وكل مخالفة تطرح InvalidArgumentException برسالة محدّدة.

ينطبق فحص نوع الإخراج على الخطوات التي يُقابل نوعها إخراج ⁨PDF⁩: إذ يجب أن تُنتج كل تبعيّة لمثل هذه الخطوة إخراج ⁨PDF⁩ بذاتها. أما حواف التبعيّة الداخلة إلى أنواع الخطوات المُنتجة لـ ⁨JSON⁩ (inspect، extract) فلا تخضع لفحص النوع في هذا الإصدار.

ترتيب التنفيذ والاستئناف والمهلة الزمنية

يبني execute($manifest, $variables) سياق PipelineContext جديداً، ويحسب الترتيب الطوبولوجي، ويُشغّل الخطوات تِباعاً بذلك الترتيب. ومع ضبط نقطة استئناف، تُتخطّى الخطوات السابقة حتى الوصول إلى الخطوة المُسمّاة. ولا يُعاد تنفيذ الأسلاف المتخطّاة ولا تُستعاد مخرجاتها: فالسياق لكل تشغيل وفي الذاكرة، ولذا فإن خطوة مُستأنَفة تقرأ إخراج سلف متخطّى ترصد null.

وتُقيَّم المهلة الزمنية الكلية، متى كانت موجبة، بين الخطوات، قبل بدء كل خطوة. وعند انقضائها تصبح حالة خط الأنابيب ⁨Failed⁩ ولا تبدأ الخطوات المتبقّية. ولا تُقاطَع أي خطوة قيد التشغيل في منتصف تنفيذها، ولذا قد تتجاوز خطوة طويلة واحدة الميزانية الزمنية.

إعادة المحاولة والتقاط الفشل

تتلقّى كل خطوة maxRetries + 1 محاولة كحدّ أقصى. وتُعيد المحاولة الناجحة على الفور. وأي محاولة فاشلة — نتيجة ⁨Failed⁩ من المُحلِّل، أو استثناء Throwable مطروح — يُعاد تنفيذها ما دامت هناك محاولات؛ وتُعاد نتيجة المحاولة الأخيرة. ويُخفَّض أي Throwable يُطرح داخل مُحلِّل إلى نتيجة خطوة بحالة ⁨Failed⁩ تحمل رسالة الاستثناء، أو Unknown error عندما تكون الرسالة فارغة. ولذا يُعيد execute() دائماً PipelineResult؛ ولا ينشر إخفاق مُحلِّل مطلقاً.

وأي نوع خطوة بلا مُحلِّل مُسجَّل يُنتج نتيجة خطوة بحالة ⁨Failed⁩ برسالة صريحة؛ ولا يُجهَض التشغيل. ومع كون stopOnError صحيحاً (القيمة الافتراضية)، يتوقّف التنفيذ عند أول خطوة فاشلة وتصبح حالة خط الأنابيب ⁨Failed⁩. ومع كونه خاطئاً، يستمرّ التنفيذ وتكون الحالة النهائية ⁨Failed⁩ إن فشلت أي خطوة، وإلا ⁨Completed⁩.

بوابة قدرة الحزمة

قبل أي إرسال إلى مُحلِّل، تُفحَص كل خطوة مبوَّبة بحزمة (⁨Redact⁩ و⁨Extract⁩ و⁨OcrOverlay⁩) في مقابل CapabilityResolverInterface المُحقَن. والبوابة مغلقة عند الفشل: مُحلِّل مفقود، أو إجابة false، أو رمز قدرة غير مُقابَل، كلها ترفض الخطوة. ويُنتج الرفض نتيجة خطوة بحالة ⁨Failed⁩ يحمل خطؤها الرمز SPEC-LIC-001 ونوع الخطوة والقدرة المطلوبة. والرفض المبوَّب لا يستهلك أي محاولات إعادة ويُبلّغ عن مدة قدرها 0.0. ويجب أن تُعيد تطبيقات المُحلِّل true فقط لاستحقاق مملوك إيجابياً وألّا تطرح استثناءً.

تجميع النتائج

يُبلّغ PipelineResult عن مُعرّف البيان، والحالة الكلية، ونتائج كل خطوة بترتيب التنفيذ، والمدة الكلية بالمِلّي ثانية، وأعداد الخطوات الكلية والمكتملة والفاشلة. ويحصي stepsTotal كل خطوة في البيان، بما فيها الخطوات المتخطّاة بالاستئناف أو غير المبلوغة بعد توقّف؛ أما stepsCompleted وstepsFailed فيحصيان الخطوات المُنفَّذة فقط.

الحالات الحدّية وأنماط الفشل

• المُنفِّذ مُصمَّم للتنفيذ غير المتزامن داخل عامل مهام. والاستخدام المضمَّن يحجب المُستدعي طوال مدة خط الأنابيب كاملةً.
• المهلة الزمنية الكلية فحص بين الخطوات. وقد تتجاوز خطوة طويلة واحدة الميزانية الزمنية؛ ولا تُقاطَع أي خطوة في منتصف تنفيذها.
• الاستئناف يتخطّى الخطوات ضمن التنفيذ نفسه فقط. ولا يستعيد مخرجات من أي مخزن؛ والاستئناف عبر التشغيلات بمخرجات مُخزَّنة مؤقتاً غير مُنفَّذ.
• إنشاء PipelineStep مباشرةً يجعل نوع الإخراج ⁨PDF⁩ افتراضياً لكل نوع خطوة. استخدم الباني، أو مرِّر نوع الإخراج صراحةً، كي تُعلن خطوتا inspect وextract عن إخراج ⁨JSON⁩ ويظلّ التحقّق من الحواف ذا معنى.
• استثناء المُحلِّل برسالة فارغة يُطبَّع إلى Unknown error في نتيجة الخطوة.
• نتائج الخطوات الفاشلة التي تُنتجها البوابة أو مُحلِّل مفقود تُبلّغ عن مدة قدرها 0.0.
• يُعيد PipelineResult::getStepResult() القيمة null لكل من المُعرّفات غير المعروفة والخطوات المتخطّاة بالاستئناف أو بتوقّف؛ ميّز بينها عبر stepsTotal مقابل طول قائمة النتائج.
• لا تُجري هذه الوحدة أي عمليات تشفيرية ولا تُعرّف أي سلوك خاص بـ ⁨FIPS⁩. ووضعية ⁨FIPS⁩ لخطوة sign تحكمها وحدة التوقيع، لا خط الأنابيب.

المطابقة

لا يُجري خط الأنابيب أي عمل مطابقة تنسيق خاص به. ومطابقة كل قطعة أثرية مُنتَجة تملكها الوحدة الكامنة خلف الخطوة المُنفِّذة — التوقيع، والتحسين، والتحويل، وهكذا — وهي موثَّقة في صفحات مرجع تلك الوحدات. ولا تدّعي هذه الصفحة أي مُعرّفات بنود خارجية؛ فكل عبارة مؤسَّسة على شفرة المنتج المصدرية. ⁨NextPDF⁩ لا تقدّم أي ادّعاء اعتماد.

ملاحظات التطوير

• تحمل شفرة الوحدة المصدرية @since 2.2.0؛ ويوثّق هذا المرجع السطح كما شُحن في nextpdf/pro 3.1.0.
• كل الفئات final؛ وأنواع البيان والخيارات والخطوة والنتيجة كائنات قيمة للقراءة فقط. أنشئ نسخاً جديدة بدلاً من التغيير.
• StepResolverInterface وStepResolverRegistry من نوع @internal. ومُحلِّلات الخطوات مُدمجة فقط؛ ومعالِجات الخطوات المخصّصة المُعرَّفة من المستخدم غير مدعومة في هذا الإصدار.
• CapabilityResolverInterface هي وصلة الاستحقاق العامة. ويجب أن تكون التطبيقات قائمة على الرفض بالإغفال وألّا تسمح افتراضياً.
• مُنفِّذ ⁨PHP⁩ هذا هو مسار التحقّق من البيان والتنفيذ التسلسلي؛ وقد ترسل عمليات النشر الإنتاجية عبر الـ ⁨sidecar⁩ للتنسيق المتوازي. وبوابة القدرة على مسار ⁨PHP⁩ مغلقة عند الفشل باستقلالية في الحالتين.
• تفاصيل الآلية الداخلية تبقى في التوثيق الداخلي لمستودع المصدر وهي خارج نطاق هذا الدليل.

حدود النشر

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

اطّلع أيضاً

• خط أنابيب الإخراج — صفحة القدرة لإرشادات سير العمل.
• خط أنابيب الإخراج — مرجع ⁨NextPDF Enterprise⁩ المتعمّق — التنسيق الدفعي عبر البيانات.
• ⁨Document⁩ — مرجع متعمّق
• ⁨Accelerator⁩ — مرجع متعمّق