خط الإخراج — مرجع متعمّق

لمحة سريعة

ينفّذ NextPDF\Enterprise\OutputPipeline عددًا كبيرًا من ملفات بيان خط ⁨Pro⁩ كدفعة واحدة. يُغلّف BatchPipelineOrchestrator منفّذ ⁨Pro⁩ PipelineExecutor بتنسيق دفعي: حارس موارد محدود على حجم الدفعة، ومهلة زمنية عامة اختيارية للدفعة، وحقن متغيّرات لكل ملف بيان، ومحاسبة إجمالية. يُعيد فحص امتثال اختياري في نهاية الدفعة التحقّقَ من كل مخرَج مكتمل عبر بوابة امتثال ⁨Enterprise⁩ ويفشل مغلقًا. وتُعيد كل عملية تشغيل BatchPipelineResult يحمل نتائج كل ملف بيان، وأعداد المكتمل والفاشل، والتوقيت، وتقرير الامتثال الاختياري.

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

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

الفئة	سطح خط الإخراج
⁨Core⁩	لا يوجد سطح لخط الإخراج.
⁨Pro⁩	خط أحادي البيان (الإمكانية pro.output.pipeline).
⁨Enterprise⁩	تنسيق دفعي، وحدّ لحجم الدفعة، ومهلة للدفعة، وتسليم امتثال.

لا يحمل سطح الدفعة في ⁨Enterprise⁩ رمز إمكانية منفصلًا لكل ميزة؛ بل يحرسه حدُّ الحزمة. وتُعدّ إمكانية البيان الأحادي في ⁨Pro⁩ pro.output.pipeline متطلَّبًا مسبقًا، لا البوابة. ولا يفتح ترخيص ⁨Pro⁩ وحده سوى خط البيان الأحادي الأساسي، لا سطح الدفعة هذا.

composer require nextpdf/enterprise:^3

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

الرمز	المعامِلات	السلوك الافتراضي	المُعاد	يرمي أو يفشل بـ	ملاحظات
BatchPipelineOrchestrator::__construct()	PipelineExecutor $executor, BatchPipelineConfig $config, ?ComplianceGateway $complianceGateway, ComplianceProfile $complianceProfile	الإعداد الافتراضي؛ بلا بوابة؛ ملف التعريف ComplianceProfile::PdfA4	—	لا شيء	احقن بوابة عند تفعيل فحص الامتثال؛ فبدونها يُبلَّغ عن فشل كل ملف بيان مفحوص.
BatchPipelineOrchestrator::executeBatch()	list<PipelineManifest> $manifests, array<string, array<string, mixed>> $variablesMap = []	يُنفِّذ ملفات البيان بترتيب التقديم؛ وتُحلّ المتغيّرات حسب معرّف ملف البيان	BatchPipelineResult	OverflowException عندما تتجاوز الدفعة 10,000 ملف بيان؛ واستثناءات البوابة عند تفعيل فحص الامتثال (انظر الحالات الحدّية)	لا تُفلت Throwable الخاصة بالمُحلِّل أبدًا؛ إذ يخفّضها منفّذ ⁨Pro⁩ إلى نتائج خطوات فاشلة.
BatchPipelineConfig::__construct()	int $maxConcurrency = 4, int $timeoutMs = 0, bool $complianceCheckOnComplete = false	تزامن 4؛ بلا مهلة؛ بلا فحص امتثال	—	لا شيء	كائن قيمة للقراءة فقط. timeoutMs = 0 يعطّل مهلة الدفعة.
BatchPipelineResult::__construct()	list<PipelineResult> $results, int $totalManifests, int $completedCount, int $failedCount, float $durationMs, ?array $complianceReport = null	تجميع فوق قيم PipelineResult لكل ملف بيان	—	لا شيء	للقراءة فقط. يبقى complianceReport بقيمة null ما لم يُشغَّل الفحص.
BatchPipelineResult::allSucceeded()	—	يختبر failedCount === 0	bool	لا شيء	يُعيد ⁨true⁩ على دفعة مبتورة بالمهلة بلا أي فشل؛ انظر الحالات الحدّية.
BatchPipelineResult::successRate()	—	completedCount / totalManifests	float	لا شيء	يُعيد 1.0 لدفعة فارغة.
BatchPipelineResult::hasComplianceReport()	—	يختبر complianceReport !== null	bool	لا شيء	—

public function __construct(
    private readonly PipelineExecutor $executor,
    private readonly BatchPipelineConfig $config = new BatchPipelineConfig(),
    private readonly ?ComplianceGateway $complianceGateway = null,
    private readonly ComplianceProfile $complianceProfile = ComplianceProfile::PdfA4,
) {}

public function executeBatch(
    array $manifests,
    array $variablesMap = [],
): BatchPipelineResult

public function __construct(
    public int $maxConcurrency = 4,
    public int $timeoutMs = 0,
    public bool $complianceCheckOnComplete = false,
) {}

عقد السلوك

يتحقّق executeBatch() أولًا من حجم الدفعة مقابل سقف قدره 10,000 ملف بيان. وتُثير أي دفعة تتجاوز السقف OverflowException قبل تنفيذ أي ملف بيان؛ ولا يتدهور شيء بصمت.

ثم تُنفَّذ ملفات البيان بترتيب التقديم عبر منفّذ ⁨Pro⁩ PipelineExecutor. ويتلقّى كل ملف بيان مدخل المتغيّرات المفهرَس بمعرّفه في $variablesMap؛ ويتلقّى ملف البيان الذي بلا مدخل خريطةَ متغيّرات فارغة. ويُحتسب ملف البيان مكتملًا عندما تكون حالة PipelineResult الخاصة به Completed؛ وتُحتسب أي حالة نهائية أخرى فاشلة. ولا تُفلت استثناءات المُحلِّل: إذ يحوّل منفّذ ⁨Pro⁩ كل Throwable من المُحلِّل إلى نتيجة خطوة فاشلة، لذا يُجمّع executeBatch() النتائجَ دائمًا بدلًا من الإجهاض في منتصف الدفعة عند خطأ خطوة.

عندما يكون timeoutMs أكبر من صفر، يُفحَص الوقت المنقضي قبل بدء كل ملف بيان. وبمجرّد استنفاد الميزانية، تُتخطّى ملفات البيان المتبقّية: فلا تُنتج PipelineResult، ولا تُحتسب مكتملة ولا فاشلة. ويُبلّغ totalManifests دائمًا عن العدد المقدَّم.

عند تفعيل complianceCheckOnComplete، يتحقّق المنسّق من ملف ⁨PDF⁩ النهائي لكل ملف بيان مكتمل مقابل ComplianceProfile المُهيّأ عبر ComplianceGateway المحقون. ويفشل الفحص مغلقًا:

• بلا بوابة محقونة: يُبلَّغ عن فشل كل ملف بيان مفحوص، لأن الامتثال لم يُتحقَّق منه قط.
• تعذُّر استخلاص مخرَج ⁨PDF⁩ من مخرجات خطوات ملف البيان: فاشل.
• لا تُعيد البوابة أي نتيجة (عدم توفّر الرديف في الوضع الاختياري): فاشل. فغياب النتيجة الإيجابية ليس نجاحًا.
• تُبلّغ البوابة عن أي عدم مطابقة: فاشل.

يُستخلَص ملف ⁨PDF⁩ النهائي بمسح مخرجات خطوات ملف البيان المكتمل، من الخطوة الأخيرة أولًا، بحثًا عن قيمة نصية مباشرة تبدأ بترويسة %PDF. ولا تُضمّن مخرجات الخطوات سلاسلَ بايتات ⁨PDF⁩ داخل مصفوفات فرعية أبدًا؛ إذ لا تُفحَص سوى قيم المخرجات المباشرة. وتُتخطّى ملفات البيان التي لم تكتمل، لا تُفحَص.

تقرير الامتثال مصفوفة بمفاتيح profile وchecked وpassed وfailed وfailures؛ ويحمل كل مدخل فشل manifestId وreason. ويُرفَق التقرير بـ BatchPipelineResult::$complianceReport ويمكن الوصول إليه عبر hasComplianceReport().

تسليم الامتثال أداة مساعدة لإعادة التحقّق، لا ضابط تفويض. فهو يُبلّغ عن النتائج فقط.

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

• أكثر من 10,000 ملف بيان: OverflowException قبل بدء أي تنفيذ.
• timeoutMs = 0 يعني بلا مهلة للدفعة. اضبط قيمة محدودة في الإنتاج.
• بتر بالمهلة: لا تظهر ملفات البيان المتخطّاة في أي عدّ، لذا قد يكون completedCount + failedCount أقل من totalManifests. ويختبر allSucceeded() فقط failedCount === 0 وقد يُعيد ⁨true⁩ لدفعة مبتورة. قارن count($result->results) بـ totalManifests لاكتشاف البتر.
• successRate() يُعيد 1.0 لدفعة فارغة (صفر ملفات بيان مقدَّمة).
• لا تُزال تكرارات معرّفات ملفات البيان على مستوى الدفعة. إذ يُنفَّذ ملفَا بيان يتشاركان معرّفًا كلاهما ويحلّان مدخل المتغيّرات نفسه.
• تُثير الأخطاء البنيوية في ملف البيان (قائمة خطوات فارغة، معرّفات خطوات مكرّرة، اعتمادية غير معروفة، دورة اعتماديات، عدم تطابق نوع المخرَج، خطوة استئناف مفقودة) InvalidArgumentException عند بناء ملف البيان، قبل استدعاء executeBatch() مطلقًا.
• مع تفعيل فحص الامتثال، قد يرمي ComplianceGateway::validate() استثناء ComplianceSidecarUnavailableException (الرديف غير متوفّر في الوضع المطلوب) أو InvalidArgumentException (لا مُحقِّق مسجَّل لأداة ملف التعريف). ويُفلت أيٌّ من الاستثناءين من executeBatch() بعد التنفيذ لكن قبل بناء النتيجة، لذا تُفقَد نتائج كل ملف بيان بالنسبة للمستدعي. وفي الوضع الاختياري تُعيد البوابة null بدلًا من ذلك، ويُسجَّل ملف البيان بوصفه فشل امتثال.
• تفشل خطوة تسليم الامتثال داخل الخط عندما لا يحتوي أي مخرَج خطوة سابقة على بايتات ⁨PDF⁩ قابلة للتمييز؛ ولا تنجح بصمت أبدًا.
• لا تُجري هذه الوحدة أي عمليات تشفير؛ ووضع ⁨FIPS⁩ غير قابل للتطبيق.

المطابقة

لا تُدَّعى أي مطابقة للمعايير لهذه الوحدة؛ فهي طبقة تنسيق. ويحيل فحص الامتثال الاختياري إلى بوابة امتثال ⁨Enterprise⁩ ومُحقِّقيها الخارجيين، الذين يحملون مراجعهم الخاصة. وملف التعريف الافتراضي هو ComplianceProfile::PdfA4؛ وتغطّي ملفات تعريف البوابة الأخرى أهدافًا إضافية من ⁨PDF/A⁩ و⁨PDF/UA⁩ و⁨PAdES⁩.

يذكر تقرير الامتثال نتائج المُحقِّق مقابل ملف التعريف المختار. وهو لا يعتمد مستندًا، ولا يضمن الكفاية التنظيمية، ولا يشكّل استشارة قانونية. والحكم على ما إذا كان المخرَج يفي بالتزاماتك مسؤوليتك أنت.

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

• في عمليات النشر الإنتاجية، يتولّى رديفُ تنفيذ منفصل توزيعَ العمّال المتوازي والضغطَ العكسي. ويوفّر منسّق ⁨PHP⁩ منطق تنسيق الدفعة وتسليم الامتثال، ويستدعيه عاملُ المهام، لا معالِجات الطلبات مباشرةً.
• ينفّذ مسار ⁨PHP⁩ الاحتياطي ملفات البيان تِباعًا. ويحدّ maxConcurrency استدعاءات العمّال المتزامنة في النشر المُدار بالرديف؛ وتحجيمه نسبةً إلى مجمّع عمّال ⁨PHP⁩ مسؤولية المُشغِّل.
• مُحلِّل خطوة تسليم الامتثال داخل الخط نوعٌ داخلي مسجَّل لخطوات من نوع ⁨inspect⁩. فعِّل التحقّق في نهاية الدفعة عبر BatchPipelineConfig بدلًا من بناء خطوات الخط له مباشرةً.
• أنشئ نسخ PipelineManifest مبكرًا. فتحقّقها البنيوي يجري في الباني، لذا تفشل الرسوم البيانية غير الصالحة سريعًا ولا تستهلك ميزانية الدفعة أبدًا.

حدود النشر

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

انظر أيضًا

• خط الإخراج (إمكانية ⁨Enterprise⁩)
• خط الإخراج — مرجع ⁨Pro⁩ المتعمّق
• الامتثال — المرجع المتعمّق