الإسقاط

لمحة سريعة

يحلّل الإسقاط تدفّق محتوى ⁨PDF⁩ إلى قائمة رموز مسطّحة، ويُصدِر تدفّق محتوى جديدًا من تلك الرموز. ويتطلّب الإصدار قصدًا مُعلَنًا صريحًا. وهذه الوحدة ليست محرّر ⁨PDF⁩ عامّ الغرض.

ملاحظة. يعني «الإسقاط» هنا إسقاط رموز تدفّق المحتوى. وهو ليس إسقاطًا إحداثيًا أو جغرافيًا مكانيًا. وللميزات الجغرافية المكانية، راجِع وحدة ⁨Geo⁩.

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

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

لا يوجد علم ترخيص منفصل لكل ميزة. ويضبط مُعامل ProjectionIntent المطلوب الإصدارَ على مستوى الواجهة البرمجية، لا مفتاح ترخيص.

التثبيت

composer require nextpdf/pro:^3

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

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

يوفّر ContentProjectionWriter ثلاث عمليات ساكنة:

• يحلّل tokenize() تدفّق محتوى إلى قائمة رموز مسطّحة ومرتَّبة. وهذه للقراءة فقط ولا تحتاج إلى قصد.
• يكتب emit() تدفّق محتوى جديدًا من قائمة رموز (قد تكون معدَّلة). ويتطلّب ProjectionIntent.
• يُجزِّئ roundTrip() ثم يعيد الإصدار من دون تغيير، للتحقّق.

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

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

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

خلفية التصميم: الحجب ليس مستطيلًا أسود.

عقد السلوك

• يعيد tokenize($contentStream) قائمة رموز تغطّي السلاسل، والأسماء، والأعداد، والمصفوفات، والقواميس، والقيم المنطقية، و⁨null⁩، والمعاملات.
• يتطلّب emit($tokens, $intent) قصدًا صريحًا؛ ويفرض نظام الأنواع هذا عند موضع الاستدعاء.
• مخرَج roundTrip() ليس متطابقًا بايتيًا مع المدخل، لكن تسلسل المعاملات وقيم المعاملات يتطابقان.
• ينسّق المُصدِر الأعداد للحفاظ على تمييز العدد الصحيح والعدد العشري ويعيد تهريب السلاسل الحرفية.
• القصدان المُعلَنان هما التطهير (عملية حجب إتلافية وغير قابلة للعكس) والتضمين الإخفائي.

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

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

use NextPDF\Pro\Projection\ContentProjectionWriter;

$tokens = ContentProjectionWriter::tokenize($contentStream);

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

use NextPDF\Pro\Projection\ContentProjectionWriter;
use NextPDF\Pro\Projection\ProjectionIntent;

$tokens = ContentProjectionWriter::tokenize($contentStream);

// Validate first: a clean round-trip must hold before any modification.
$check = ContentProjectionWriter::roundTrip($contentStream);

// Apply your modification to $tokens, then emit with a declared intent.
$output = ContentProjectionWriter::emit($tokens, ProjectionIntent::Sanitization);

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

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

الأداء

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

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

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

المطابقة

تتبع التجزئة الأعراف المعجمية وأعراف تدفّق المحتوى في ⁨ISO 32000-2⁩؛ ويُؤشِّر المصدر البنود ذات الصلة. ولم تكن مجموعة ⁨RAG⁩ متاحة وقت التأليف، لذا لا تؤكّد هذه الصفحة أي مُعرِّفات بنود خارجية وتقصر بيانات المطابقة على السلوك المُتحقَّق منه باختبارات الوحدة.

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

لا يغيّر ⁨Enterprise⁩ سلوك الإسقاط. يضيف ⁨Enterprise⁩ ميزات خصوصية وامتثال أعلى مستوى مُوثَّقة على حدة؛ وهي ليست لازمة لاستخدام واجهة الإسقاط البرمجية.

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

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

حدّ النشر

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

انظر أيضًا

• مرجع الإسقاط
• ⁨AST⁩
• الكاتب
• ⁨Geo⁩