Writer

ภาพรวมโดยสรุป

โมดูล Writer ผนวก revision แบบ incremental-update เข้ากับ PDF และแพ็กออบเจกต์ขนาดเล็กเข้าใน Object Stream โดย incremental writer บังคับใช้กฎ append-only คือไบต์ที่มีอยู่ก่อน revision ต้องไม่เปลี่ยนแปลง

ความพร้อมใช้งานและการอนุญาต

ความสามารถนี้จัดส่งใน NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วย license envelope ระดับ Pro การติดตั้งที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ Compare editions and get a license ไม่มีแฟล็กใบอนุญาตแยกต่อฟีเจอร์ โค้ดจัดส่งมาพร้อมกับรุ่น Pro

การติดตั้ง

composer require nextpdf/pro:^3

โค้ดอยู่ภายใต้ namespace NextPDF\Pro\Writer

ภาพรวมเชิงแนวคิด

มีสองความสามารถที่จัดให้:

• IncrementalUpdateWriter เขียน revision ใหม่ มันเขียน catalog ใหม่ด้วยรายการที่ผสานแล้ว ผนวก cross-reference table แบบดั้งเดิมสำหรับออบเจกต์ใหม่และที่ถูกแก้ไข และเขียน trailer ที่ลิงก์ไปยัง revision ก่อนหน้า มันบังคับใช้กฎ append-only แบบ fail-closed
• ObjectStreamWriter จัดกลุ่มออบเจกต์ขนาดเล็กเข้าใน Object Stream ที่ถูกบีบอัดเดียว สิ่งนี้ลดขนาดของ cross-reference table และปรับปรุงการบีบอัด มันปฏิเสธออบเจกต์ที่จะเกินขนาด stream สูงสุด และปฏิเสธ stream ที่ว่าง

กฎ append-only ปกป้องลายเซ็นที่มีอยู่ ทุกไบต์ที่บัฟเฟอร์ถือไว้ก่อน revision ต้องปรากฏโดยไม่เปลี่ยนแปลงที่ตำแหน่งเดียวกันหลัง revision หากไบต์ก่อนหน้าใดเปลี่ยนไป writer จะยกข้อผิดพลาดและไม่ผลิตผลลัพธ์

ทำไมจึงทำงานเช่นนี้

ทางเลือกที่รับน้ำหนักคือตำแหน่งที่เกต append-only อยู่ มันอยู่ที่ระดับ writer ไม่ใช่เพียงใน orchestrator ระดับสูงกว่าเท่านั้น ดังนั้นทุกผู้เรียกทั้งปัจจุบันและอนาคตจึงได้รับการครอบคลุมแบบ fail-closed สืบทอดมา การตรวจสอบเป็นการทดสอบความเท่ากันของ prefix ล้วน ๆ คือ writer สแนปช็อต prefix ของบัฟเฟอร์ก่อนผนวก แล้วยืนยันว่าทุกไบต์ก่อนหน้าไม่เปลี่ยนแปลงหลังจากนั้น สิ่งนี้ปกป้องลายเซ็นใดก็ตามที่ /ByteRange ครอบคลุม prefix เพราะไบต์ที่เปลี่ยนไปเพียงไบต์เดียวจะทำให้มันเป็นโมฆะโดยเงียบ ๆ cross-reference table แบบดั้งเดิมและตัวชี้ /Prev เป็นตัวพา revision ใหม่ เพราะ incremental update ต้องผนวกแทนที่จะเขียนใหม่ ต้นทุนการตรวจสอบเป็นเชิงเส้นตามขนาดของ prefix ที่มีอยู่ และต้นทุนนั้นเป็นที่ยอมรับโดยเจตนา คือความสมบูรณ์ของไบต์ที่ลงนามแล้วสำคัญกว่าสำเนาชุดที่สอง

พื้นเพการออกแบบ: Incremental updates and why they matter

สัญญาพฤติกรรม

• IncrementalUpdateWriter::writeRevision(...) คืนค่า byte offset ของ cross-reference table ใหม่ เพื่อให้คุณร้อยต่อ revision ถัดไปได้
• writer ตรวจสอบว่า prefix ต้นฉบับเท่ากันในระดับไบต์ทั้งก่อนและหลังเขียน การเบี่ยงเบนจะยกข้อยกเว้นของ writer ที่พกสถานะ append-only-violation
• revision ใหม่ใช้ cross-reference table แบบดั้งเดิมและ trailer ที่มีตัวชี้ /Prev การผสม table และ stream ข้าม revision ต่าง ๆ เป็นที่อนุญาต
• ObjectStreamWriter::addObject() ยกข้อผิดพลาด overflow เมื่อการเพิ่มออบเจกต์จะเกินขนาด stream สูงสุด (65,536 ไบต์แบบไม่บีบอัดสำหรับ index บวก body)
• ObjectStreamWriter::build() ยกข้อผิดพลาดเมื่อไม่มีการเพิ่มออบเจกต์ใด มิฉะนั้นมันจะคืนเนื้อหา Object Stream ที่ถูกบีบอัด

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

สิ่งต่อไปนี้สะท้อน public API ที่บันทึกไว้ repository ไม่ได้จัดส่งตัวอย่างที่รันได้สำหรับโมดูลนี้

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.

กรณีขอบและข้อควรระวัง

• การตรวจสอบ append-only ทำสำเนา prefix ที่มีอยู่ ต้นทุนเพิ่มตามขนาดของเอกสารที่เขียนไปแล้ว ต้นทุนนี้เป็นความตั้งใจและปกป้องไบต์ที่ลงนามแล้ว
• ขีดจำกัดขนาดของ Object Stream อยู่ที่ index และ body รวมกันก่อนการบีบอัด ให้จัดกลุ่มออบเจกต์ตามนั้น
• Object Stream ต้องไม่มีชนิดออบเจกต์บางชนิด (เช่น พจนานุกรมการเข้ารหัส) ให้วางออบเจกต์เหล่านั้นเป็น direct indirect object

ประสิทธิภาพ

การตรวจสอบ append-only เป็นเชิงเส้นตามขนาดของ prefix ของเอกสารที่มีอยู่ การแพ็ก Object Stream ลดขนาดของ cross-reference และปรับปรุงการบีบอัด โดยแลกกับการ pass บีบอัดเพิ่มหนึ่งครั้ง ไม่มีตัวเลข throughput ที่เผยแพร่ ให้วัดด้วยเอกสารที่เป็นตัวแทน

หมายเหตุด้านความปลอดภัย

incremental writer เป็น fail-closed หากเส้นทางโค้ดจะเปลี่ยนไบต์ที่ลายเซ็นก่อนหน้าครอบคลุมอยู่ writer จะยกข้อผิดพลาดแทนที่จะผลิตเอกสาร สิ่งนี้ปกป้องความสมบูรณ์ของลายเซ็นสำหรับเวิร์กโฟลว์ที่ร้อยต่อ revision ไม่มีการบันทึกเนื้อหาเอกสาร

ความสอดคล้อง

ซอร์สมีคำอธิบายไวยากรณ์ incremental-update และแบบจำลอง Object Stream ใน ISO 32000-2 และข้อกำหนดการร้อยต่อ revision ในโปรไฟล์ PAdES ของ ETSI EN 319 142-1 เนื่องจากคอร์ปัส RAG ไม่พร้อมใช้งานในเวลาเขียนเอกสาร หน้านี้จึงทำซ้ำเฉพาะการอ้างอิงข้อกำหนดที่ซอร์สเองประกาศไว้เท่านั้น และไม่ยืนยันตัวระบุข้อกำหนดภายนอกเพิ่มเติมใด ๆ

หมายเหตุขอบเขต Enterprise

Enterprise เพิ่มฟีเจอร์วงจรชีวิตลายเซ็นระดับสูงขึ้น (การตรวจสอบความถูกต้องระยะยาวและการต่ออายุ) ที่ต่อยอดจาก incremental update ในระดับพฤติกรรม โมดูล Writer มอบเฉพาะไพรมิทีฟ revision เท่านั้น ฟีเจอร์ระดับสูงขึ้นเหล่านั้นถูกบันทึกแยกต่างหากและไม่จำเป็นสำหรับการเขียน revision

การถอยกลับไปใช้ Core / ทางเลือก

หากไม่มี Pro ให้ใช้ writer พื้นฐานของ NextPDF Core revision แบบ incremental-update พร้อมเกต append-only และการแพ็ก Object Stream เป็นส่วนเพิ่มของ Pro ดู /modules/writer/

ขอบเขตการเผยแพร่

หน้านี้อธิบายเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว public API ที่รองรับเท่านั้น path ของ namespace ภายใน คลาส helper ตาราง mechanism ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต

ดูเพิ่มเติม

• Writer — Deep Reference
• Document
• Optimizer
• Output Pipeline