Pro الإصدار

‏⁨Writer⁩

لمحة سريعة

تُلحِق وحدة ⁨Writer⁩ مراجعات تحديث تزايدي بملف ⁨PDF⁩ وتحزّم الكائنات الصغيرة في ⁨Object Streams⁩. ويفرض الكاتب التزايدي قاعدة الإلحاق فقط: يجب ألّا تتغيّر البايتات التي كانت موجودة قبل المراجعة.

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

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

التثبيت

composer require nextpdf/pro:^3

تعيش الشيفرة ضمن النطاق الاسمي NextPDF\Pro\Writer.

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

تُوفَّر قدرتان:

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

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

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

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

خلفية التصميم: التحديثات التزايدية ولماذا تهمّ.

عقد السلوك

يُرجِع IncrementalUpdateWriter::writeRevision(...) إزاحة البايت لجدول الإحالة المرجعية الجديد، كي تستطيع تسلسل مراجعات إضافية.
يتحقّق الكاتب من أنّ البادئة الأصلية متطابقة بايتيًا قبل الكتابة وبعدها. ويرفع التباعدُ استثناء كاتب يحمل حالة انتهاك قاعدة الإلحاق فقط.
تستخدم المراجعة الجديدة جدول إحالة مرجعية تقليديًا ومُذيَّلًا بمؤشِّر /Prev؛ ويُسمَح بخلط الجداول والتدفّقات عبر المراجعات.
يرفع ObjectStreamWriter::addObject() خطأ تجاوز عندما تتجاوز إضافة كائن الحجمَ الأقصى للتدفّق (65,536 بايتًا غير مضغوطة للفهرس مع الجسم).
يرفع ObjectStreamWriter::build() خطأً عند عدم إضافة أي كائنات؛ وإلّا يُرجِع محتوى ⁨Object Stream⁩ المضغوط.

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

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

use NextPDF\Pro\Writer\ObjectStreamWriter;

$writer = new ObjectStreamWriter();
$writer->addObject(10, $serializedObjectBody);
$objStm = $writer->build();

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

use NextPDF\Pro\Writer\IncrementalUpdateWriter;

$newXrefOffset = IncrementalUpdateWriter::writeRevision(
    $buffer,
    $registry,
    $prevXrefOffset,
    $catalogObject,
    $catalogEntries,
    $catalogUpdates,
    $newObjectNumbers,
    $fileId,
);
// A WriterException here means the append-only rule was violated.
// Treat it as a hard failure; do not emit the output.

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

ينسخ فحص الإلحاق فقط البادئة القائمة. وتنمو الكلفة مع حجم المستند المكتوب بالفعل. وهذه الكلفة مقصودة وتحمي البايتات الموقَّعة.
حدّ حجم ⁨Object Stream⁩ على الفهرس والجسم مجتمعَين قبل الضغط. جمِّع الكائنات تبعًا لذلك.
يجب ألّا تتضمّن ⁨Object Streams⁩ أنواع كائنات معيّنة (مثل قاموس التشفير). ضَع تلك كائناتٍ غير مباشرة مباشِرة.

الأداء

التحقّق من الإلحاق فقط خطّي في حجم بادئة المستند القائمة. ويقلّل تحزيم ⁨Object Stream⁩ حجم الإحالة المرجعية ويحسّن الضغط مقابل كلفة مرور ضغط إضافي واحد. ولا يوجد رقم إنتاجية منشور. قِس بمستندات تمثيلية.

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

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

المطابقة

يعلّق المصدر على نحو التحديث التزايدي ونموذج ⁨Object Stream⁩ في ⁨ISO 32000-2⁩ ومتطلّبات تسلسل المراجعات في ملف تعريف ⁨ETSI EN 319 142-1⁩ لـ⁨PAdES⁩. ولأنّ متن ⁨RAG⁩ لم يكن متاحًا وقت التأليف، تكرّر هذه الصفحة فقط مراجع البنود التي يصرّح بها المصدر نفسه ولا تؤكّد أي مُعرِّفات بنود خارجية إضافية.

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

يضيف ⁨Enterprise⁩ ميزات دورة حياة توقيع أعلى طبقةً (التحقّق طويل الأمد والتجديد) تبني على التحديثات التزايدية على مستوى السلوك. وتوفّر وحدة ⁨Writer⁩ بدائية المراجعة فقط؛ وتلك الميزات الأعلى طبقةً موثَّقة بصورة منفصلة وليست مطلوبة لكتابة مراجعة.

تراجُع النواة / البديل

من دون ⁨Pro⁩، استخدم كاتب ⁨NextPDF Core⁩ الأساسي؛ ومراجعات التحديث التزايدي ببوّابة الإلحاق فقط وتحزيم ⁨Object Stream⁩ إضافات من ⁨Pro⁩. راجِع /modules/writer/.

حدّ النشر

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