Merge — การอ้างอิงเชิงลึก

ภาพรวมโดยสังเขป

หน้านี้เป็นการอ้างอิงระดับสัญญาสำหรับโมดูล NextPDF Pro Merge คือ NextPDF\Pro\Merge โดย SmartMerger ประกอบเอกสารอินพุตหลายฉบับเข้าเป็นฉบับเดียวและใช้การเสริมของ Pro ได้แก่ ต้นไม้บุ๊กมาร์กที่รวมจากป้ายกำกับของแต่ละอินพุต การขจัดข้อมูลซ้ำทั้งเอกสาร การเลือกช่วงหน้าของแต่ละอินพุต และการตรวจจับลิงก์ภายใน ส่วน SemanticSplitter เป็นจุดเข้าใช้งานการแยกที่รับรู้โครงสร้างซึ่งเป็นคู่กัน หน้านี้ระบุ API สาธารณะ สัญญาพฤติกรรมที่สังเกตได้ ขอบเขตทรัพยากร และโหมดความล้มเหลว การตั้งค่าเชิงงานและตัวอย่างอยู่ที่หน้าความสามารถ Merge

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

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

ไม่มีแฟล็กความสามารถขณะรันที่จำกัดโมดูลนี้ คลาส Merge ใช้งานได้เมื่อใดก็ตามที่ติดตั้งและมีใบอนุญาต nextpdf/pro

พื้นผิว API สาธารณะ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
SmartMerger::__construct()	?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null	รับและละเว้นตัวรวมของ Core แบบเดิม null splitter จะสร้าง Pro splitter เริ่มต้น	—	—	$coreMerger คงไว้เพื่อการสร้างที่เข้ากันได้ย้อนหลังเท่านั้น
SmartMerger::merge()	list<MergeInput> $inputs, SmartMergeConfig $config = new SmartMergeConfig()	ลดช่วงหน้า ขจัดอินพุตทั้งฉบับที่ซ้ำ มอบหมายการประกอบพื้นฐาน จากนั้นแทรกบุ๊กมาร์กและนับลิงก์ตามการตั้งค่า	SmartMergeResult	InvalidArgumentException เมื่อรายการอินพุตว่าง OverflowException เมื่อจำนวนอินพุตเกิน maxInputs หรืออินพุตหนึ่งเกิน maxBytesPerInput	จุดเข้าใช้งานการรวมเพียงจุดเดียว
MergeInput::__construct()	string $pdfData, list<PageRange> $pageRanges = [], string $label = ''	อ็อบเจกต์ค่า $pageRanges ที่ว่างจะเลือกทุกหน้า	—	—	Readonly
MergeInput::hasPageRanges()	—	จริงเมื่ออินพุตมีช่วงหน้าอย่างน้อยหนึ่งช่วง	bool	—	—
SmartMergeConfig::__construct()	bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000	อ็อบเจกต์ค่าที่เก็บสวิตช์การเสริมและขอบเขตทรัพยากร	—	—	Readonly การขจัดข้อมูลซ้ำต้องเลือกเปิดเอง
SmartMergeConfig::default()	—	เปิดบุ๊กมาร์กและการสแกนลิงก์ ปิดการขจัดข้อมูลซ้ำ	self	—	Static factory
SmartMergeConfig::basic()	—	ปิดการเสริมทั้งหมด ต่อกันแบบพื้นฐานเท่านั้น	self	—	Static factory
SmartMergeResult::__construct()	string $pdfData, int $totalPages, int $sourceCount, int $mergedSize, int $bookmarksAdded = 0, int $duplicatesRemoved = 0, int $linksRewritten = 0, list<string> $inputLabels = []	ตัวนำพา Readonly สำหรับไบต์ที่รวมแล้วและสถิติการรวม	—	—	Readonly
SmartMergeResult::isValid()	—	จริงเมื่อเอาต์พุตขึ้นต้นด้วยส่วนหัว %PDF	bool	—	ตรวจสอบเฉพาะส่วนหัว
SmartMergeResult::hasOptimizations()	—	จริงเมื่อมีการลบข้อมูลซ้ำหรือนับลิงก์ใดๆ	bool	—	—
SemanticSplitter::__construct()	?PdfSplitter $splitter = null	อาร์กิวเมนต์ null จะสร้าง Pro splitter เริ่มต้น	—	—	การฉีดผ่านคอนสตรัคเตอร์เพื่อการทดสอบ
SemanticSplitter::splitByStructure()	string $pdfData, float $headingFontThreshold = 14.0	ตรวจจับตัวดำเนินการ Tf ขนาดหัวเรื่องเป็นจุดเริ่มของส่วนและแยกที่ขอบเขตเหล่านั้น หากไม่พบโครงสร้างจะคืนส่วนเดียวทั้งเอกสาร	SplitResult	InvalidArgumentException เมื่อบัฟเฟอร์ว่างหรือไม่มีส่วนหัว %PDF OverflowException เมื่ออินพุตเกิน 100 MB	ถอยกลับไปใช้การแยกช่วงหน้าของ Core

ลายเซ็นจุดเข้าใช้งาน

public function __construct(
    ?PdfMerger $coreMerger = null,
    ?PdfSplitter $splitter = null,
)

public function merge(
    array $inputs,
    SmartMergeConfig $config = new SmartMergeConfig(),
): SmartMergeResult

public function __construct(
    public string $pdfData,
    public array $pageRanges = [],
    public string $label = '',
)

public function hasPageRanges(): bool

public function __construct(
    public bool $consolidateBookmarks = true,
    public bool $deduplicatePages = false,
    public bool $rewriteLinks = true,
    public int $maxInputs = 100,
    public int $maxBytesPerInput = 100_000_000,
)

public static function default(): self

public static function basic(): self

public function isValid(): bool

public function hasOptimizations(): bool

public function __construct(?PdfSplitter $splitter = null)

public function splitByStructure(
    string $pdfData,
    float $headingFontThreshold = 14.0,
): SplitResult

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

ไปป์ไลน์การรวม

SmartMerger::merge() รันไปป์ไลน์คงที่ ซึ่งสังเกตจากภายนอกได้ดังนี้

1. รายการอินพุตที่ว่างจะทำให้เกิด InvalidArgumentException จากนั้นจำนวนอินพุตถูกจำกัดด้วย maxInputs การเกินขอบเขตจะทำให้เกิด OverflowException
2. แต่ละอินพุตถูกตรวจขนาดเทียบกับ maxBytesPerInput ก่อนใช้ เมื่ออินพุตประกาศช่วงหน้า อินพุตนั้นจะถูกลดเหลือเฉพาะหน้าที่เลือกผ่าน Pro splitter ก่อน แล้วจึงมีส่วนร่วมเฉพาะหน้าเหล่านั้น
3. เมื่อเปิด deduplicatePages สตริงไบต์ทั้งหมดของเอกสารอินพุตแต่ละฉบับจะถูกคำนวณลายนิ้วมือด้วยฟังก์ชัน xxh128 ที่ไม่ใช่การเข้ารหัสลับ อินพุตที่มีไบต์ตรงกันทุกประการกับอินพุตก่อนหน้าจะถูกทิ้ง การขจัดข้อมูลซ้ำเป็นแบบทั้งเอกสารและตรงกันทุกไบต์
4. การประกอบพื้นฐานมอบหมายให้เอนจิน Pro PdfSplitter::mergeDocuments() ซึ่งกำหนดเลขใหม่ให้ทุกอินพุตเข้าสู่พื้นที่อ็อบเจกต์ที่ต่อเนื่องกันหนึ่งเดียวและปล่อยตารางอ้างอิงไขว้จริง
5. การรวมบุ๊กมาร์กถูกนำมาใช้เมื่อเปิด consolidateBookmarks และมีอินพุตอย่างน้อยหนึ่งฉบับที่มีป้ายกำกับไม่ว่าง มีการแทรก /Outlines dictionary ขั้นต่ำ เชื่อมจากแคตาล็อกเอกสาร โดยมีรายการ outline หนึ่งรายการต่อหนึ่งอินพุตตามลำดับการรวม
6. เมื่อเปิด rewriteLinks เอาต์พุตที่รวมแล้วจะถูกสแกนหาแอ็กชัน /S /GoTo และรายงานจำนวนของมัน

สถิติผลลัพธ์

SmartMergeResult รายงานไบต์ที่รวมแล้วพร้อมสถิติ totalPages มาจากการรวมพื้นฐาน sourceCount คือจำนวนอินพุตเดิม ซึ่งนับก่อนการขจัดข้อมูลซ้ำ mergedSize คือความยาวไบต์ของเอาต์พุต bookmarksAdded นับเฉพาะอินพุตที่ให้ป้ายกำกับไม่ว่าง duplicatesRemoved นับอินพุตทั้งฉบับที่ถูกทิ้ง linksRewritten คือจำนวน GoTo ที่ตรวจพบ inputLabels แสดงรายการป้ายกำกับที่แก้ไขแล้วตามลำดับการรวม isValid() ตรวจสอบส่วนหัว %PDF hasOptimizations() เป็นจริงเมื่อมีการลบข้อมูลซ้ำหรือนับลิงก์

ชื่อบุ๊กมาร์ก

รายการ outline แต่ละรายการนำป้ายกำกับอินพุตมาเป็น /Title โดย escape เป็น PDF literal string ตาม ISO 32000-2:2020 §7.3.4.2 มีการทำ reverse solidus เป็นสองตัวก่อน escape วงเล็บ ไบต์ควบคุมที่มีชื่อใช้ลำดับที่กำหนดไว้ และไบต์ที่พิมพ์ไม่ได้ที่เหลือจะกลายเป็น octal escape สามหลัก ดังนั้นป้ายกำกับที่มุ่งร้ายจึงไม่สามารถทำให้ตัวคั่น literal-string ผิดจังหวะหรือฉีดโครงสร้างอ็อบเจกต์ได้ อินพุตที่มีป้ายกำกับว่างจะได้รับชื่อตัวยึด Document N โดยเริ่มดัชนีที่หนึ่ง

การประกอบพื้นฐาน

Core PdfMerger::merge() แบบเดิมเป็น stub ที่ล้มเหลวแบบปิดโดยเจตนาในรุ่นนี้ และ SmartMerger ไม่เคยเรียกใช้ การรวมพื้นฐานกลับทำงานผ่าน Pro PdfSplitter::mergeDocuments() แทน ดังนั้นไฟล์ที่รวมแล้วจึงมีตารางอ้างอิงไขว้ที่แม่นยำระดับไบต์ โดยมีหนึ่งรายการต่อหนึ่งอ็อบเจกต์ทางอ้อม ตาม ISO 32000-2:2020 §7.5.4 ความเป็นดีเทอร์มินิสติกเป็นไปตามโปรไฟล์ที่บันทึกไว้ของ Pro splitter คืออินพุตและการตั้งค่าที่เหมือนกันจะให้สตรีมไบต์ที่เสถียร

การแยกที่รับรู้โครงสร้าง

SemanticSplitter::splitByStructure() สแกนสตรีมเนื้อหาหน้าเพื่อหาตัวดำเนินการ set-font Tf ที่มีขนาดเท่ากับหรือมากกว่า headingFontThreshold (ค่าเริ่มต้น 14.0) และถือว่าแต่ละหน้าดังกล่าวเป็นจุดเริ่มของส่วน ขอบเขตถูกแปลงเป็นช่วงหน้าและมอบหมายให้ Pro PdfSplitter::split() เมื่อไม่พบขอบเขตใด เอกสารทั้งฉบับจะคืนเป็นส่วนเดียว อินพุตต้องขึ้นต้นด้วย %PDF และอยู่ภายในขอบเขต 100 MB

กรณีขอบและโหมดความล้มเหลว

• รายการอินพุตที่ว่างจะล้มเหลวด้วย InvalidArgumentException ก่อนการประกอบใดๆ
• จำนวนอินพุตที่เกิน maxInputs (ค่าเริ่มต้น 100) หรืออินพุตใดที่เกิน maxBytesPerInput (ค่าเริ่มต้น 100 MB) จะล้มเหลวด้วย OverflowException ขอบเขตทั้งสองเป็นการปฏิเสธแบบล้มเหลวปิดโดยเจตนา ไม่ใช่ข้อผิดพลาดชั่วคราว
• การขจัดข้อมูลซ้ำเป็นแบบทั้งเอกสารและตรงกันทุกไบต์ อินพุตสองฉบับที่เรนเดอร์เหมือนกันแต่ต่างกันในไบต์ใดๆ จะถูกเก็บไว้ทั้งคู่ และ duplicatesRemoved นับอินพุตทั้งฉบับที่ถูกทิ้ง แม้ชื่อ deduplicatePages จะสื่อถึงระดับหน้า
• sourceCount สะท้อนจำนวนอินพุตเดิม ไม่ใช่จำนวนเอกสารหลังการขจัดข้อมูลซ้ำ
• การรวมบุ๊กมาร์กจะทำงานเฉพาะเมื่อมีอินพุตอย่างน้อยหนึ่งฉบับที่มีป้ายกำกับไม่ว่าง หาก consolidateBookmarks เป็นจริงแต่ป้ายกำกับทุกอันว่าง จะไม่มีการเขียนอ็อบเจกต์ /Outlines
• รายการ outline ที่แทรกเข้ามีชื่อและลิงก์ต้นไม้ /Parent, /Prev, /Next แต่ไม่ฝังปลายทาง /Dest ที่ชัดแจ้งในรุ่นนี้
• การเขียนลิงก์ใหม่นับเฉพาะแอ็กชัน /S /GoTo ไม่ได้ชี้ปลายทางใหม่ข้ามอ็อบเจกต์ที่กำหนดเลขใหม่ ให้ถือว่า linksRewritten เป็นจำนวนการตรวจจับ
• การตรวจจับของ SemanticSplitter เป็นเชิงคำศัพท์ โดยอาศัยตัวดำเนินการขนาดฟอนต์ Tf ดังนั้นหน้าที่มีแต่ภาพหรือเข้ารหัสผิดปกติจึงไม่เกิดขอบเขตและคืนเป็นส่วนเดียวทั้งเอกสาร

พฤติกรรมในโหมด FIPS

ไม่มีการดำเนินการเข้ารหัสลับเกิดขึ้นในโมดูลนี้ จึงไม่มีพฤติกรรมเฉพาะของโหมด FIPS ลายนิ้วมือเนื้อหา xxh128 ที่ใช้ในการขจัดข้อมูลซ้ำเป็นแฮชตรวจจับการเปลี่ยนแปลงที่ไม่ใช่การเข้ารหัสลับ และไม่มีน้ำหนักด้านความสมบูรณ์หรือหลักฐานใดๆ

ความสอดคล้องกับมาตรฐาน

ข้อกล่าวอ้าง	มาตรฐาน	ข้อ
บุ๊กมาร์กที่รวมแล้วถูกเขียนเป็น /Outlines dictionary ที่เชื่อมจากแคตาล็อกเอกสาร	ISO 32000-2:2020	§7.7.2
การรวมพื้นฐานปล่อยตารางอ้างอิงไขว้ที่แม่นยำระดับไบต์สำหรับทุกอ็อบเจกต์ทางอ้อม	ISO 32000-2:2020	§7.5.4
ชื่อรายการ outline ถูก escape เป็น PDF literal strings พร้อมการจัดการ backslash และวงเล็บ	ISO 32000-2:2020	§7.3.4.2
การแก้ไขลิงก์ข้ามเอกสารแบบเต็ม	—	ไม่รองรับ (ตรวจจับ GoTo เท่านั้น)
ปลายทาง outline ต่อส่วนที่ชัดแจ้ง	—	ไม่ปล่อยในรุ่นนี้

ข้อทุกข้อเป็นการถอดความ NextPDF ไม่ทำซ้ำข้อความเชิงบรรทัดฐาน สิ่งเหล่านี้เป็นข้อความแสดงความสามารถ ไม่ใช่การรับรอง NextPDF ไม่ถือการรับรองใดและไม่มอบการรับรองใด

หมายเหตุการพัฒนา

• ความพร้อมใช้งานภายในแพ็กเกจ Pro: SmartMerger, MergeInput, SmartMergeConfig, SmartMergeResult และ SemanticSplitter ตั้งแต่ 2.2.0 ทั้งหมดเป็นเวอร์ชันปัจจุบันใน nextpdf/pro 3.1.0
• การรวมพื้นฐานมอบหมายให้ Pro PdfSplitter::mergeDocuments() Core PdfMerger::merge() แบบเดิมเป็น stub ที่ล้มเหลวปิดในรุ่นนี้และไม่เคยถูกเรียก
• เปิด deduplicatePages เฉพาะเมื่ออินพุตอาจเป็นเอกสารทั้งฉบับที่เหมือนกันทุกไบต์ มันไม่ยุบสำเนาที่เกือบซ้ำหรือที่เข้ารหัสใหม่
• ใช้ SmartMergeConfig::basic() สำหรับการต่อกันล้วนๆ และ ::default() สำหรับบุ๊กมาร์กพร้อมการสแกนลิงก์
• จับ OverflowException เมื่อรวมอินพุตที่ไม่น่าเชื่อถือ ขอบเขตจำนวนและขนาดเป็นการปฏิเสธโดยเจตนา
• ควรใช้ Pro PdfSplitter โดยตรงสำหรับการแยกช่วงหน้าอย่างง่าย ใช้ SemanticSplitter เฉพาะเมื่อจำเป็นต้องแบ่งส่วนตามหัวเรื่อง

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

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

ดูเพิ่มเติม

• Merge (ความสามารถ) — การติดตั้ง เริ่มต้นอย่างรวดเร็ว และตัวอย่างสำหรับใช้งานจริง
• Toc — การอ้างอิงเชิงลึก
• Diff — การอ้างอิงเชิงลึก
• Document — การอ้างอิงเชิงลึก — Pro splitter และเอนจินการรวมพื้นฐาน