‏⁨Writer⁩ — مرجع متعمّق

لمحة سريعة

تكتب وحدة ⁨Writer⁩ مراجعات التحديث التزايدي لملفات ⁨PDF⁩ وتحزم الكائنات الصغيرة في ⁨Object Streams⁩. ويفرض الكاتب التزايدي قاعدة إلحاق-فقط فاشلة-الإغلاق: كل بايت احتفظ به المخزن المؤقت قبل مراجعةٍ ما يجب أن يبقى دون تغيير بعدها. ويجمّع باني ⁨Object Stream⁩ الكائنات المؤهَّلة في كائن /Type /ObjStm واحد مضغوط بـ⁨FlateDecode⁩ ضمن حجم محدود.

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

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

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

تقع الوحدة ضمن مساحة الأسماء NextPDF\Pro\Writer. وجميع الرموز العامة مدرَجة أدناه. وكائنات القيمة أصنافٌ ثابتة من نوع final readonly.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُرجَعة	يرفع أو يفشل بـ	ملاحظات
IncrementalUpdateWriter::writeRevision	BinaryBuffer $buffer, ObjectRegistry $registry, int $prevXrefOffset, int $catalogObject, array $catalogEntries, array $catalogUpdates, array $newObjectNumbers, string $fileId	ثابت. يعيد كتابة الفهرس بمُدخَلات مدموجة، ويُلحِق جدول إحالة مرجعية تقليديًا للكائنات الجديدة والمعدَّلة، ويكتب مُذيَّلًا بـ/Size و/Root و/Prev و/ID. ويتحقّق بعدها من أن بادئة ما-قبل-المراجعة متساوية بايتيًا.	int — إزاحة بايت جدول الإحالة المرجعية الجديد	\NextPDF\Exception\WriterException عند فشل فحص بادئة الإلحاق-فقط؛ ويُرجِع getWriterState() القيمة dss-append-only-invariant	نقطة دخول ثابتة. لا مخرَج قابل للاستخدام عند الانتهاك.
ObjectStreamWriter::addObject	int $objectNumber, string $content	يُلحِق كائنًا واحدًا بالتدفّق المعلَّق بعد فحص حجم.	void	OverflowException عندما يتجاوز الفهرس مع الجسم مجتمعَين 65,536 بايتًا	يستثني $content غلافَي N 0 obj / endobj.
ObjectStreamWriter::canAccept	string $content	يقدّر عبء الفهرس ويختبر المجموع الجاري مقابل الحدّ الأقصى.	bool	لا يرفع استثناءً	مُسنِد صرف؛ دون تغيير حالة.
ObjectStreamWriter::build	لا شيء	يبني الفهرس، ويسلسل الأجسام، ويضغط بـ⁨FlateDecode⁩، ويلفّ قاموس /Type /ObjStm.	string — محتوى ⁨Object Stream⁩ الخام	ObjectStreamWriteException عند عدم إضافة أي كائنات، أو عند فشل ضغط ⁨zlib⁩	يُسنِد المُستدعي رقم الكائن ويلفّ العلامات.
ObjectStreamWriter::getEntries	لا شيء	يعيد حساب الإزاحات النسبية للجسم للكائنات المتراكمة.	list<ObjectStreamEntry>	لا يرفع استثناءً	الإزاحات نسبية إلى قسم الجسم.
ObjectStreamWriter::count	لا شيء	يُبلِغ عن عدد الكائنات المتراكمة.	int	لا يرفع استثناءً	—
ObjStmCompressor::__construct	int $maxStreamSize = 65536, int $maxObjectsPerStream = 200	يخزّن حدَّي الحجم وعدد الكائنات المستخدَمَين في التجميع.	—	لا يرفع استثناءً	تطابق القيم الافتراضية ضبط ⁨Object Stream⁩ في الوحدة.
ObjStmCompressor::groupObjects	list<array{number: int, generation?: int, content: string}> $objects	يرشّح الكائنات غير المؤهَّلة، ثم يحزم الباقي في كتّاب ضمن حدَّي الحجم والعدد.	list<ObjectStreamWriter>	لا يرفع استثناءً؛ وتُتخطّى الكائنات غير المؤهَّلة	تسقط الكائنات ذات الجيل غير الصفري إلى التسلسل العادي.
ObjStmCompressor::isEligible	string $content, int $generation = 0	يرفض كائنات التدفّق و/Encrypt و/XRef و/Catalog وأي جيل غير صفري.	bool	لا يرفع استثناءً	مطابقة /Type متسامحة مع المسافات البيضاء وهروب #xx.
ObjStmCompressor::writeToBuffer	list<ObjectStreamWriter> $streams, BinaryBuffer $buffer, ObjectRegistry $registry	يخصّص كائن حامل لكل تدفّق، ويسجّل مُدخَلات مضغوطة من النوع-2، ويكتب كل كتلة ⁨ObjStm⁩.	list<int> — أرقام الكائنات الحاملة	ينشر ObjectStreamWriteException من build() عند فشل ضغط نادر	يُشغَّل بعد كتابة الكائنات غير المؤهَّلة وقبل إصدار الإحالة المرجعية.
ObjStmCompressor::estimateSavings	list<ObjectStreamWriter> $streams, int $originalSize	يبني كل تدفّق لقياس الحجم المضغوط مقابل الأصلي.	ObjStmCompressionResult	ينشر ObjectStreamWriteException من build() عند فشل ضغط نادر	مساعد قياس للقراءة فقط.
ObjectStreamEntry::__construct	int $objectNumber, string $content, int $offset	سجلّ ثابت لكائن محزوم واحد وإزاحة جسمه.	—	لا يرفع استثناءً	final readonly؛ خصائص عامة.
ObjStmCompressionResult::__construct	int $originalObjectCount, int $streamCount, int $estimatedOriginalSize, int $estimatedCompressedSize	حاوية مقاييس ثابتة.	—	لا يرفع استثناءً	final readonly؛ خصائص عامة.
ObjStmCompressionResult::savedBytes	لا شيء	يُرجِع الحجم الأصلي ناقص المضغوط.	int	لا يرفع استثناءً	قد يكون سالبًا عندما يوسّع الحزم البيانات.
ObjStmCompressionResult::savedPercent	لا شيء	يُرجِع نسبة التخفيض المئوية.	float	لا يرفع استثناءً	يُرجِع 0.0 عندما يكون الحجم الأصلي صفرًا.
ObjStmCompressionResult::compressionRatio	لا شيء	يُرجِع الحجم المضغوط على الأصلي.	float	لا يرفع استثناءً	يُرجِع 1.0 عندما يكون الحجم الأصلي صفرًا.
ObjectStreamWriteException	—	يشير إلى فشل بناء ⁨Object Stream⁩.	—	يمدّد RuntimeException	يُرفَع من build()؛ ويمكن التقاطه عبر RuntimeException للتوافق الخلفي.

توقيعات نقاط الدخول

final class IncrementalUpdateWriter
{
    public static function writeRevision(
        BinaryBuffer $buffer,
        ObjectRegistry $registry,
        int $prevXrefOffset,
        int $catalogObject,
        array $catalogEntries,
        array $catalogUpdates,
        array $newObjectNumbers,
        string $fileId,
    ): int;
}

final class ObjectStreamWriter
{
    public function addObject(int $objectNumber, string $content): void;
    public function canAccept(string $content): bool;
    public function build(): string;
    /** @return list<ObjectStreamEntry> */
    public function getEntries(): array;
    public function count(): int;
}

final class ObjStmCompressor
{
    public function __construct(
        int $maxStreamSize = 65536,
        int $maxObjectsPerStream = 200,
    );

    /**
     * @param list<array{number: int, generation?: int, content: string}> $objects
     * @return list<ObjectStreamWriter>
     */
    public function groupObjects(array $objects): array;

    public function isEligible(string $content, int $generation = 0): bool;

    /**
     * @param list<ObjectStreamWriter> $streams
     * @return list<int>
     */
    public function writeToBuffer(array $streams, BinaryBuffer $buffer, ObjectRegistry $registry): array;

    /** @param list<ObjectStreamWriter> $streams */
    public function estimateSavings(array $streams, int $originalSize): ObjStmCompressionResult;
}

عقد السلوك

يكتب writeRevision مراجعة تحديث تزايدي واحدة. ويلتقط لقطة لبادئة المخزن المؤقت القائمة قبل الكتابة. ويعيد كتابة الفهرس بمُدخَلات مدموجة، ويسجّل إزاحات الكائنات الجديدة، ويكتب جدول إحالة مرجعية تقليديًا مجمَّعًا في أقسام فرعية متجاورة، ويكتب مُذيَّلًا بـ/Size و/Root و/Prev و/ID. وبعد الكتابة، يقارن البادئة مرّة أخرى. وإن تغيّر أي بايت سابق، يرفع WriterException حاملًا حالة انتهاك الإلحاق-فقط ولا يُرجِع مخرَجًا قابلًا للاستخدام. وعند النجاح يُرجِع إزاحة بايت جدول الإحالة المرجعية الجديد لتسلسل مراجعات إضافية. ويُسمَح بخلط جداول الإحالة المرجعية وتدفّقاتها عبر المراجعات.

يراكِم ObjectStreamWriter الكائنات. ويرفع addObject خطأ تجاوز عندما يتجاوز الفهرس والجسم مجتمعَين الحدّ الأقصى البالغ 65,536 بايتًا غير مضغوطة. ويرفع build خطأً عند تدفّق فارغ؛ وإلّا فإنه يضغط الفهرس مع الجسم ويُرجِع محتوى ⁨Object Stream⁩ بمُدخَلات /Type /ObjStm و/N و/First و/Length و/Filter /FlateDecode. ويُسنِد المُستدعي رقم الكائن ويلفّ علامتَي N 0 obj / endobj.

يقرّر ObjStmCompressor أي الكائنات يُحزَم. وهو يستثني كائنات التدفّق، وقواميس التشفير، وتدفّقات الإحالة المرجعية، وفهرس المستند، وأي كائن يحمل رقم جيل غير صفري. ويخصّص writeToBuffer كائنًا حاملًا لكل تدفّق، ويسجّل كل كائن محزوم كمُدخَل إحالة مرجعية مضغوط من النوع-2، ويكتب كتلة ⁨ObjStm⁩ عند الإزاحة الحالية للمخزن المؤقت. ويبني estimateSavings كل تدفّق لحساب مقاييس الحجم دون تعديل المخزن المؤقت.

الحالات الحدّية وأوضاع الفشل

• ينسخ فحص الإلحاق-فقط البادئة القائمة. وتنمو كلفته مع حجم المستند المكتوب بالفعل. وهذه الكلفة مقصودة وتحمي البايتات الموقَّعة.
• يسري حدّ ⁨Object Stream⁩ على الفهرس غير المضغوط مع الجسم. ضَع قاموس التشفير وسائر أنواع الكائنات المستثناة كائناتٍ غير مباشرة مباشِرة.
• استثناء /Type متسامح مع أي مسافات بيضاء بين الرموز ومع هروب #xx الست عشري. فالصيغ مثل /Type /Encrypt و/Type\n/Encrypt و/Type /#45ncrypt كلها مرفوضة، وليست الكتابة الحرفية القانونية وحدها.
• أي كائن يحمل رقم جيل غير صفري يُعامَل بوصفه غير مؤهَّل ويسقط إلى التسلسل العادي N G obj … endobj، لأن جيل الكائن المضغوط صفرٌ ضمنًا.
• يجب أن يُشغَّل writeToBuffer بعد كتابة جميع الكائنات غير المؤهَّلة وقبل إصدار الإحالة المرجعية. ويجب ألّا تُسلسَل الكائنات المحزومة على حدة أيضًا.

سلوك وضع ⁨FIPS⁩

لا تؤدّي وحدة ⁨Writer⁩ أي عمليات تشفير. وهي تحمي البايتات الموقَّعة برفض الإصدار عندما يتغيّر بايت سابق، وهو اختبار تساوٍ بايتي لا اختبار تشفيري. ووحدة التوقيع هي ما يحكم اختيار خوارزمية ⁨FIPS⁩ للتوقيع والتجزئة، لا هذا الكاتب. ولا يغيّر تفعيل وضع ⁨FIPS⁩ أو تعطيله سلوك أي طريقة من طرائق ⁨Writer⁩.

المطابقة

تنفّذ ⁨NextPDF⁩ الوحدة وفق ⁨ISO 32000-2:2020⁩. ويتّبع الكاتب التزايدي قواعد التحديث التزايدي في §⁨7.5.6⁩: تُلحِق كل مراجعة قسم إحالة مرجعية يغطّي الكائنات الجديدة أو المتغيّرة أو المحذوفة فقط، ومُذيَّلًا يعطي مُدخَله /Prev إزاحة الإحالة المرجعية السابقة. ويتّبع باني ⁨Object Stream⁩ نموذج تدفّق الكائنات في §⁨7.5.7⁩: فهرسٌ من أزواج رقم-الكائن والإزاحة، بإزاحات تُقاس من مُدخَل /First بترتيب تصاعدي، يسبق أجسام الكائنات المحزومة. وقد جرى التحقّق من مرجعَي البندين كليهما مقابل متن ⁨ISO 32000-2:2020⁩. ويتّبع تسلسل المراجعات لسير عمل ⁨PAdES B-LT⁩ و⁨B-LTA⁩ المعيار ⁨ETSI EN 319 142-1⁩ §⁨5.4⁩، كما هو مُعلَّق في المصدر. ودعم بندٍ ما تصريحُ قدرة هندسية لا شهادة اعتماد؛ ولا تحمل ⁨NextPDF⁩ أي شهادة مطابقة رسمية.

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

• ثبّت الحزمة بـcomposer require nextpdf/pro:^3. وتُحَل الأصناف ضمن NextPDF\Pro\Writer.
• ‏IncrementalUpdateWriter::writeRevision نقطة دخول ثابتة؛ ولا يحمل حالة نسخة بين المراجعات.
• تشكّل ObjectStreamEntry وObjStmCompressionResult وIncrementalUpdateWriter والضاغط معًا السطح العام للوحدة؛ ولا يشحن المستودع أي مثال قابل للتشغيل لها.
• يشير WriterException الصادر من writeRevision إلى انتهاك الإلحاق-فقط. عامِله بوصفه فشلًا صارمًا واطرح المخزن المؤقت.
• الكائنات الحاملة لـ⁨Object Stream⁩ كائنات غير مباشرة؛ ويُسنِد المُستدعي أرقام كائناتها عبر السجلّ.

حدود النشر

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

انظر أيضًا

• ‏⁨Writer⁩
• ‏⁨Document⁩ — مرجع متعمّق
• ‏⁨Optimizer⁩ — مرجع متعمّق