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

Spec: ISO 32000-2, §7.5 Evidence: Code-backed

لمحة سريعة

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

لماذا يهم هذا

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

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

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

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

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

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

Document facade Fluent, use-once builder; records intent via concern traits.
Content production Direct drawing or the HTML/CSS engine — both build one document model.
Document model Accumulated pages, content, and resources held as typed state.
PDF writer Serialises the model; selects a PDF 1.4 / 1.7 / 2.0 strategy.
Conforming PDF Header, object body, cross-reference table, trailer.

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

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

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

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

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

ماذا تقول الأدلة

هذه الصفحة Evidence: Code-backed . تُطابِق المراحل بنية حقيقية في مستودع النواة:

تتمثل الواجهة وتفويضها في src/Core/Document.php إضافةً إلى سمات الاهتمام في src/Core/Concerns/ (إخراج النص، والإخراج، والرسم، والصفحات، والأمان، والطباعة، والتنقل، والمعاملات، وغيرها — لكل منها مسؤولية واحدة).
مسارا المحتوى هما محرك ⁨HTML/CSS⁩ (src/Html/) والرسم المباشر (src/Graphics/)، وكلاهما يغذّي النموذج الداخلي.
يجري التحويل بالتسلسل واستراتيجية إصدار ⁨PDF⁩ في src/Writer/ (PdfWriter.php، مع أصناف استراتيجية صريحة لـ ⁨PDF⁩ 1.4 / 1.7 / 2.0).
إنّ الحدّ بين عمر العملية والطلب الواحد هو التصميم الآمن للعمال المسجَّل في نظرة عامة على البنية المعمارية والمُجسَّد في مثال مصنع العمال المشحون، حيث يشارك FontRegistry وImageRegistry عبر الطلبات بينما يُنشئ كل Document من جديد.

الوجهة ثابتة بحكم الصيغة. يجب أن يكون مخرَج الكاتب ترويسة، وجسم كائنات، وجدول مرجعية متقاطعة، ومقطورة بموجب Spec: ISO 32000-2, §7.5 . إنّ تركيز ذلك الالتزام في مرحلة واحدة هو ما يتيح لبقية المحرك أن تبقى مركّزة على المحتوى بدلاً من تجميع بنية الملف.

مثال عملي

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

<?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.⁩ وهذا ليس المقصود. خط المعالجة هنا تفكيك معماري: مراحل ذات مسؤوليات مفردة وحدود مُحدَّدة الأنواع. لا تزال تبرمج مقابل واجهة انسيابية. المراحل هي الطريقة التي يُبنى بها المحرك ويُختبَر، لا ناقل تجمّعه يدوياً.

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

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

تصف هذه الصفحة شكل خط المعالجة، لا واجهة البرمجة الداخلية لأي مرحلة منفردة. إنّ الجرد الدقيق لسمات الاهتمام، وقواعد اختيار استراتيجية الكاتب، وحقول نموذج المحتوى تحدّدها الشِفرة والمرجع، لا هذا الشرح. إنّ العدد الدقيق للسمات تفصيل تنفيذي يمكن أن يتغيّر دون تغيير النموذج. لا تغطّي هذه الصفحة المراحل الداخلية لمحرك ⁨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.
آمن للعمال — مصمَّم بحيث تُشارَك الحالة على مستوى عمر العملية بأمان بينما تُنشأ الحالة الخاصة بكل طلب من جديد ولا يُعاد استخدامها أبداً.