نموذج خط المعالجة

SpecSpec: ISO 32000-2, §7.5ISO 32000-2 §7.5

لمحة سريعة

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

لماذا يهم هذا

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

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

النسخة المختصرة

• نقطة الدخول العامة هي واجهة ⁨Document⁩. إنها أداة بناء انسيابية، تُستخدَم مرة واحدة، وآمنة للعمل ضمن العمال، وتسجّل ما تريده، لا كيف يُحوَّل بالتسلسل.
• تفوّض الواجهة المهام إلى ما يقارب عشرين سمة اهتمام مركّزة (إخراج النص، والرسم، والصفحات، والأمان، والتنقل، وما إلى ذلك) — مسؤولية واحدة لكل منها، لا صنف عملاق واحد.
• يصل المحتوى عبر أحد مسارين: الرسم المباشر (بدائيّات الرسومات) أو محرك ⁨HTML/CSS⁩. وكلاهما يُنتج نموذج المستند الداخلي نفسه.
• يحوّل كاتب ⁨PDF⁩ مخصّص ذلك النموذج بالتسلسل، مختاراً استراتيجية ⁨PDF⁩ ⁨1.4⁩ / ⁨1.7⁩ / 2.0. إنتاج بنية ملف صالحة يحدث هنا ولا مكان غيره.
• الحالة الطويلة العمر (سجلّات الخطوط والصور) ذات نطاق على مستوى العملية ومشتركة؛ أما الحالة الخاصة بكل طلب (المستند) فتُنشأ من جديد ولا يُعاد استخدامها أبداً. الحدّ صريح، وهذا ما يجعل بيئات تشغيل العمال آمنة.

كيف يتناول ⁨NextPDF⁩ ذلك

أوضح طريقة لفهم النموذج هي تتبّع مستند من الاستدعاء إلى البايتات.

1. Document facadeFluent, use-once builder; records intent via concern traits.
2. Content productionDirect drawing or the HTML/CSS engine — both build one document model.
3. Document modelAccumulated pages, content, and resources held as typed state.
4. PDF writerSerialises the model; selects a PDF 1.4 / 1.7 / 2.0 strategy.
5. Conforming PDFHeader, object body, cross-reference table, trailer.

مسار المستند عبر NextPDF: لكل مرحلة مسؤولية واحدة وحدّ مُحدَّد الأنواع، فيمكن التفكير فيها واختبارها بمعزل عن غيرها.

هناك خياران تصميميان يجعلان هذا أكثر من مجرد مخطط.

الواجهة مُركَّبة، لا كتلة واحدة متجانسة. لا ينفّذ Document كل ميزة بنفسه؛ بل يفوّض كل مجال إلى سمة اهتمام مخصّصة — إخراج النص، والرسم، والصفحات، والأمان، والطباعة، والتنقل، والمعاملات، وما إلى ذلك. تنتمي أي طريقة مستند جديدة إلى السمة التي تملك مجالها، لا إلى الواجهة نفسها. يبقى الصنف الذي تستدعيه صغيراً، وتبقى المسؤوليات منفصلة.

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

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

مثال عملي

مهمة الواجهة هي أن تجعل القصد مقروءاً بوصفه قصداً. يبقى مسار المحتوى والكاتب غير مرئيَّين عند موضع الاستدعاء:

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();   // facade
$doc->setTitle('Quarterly Report');    // metadata concern
$doc->addPage();                       // pages concern
$doc->setFont('helvetica', 'B', 16);   // typography concern
$doc->cell(0, 12, 'Summary', newLine: true); // text-output concern
$doc->writeHtml('<p>Generated in-process.</p>'); // HTML content path
$doc->save(__DIR__ . '/report.pdf');   // writer stage

يصل كل استدعاء إلى اهتمام مختلف. يغذّي مساران مختلفان للمحتوى النموذج نفسه. مرحلة واحدة بالضبط — save() — تحوّل النموذج إلى بايتات الملف. لا يحتاج أي شيء عند موضع الاستدعاء إلى معرفة كيفية بناء جدول المرجعية المتقاطعة.

مفهوم خاطئ شائع

إنّ القراءة الخاطئة المتكررة هي أنّ “خط المعالجة” يعني واجهة برمجة دفعٍ متدفّقة تربطها مرحلةً مرحلةً، مثل أنبوب ⁨Unix.⁩ وهذا ليس المقصود. خط المعالجة هنا تفكيك معماري: مراحل ذات مسؤوليات مفردة وحدود مُحدَّدة الأنواع. لا تزال تبرمج مقابل واجهة انسيابية. المراحل هي الطريقة التي يُبنى بها المحرك ويُختبَر، لا ناقل تجمّعه يدوياً.

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

Human-factors note:Human-factors note

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

القيود والحدود

تصف هذه الصفحة شكل خط المعالجة، لا واجهة البرمجة الداخلية لأي مرحلة منفردة. إنّ الجرد الدقيق لسمات الاهتمام، وقواعد اختيار استراتيجية الكاتب، وحقول نموذج المحتوى تحدّدها الشِفرة والمرجع، لا هذا الشرح. إنّ العدد الدقيق للسمات تفصيل تنفيذي يمكن أن يتغيّر دون تغيير النموذج. لا تغطّي هذه الصفحة المراحل الداخلية لمحرك ⁨HTML⁩ (موضوع منفصل)، ولا سلوك التدفّق والذاكرة لدى الكاتب (منفصل أيضاً). الادعاءات البنيوية دقيقة اعتباراً من تاريخ مراجعة هذه الصفحة؛ والمصدر الموثوق هو src/Core/ وsrc/Html/ وsrc/Graphics/ وsrc/Writer/ في مستودع النواة.

نموذج خط المعالجة متطابق عبر الإصدارات؛ تضيف الإصدارات قدرات ضمن المراحل، لا مراحل جديدة:

Pipeline model — edition availability

Edition	Availability
Core	○ينفّذ Core خط المعالجة الكامل واجهة ← محتوى ← كاتب.
Pro	○يضيف Pro قدرات ضمن المراحل القائمة، لا مراحل جديدة.
Enterprise	○يضيف Enterprise قدرات ضمن المراحل القائمة، لا مراحل جديدة.

مستندات ذات صلة

• الذاكرة والتدفّق — كيف تُبقي مرحلة الكاتب الذاكرة محدودة.
• خط معالجة ⁨HTML⁩ — المراحل الداخلية لمسار محتوى ⁨HTML.⁩
• أنواع صارمة في كل مكان — الحدود المُحدَّدة الأنواع التي تجعل كل مرحلة قابلة للاختبار باستقلالية.

مسرد المصطلحات

• الواجهة — نقطة الدخول العامة Document: أداة بناء انسيابية تُستخدَم مرة واحدة، تسجّل القصد وتفوّض إلى سمات الاهتمام.
• سمة الاهتمام — سمة ⁨PHP⁩ مركّزة تركّبها الواجهة، تملك كل منها مجال ميزة واحداً (إخراج النص، والرسم، والصفحات، والأمان، وما إلى ذلك).
• مسار المحتوى — إحدى الطريقتين اللتين يدخل بهما المحتوى إلى النموذج: الرسم المباشر أو محرك ⁨HTML/CSS.⁩
• نموذج المستند — التراكم الداخلي المُحدَّد الأنواع للصفحات والمحتوى والموارد لدى المحرك قبل التحويل بالتسلسل.
• مرحلة الكاتب — المكوّن الذي يحوّل النموذج بالتسلسل إلى ملف ⁨PDF⁩ صالح، مختاراً استراتيجية ⁨PDF⁩ ⁨1.4⁩ / ⁨1.7⁩ / 2.0.
• آمن للعمال — مصمَّم بحيث تُشارَك الحالة على مستوى عمر العملية بأمان بينما تُنشأ الحالة الخاصة بكل طلب من جديد ولا يُعاد استخدامها أبداً.