การผสานรวม

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

NextPDF\Pro\Merge\SmartMerger รวม PDF หลายไฟล์เข้าเป็นไฟล์เดียว จากนั้นใช้ การปรับปรุงของ Pro ได้แก่ ต้นไม้บุ๊กมาร์กที่รวมจากป้ายกำกับต่ออินพุต การกำจัดหน้าซ้ำด้วย content-hash และการเลือกช่วงหน้าต่ออินพุต การประกอบ เอกสารพื้นฐานทำงานผ่านเอนจินรวมแบบ object-graph ของ Pro ซึ่งกำหนดหมายเลข ทุกอินพุตใหม่ให้อยู่ในพื้นที่อ็อบเจกต์เดียวและเขียนตารางอ้างอิงไขว้จริง

ความพร้อมใช้งานและการอนุญาตใช้สิทธิ์

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

คลาส Merge พร้อมใช้งานเมื่อใดก็ตามที่ติดตั้งแพ็กเกจ Pro ไว้ ไม่มีแฟล็กความสามารถในขณะรันไทม์มาเกตโมดูลนี้

การติดตั้ง

composer require nextpdf/pro:^3

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

SmartMerger รับรายการ value object MergeInput อินพุตแต่ละตัว พกพาไบต์ของ PDF ต้นทาง รายการช่วงหน้าที่เลือกได้ และป้ายกำกับ ที่เลือกได้ อินพุตที่มีช่วงหน้าจะถูกลดเหลือเฉพาะหน้าที่เลือก ก่อนการรวม เอกสารที่รวมแล้วถูกสร้างโดยเอนจินรวมแบบ object-graph ของ Pro ซึ่งกำหนดหมายเลขทุกอินพุตใหม่ให้อยู่ในพื้นที่อ็อบเจกต์ต่อเนื่องเดียว และปล่อยตารางอ้างอิงไขว้จริง จากนั้นเลเยอร์ Pro จึงเพิ่มการปรับปรุงที่ร้องขอ

SmartMergeConfig ควบคุมการปรับปรุง:

• การรวมบุ๊กมาร์ก แทรกรายการเค้าร่างหนึ่งรายการต่ออินพุตที่มีป้ายกำกับ โดยชี้ไปยังจุดเริ่มต้นของส่วนนั้นของอินพุต ซึ่งเป็นไปตามแบบจำลอง /Outlines ของ document catalog ใน ISO 32000-2:2020 §7.7.2
• การกำจัดหน้าซ้ำ ลบหน้าซ้ำที่เหมือนกันในระดับไบต์ข้ามอินพุต เปรียบเทียบด้วย content hash
• การเขียน link ใหม่ สแกนหา action GoTo ภายในเอาต์พุตที่รวมแล้ว

SmartMergeResult รายงานไบต์ที่รวมแล้วพร้อมสถิติ ได้แก่ จำนวนหน้าทั้งหมด จำนวนแหล่ง ขนาดเอาต์พุต บุ๊กมาร์กที่เพิ่ม หน้าซ้ำที่ลบ link ที่ตรวจพบ และป้ายกำกับอินพุตตามลำดับ

เหตุใดจึงทำงานเช่นนี้

การรวม PDF ไม่ใช่การต่อไบต์เข้าด้วยกัน อินพุตแต่ละตัวพกพาหมายเลขอ็อบเจกต์ ตารางอ้างอิงไขว้ และ page tree ของตนเอง ดังนั้นการต่อแบบไร้เดียงสาจึงโหลด ไม่ได้ในโปรแกรมอ่านที่เป็นไปตามข้อกำหนด SmartMerger จึงมอบหมายการประกอบ พื้นฐานให้เอนจิน object-graph ของ Pro (PdfSplitter::mergeDocuments()) ซึ่ง กำหนดหมายเลขทุกอินพุตใหม่ให้อยู่ในพื้นที่อ็อบเจกต์ต่อเนื่องเดียว สร้าง page tree เดียวขึ้นใหม่ และปล่อยตารางอ้างอิงไขว้จริงพร้อม byte offset ที่แท้จริง จากนั้น การปรับปรุงของ Pro ได้แก่ การรวมบุ๊กมาร์ก การกำจัดหน้าซ้ำ และการตรวจจับ link จึงวางทับบนเอาต์พุตที่ตรวจสอบแล้วนั้น แทนที่จะสร้างการประกอบขึ้นใหม่ การกำจัด หน้าซ้ำระดับทั้งเอกสารและการจัดการ link แบบตรวจจับเท่านั้นเป็นขอบเขตที่จงใจ กำหนดไว้ เพื่อให้การรวมเป็นแบบกำหนดผลแน่นอนและปลอดภัยต่ออินพุตที่ไม่น่าเชื่อถือ

ภูมิหลังการออกแบบ: กายวิภาคของไฟล์ PDF

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

• อินพุต รายการ MergeInput ที่ไม่ว่างเปล่า รายการว่างเปล่าจะยก InvalidArgumentException จำนวนอินพุตและขนาดไบต์ต่ออินพุตถูกจำกัด ด้วย SmartMergeConfig (maxInputs, maxBytesPerInput)
• เอาต์พุต SmartMergeResult isValid() เป็นจริงเมื่อเอาต์พุต เริ่มต้นด้วยส่วนหัว %PDF
• การรวมบุ๊กมาร์ก เพิ่มหนึ่งรายการต่ออินพุตที่มีป้ายกำกับไม่ว่างเปล่า เมื่อเปิดใช้งาน consolidateBookmarks
• การกำจัดหน้าซ้ำ เป็นแบบเลือกใช้ (deduplicatePages ค่าเริ่มต้นปิด) และ จับคู่ทั้งหน้าด้วย content hash ไม่ใช่หน้าที่คล้ายกันเชิงภาพ
• การเขียน link ใหม่ ในรุ่นปัจจุบันตรวจจับและนับ action GoTo ภายใน ไม่ได้ทำการ re-resolve ปลายทางข้ามเอกสารเต็มรูปแบบ ให้ถือ linksRewritten เป็นจำนวนการตรวจจับ
• ความเป็นแบบกำหนดผลแน่นอน สำหรับอินพุตและการกำหนดค่าที่เหมือนกัน กระแสไบต์ที่รวมแล้วจะเสถียร ภายใต้โปรไฟล์ความเป็นแบบกำหนดผลแน่นอน ที่จัดทำเอกสารไว้ของเอนจินรวมของ Pro

พื้นผิว public API

ชนิด	ประเภท	สมาชิกสำคัญ
NextPDF\Pro\Merge\SmartMerger	final class	__construct(?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null), merge(array $inputs, SmartMergeConfig $config = new SmartMergeConfig()): SmartMergeResult
NextPDF\Pro\Merge\MergeInput	final readonly class	__construct(string $pdfData, array $pageRanges = [], string $label = ''), hasPageRanges(): bool
NextPDF\Pro\Merge\SmartMergeConfig	final readonly class	__construct(bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000), default(), basic()
NextPDF\Pro\Merge\SmartMergeResult	final readonly class	string $pdfData, int $totalPages, int $sourceCount, int $bookmarksAdded, int $duplicatesRemoved, int $linksRewritten, array $inputLabels, isValid(): bool, hasOptimizations(): bool

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMerger;

$result = (new SmartMerger())->merge([
    new MergeInput(file_get_contents('cover.pdf'), label: 'Cover'),
    new MergeInput(file_get_contents('body.pdf'),  label: 'Body'),
]);

echo $result->totalPages, " pages, ",
     $result->bookmarksAdded, " bookmarks\n";

ตัวอย่างโค้ด — การใช้งานจริง

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMergeConfig;
use NextPDF\Pro\Merge\SmartMerger;

function assemblePacket(array $sections): string
{
    $inputs = [];
    foreach ($sections as $label => $bytes) {
        $inputs[] = new MergeInput($bytes, label: (string) $label);
    }

    $config = new SmartMergeConfig(
        consolidateBookmarks: true,
        deduplicatePages: true,
        rewriteLinks: false,
        maxInputs: 50,
    );

    $result = (new SmartMerger())->merge($inputs, $config);

    if (! $result->isValid()) {
        throw new RuntimeException('merge produced invalid output');
    }

    return $result->pdfData;
}

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

• อินพุตเดียวถือว่าถูกต้องและรวมเป็นสำเนาที่ถูกทำให้เป็นปกติของเอกสารนั้น
• การกำจัดหน้าซ้ำเปรียบเทียบเนื้อหาไบต์ทั้งหน้า หน้าที่ต่างกันเพียง เมทาดาทาหรือการกำหนดหมายเลขอ็อบเจกต์จะไม่ถูกถือว่าเป็นหน้าซ้ำ
• การเลือกช่วงหน้าบนอินพุตถูกใช้ก่อนการจัดลำดับการรวม
• linksRewritten เป็นจำนวน action ที่ตรวจพบ ไม่ใช่การรับประกันว่าทุก ปลายทาง link ข้ามเอกสารถูกชี้ใหม่

ประสิทธิภาพ

ต้นทุนถูกครอบงำโดยเอนจินรวมของ Pro และปรับขนาดตามไบต์อินพุตทั้งหมด และจำนวนหน้า การกำจัดหน้าซ้ำเพิ่ม content hash หนึ่งครั้งต่อหน้า ส่วน front-matter performance_budget คือการอ้างอิงต่อการรวมหนึ่งครั้ง

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

จำนวนอินพุตและขนาดต่ออินพุตถูกจำกัดด้วย SmartMergeConfig เพื่อจำกัด การใช้ทรัพยากรจนหมดจากอินพุตที่เป็นอันตราย การรวมไม่ดำเนินการสคริปต์ เอกสารที่ฝังไว้ ดูแบบจำลองความปลอดภัยของ Core สำหรับการเสริมความแข็งแกร่ง ในการแจงไบต์สตรีม

การเป็นไปตามข้อกำหนด

ข้ออ้าง	ข้อกำหนด	สถานะ
บุ๊กมาร์กที่รวมผ่าน /Outlines	ISO 32000-2:2020 §7.7.2	ตรวจสอบแล้ว (ชุดทดสอบหน่วย)
การกำจัดหน้าซ้ำด้วย content-hash	—	ตรวจสอบแล้ว (ชุดทดสอบหน่วย)
การ re-resolve link ข้ามเอกสารเต็มรูปแบบ	—	ไม่รองรับ (ตรวจจับเท่านั้น)

ทางเลือกสำรองของ Core

สำหรับการต่อท้ายพื้นฐานโดยไม่มีการรวมของ Pro NextPDF\Document\PdfMerger ของ Core แบบโอเพนซอร์สคือเส้นทางแบบสแตนด์อโลนที่รองรับ SmartMerger ไม่ได้มอบหมายงานให้มัน การรวมของ Pro ทำงานบนเอนจิน object-graph ของตัวเอง ดู /modules/core/document/

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

โมดูลนี้ทำการรวมเชิงโครงสร้าง ไม่ได้ทำการประกอบ legal-hold การปิดบัง หรือ การบรรจุห่วงโซ่การควบคุมหลักฐานเชิงพยานหลักฐาน สิ่งเหล่านั้นไม่ได้ มีให้ที่นี่

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

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

ดูเพิ่มเติม

• Merge — การอ้างอิงเชิงลึก
• Toc
• Diff
• แบบจำลองเอกสารของ Core