Merge — Referensi Mendalam

Sekilas pandang

Halaman ini adalah referensi tingkat kontrak untuk modul NextPDF Pro Merge, NextPDF\Pro\Merge. SmartMerger merakit beberapa dokumen masukan menjadi satu dan menerapkan penyempurnaan Pro: pohon bookmark terkonsolidasi dari label per-masukan, deduplikasi seluruh-dokumen, pemilihan rentang halaman per-masukan, dan deteksi tautan internal. SemanticSplitter adalah entry point pemisahan sadar-struktur pendampingnya. Halaman ini menyatakan API publik, kontrak perilaku yang dapat diamati, batas sumber daya, dan mode kegagalan. Penyiapan berorientasi tugas dan contoh tersedia di halaman kapabilitas Merge.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tingkat-Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag kapabilitas runtime yang menggerbang modul ini. Kelas-kelas Merge dapat digunakan setiap kali nextpdf/pro terpasang dan berlisensi.

Permukaan API publik

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
SmartMerger::__construct()	?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null	Menerima dan mengabaikan core merger lawas; splitter null mengonstruksi splitter Pro default	—	—	$coreMerger dipertahankan hanya untuk konstruksi yang kompatibel-mundur
SmartMerger::merge()	list<MergeInput> $inputs, SmartMergeConfig $config = new SmartMergeConfig()	Mereduksi rentang halaman, mendeduplikasi seluruh masukan, mendelegasikan perakitan dasar, lalu menyisipkan bookmark dan menghitung tautan sesuai config	SmartMergeResult	InvalidArgumentException pada daftar masukan kosong; OverflowException ketika jumlah masukan melampaui maxInputs atau sebuah masukan melampaui maxBytesPerInput	Satu-satunya entry point merge
MergeInput::__construct()	string $pdfData, list<PageRange> $pageRanges = [], string $label = ''	Value object; $pageRanges kosong memilih semua halaman	—	—	Readonly
MergeInput::hasPageRanges()	—	True ketika masukan membawa setidaknya satu rentang halaman	bool	—	—
SmartMergeConfig::__construct()	bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000	Value object yang menyimpan sakelar penyempurnaan dan batas sumber daya	—	—	Readonly; deduplikasi bersifat opt-in
SmartMergeConfig::default()	—	Bookmark dan pemindaian tautan aktif, deduplikasi nonaktif	self	—	Static factory
SmartMergeConfig::basic()	—	Semua penyempurnaan nonaktif; hanya penggabungan dasar	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 = []	Pembawa readonly untuk byte hasil merge dan statistik konsolidasi	—	—	Readonly
SmartMergeResult::isValid()	—	True ketika keluaran diawali dengan header %PDF	bool	—	Hanya pemeriksaan header
SmartMergeResult::hasOptimizations()	—	True ketika ada duplikat yang dihapus atau ada tautan yang dihitung	bool	—	—
SemanticSplitter::__construct()	?PdfSplitter $splitter = null	Argumen null mengonstruksi splitter Pro default	—	—	Injeksi konstruktor untuk pengujian
SemanticSplitter::splitByStructure()	string $pdfData, float $headingFontThreshold = 14.0	Mendeteksi operator Tf berukuran heading sebagai awal bagian dan memisahkan pada batas-batas tersebut; tanpa struktur terdeteksi mengembalikan satu bagian seluruh-dokumen	SplitResult	InvalidArgumentException ketika buffer kosong atau tidak memiliki header %PDF; OverflowException ketika masukan melampaui 100 MB	Jatuh kembali ke pemisahan rentang halaman Core

Tanda tangan entry point

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

Kontrak perilaku

Pipeline merge

SmartMerger::merge() menjalankan pipeline tetap, yang diamati secara eksternal sebagai berikut.

1. Daftar masukan kosong memunculkan InvalidArgumentException. Jumlah masukan kemudian dibatasi oleh maxInputs; kelebihan memunculkan OverflowException.
2. Setiap masukan diperiksa ukurannya terhadap maxBytesPerInput sebelum digunakan. Ketika masukan mendeklarasikan rentang halaman, ia terlebih dahulu direduksi menjadi halaman terpilih melalui splitter Pro, lalu hanya menyumbang halaman-halaman itu.
3. Ketika deduplicatePages diaktifkan, seluruh string byte tiap dokumen masukan di-fingerprint dengan fungsi non-kriptografis xxh128. Masukan yang byte-nya persis sama dengan masukan sebelumnya akan dibuang. Deduplikasi bersifat seluruh-dokumen dan persis-byte.
4. Perakitan dasar mendelegasikan ke mesin Pro PdfSplitter::mergeDocuments(), yang menomori ulang setiap masukan ke dalam satu ruang objek berdampingan dan memancarkan cross-reference table nyata.
5. Konsolidasi bookmark diterapkan ketika consolidateBookmarks diaktifkan dan setidaknya satu masukan membawa label tidak-kosong. Sebuah dictionary /Outlines minimal disisipkan, ditautkan dari document catalog, dengan satu entri outline per masukan dalam urutan merge.
6. Ketika rewriteLinks diaktifkan, keluaran hasil merge dipindai untuk aksi /S /GoTo dan hitungannya dilaporkan.

Statistik hasil

SmartMergeResult melaporkan byte hasil merge beserta statistik. totalPages berasal dari merge dasar. sourceCount adalah jumlah masukan asli, diambil sebelum deduplikasi. mergedSize adalah panjang byte keluaran. bookmarksAdded hanya menghitung masukan yang menyediakan label tidak-kosong. duplicatesRemoved menghitung seluruh masukan yang dibuang. linksRewritten adalah hitungan GoTo yang terdeteksi. inputLabels mendaftar label yang teresolusi dalam urutan merge. isValid() memeriksa header %PDF; hasOptimizations() bernilai true ketika ada duplikat yang dihapus atau ada tautan yang dihitung.

Judul bookmark

Setiap entri outline membawa label masukan sebagai /Title, di-escape sebagai PDF literal string sesuai ISO 32000-2:2020 §7.3.4.2. Reverse solidus digandakan terlebih dahulu, tanda kurung di-escape, byte kontrol bernama memakai sekuens yang didefinisikannya, dan byte non-cetak yang tersisa menjadi escape oktal tiga-digit. Karena itu label yang bermusuhan tidak dapat men-desinkronkan delimiter literal-string atau menyuntikkan struktur objek. Masukan dengan label kosong menerima judul placeholder Document N, berindeks-satu.

Perakitan dasar

Core PdfMerger::merge() lawas adalah stub fail-closed yang disengaja pada rilis ini; ia tidak pernah dipanggil oleh SmartMerger. Merge dasar justru berjalan melalui Pro PdfSplitter::mergeDocuments(), sehingga berkas hasil merge membawa cross-reference table yang akurat-byte dengan satu entri per objek tak-langsung sesuai ISO 32000-2:2020 §7.5.4. Determinisme mengikuti profil terdokumentasi splitter Pro: masukan dan konfigurasi identik menghasilkan aliran byte yang stabil.

Pemisahan sadar-struktur

SemanticSplitter::splitByStructure() memindai content stream halaman untuk operator set-font Tf pada atau di atas headingFontThreshold (default 14.0) dan memperlakukan setiap halaman semacam itu sebagai awal bagian. Batas-batas dikonversi menjadi rentang halaman dan didelegasikan ke Pro PdfSplitter::split(). Ketika tidak ada batas terdeteksi, seluruh dokumen dikembalikan sebagai satu bagian tunggal. Masukan harus diawali dengan %PDF dan tetap dalam batas 100 MB.

Kasus tepi & mode kegagalan

• Daftar masukan kosong gagal dengan InvalidArgumentException sebelum perakitan apa pun.
• Jumlah masukan di atas maxInputs (default 100), atau masukan mana pun di atas maxBytesPerInput (default 100 MB), gagal dengan OverflowException. Kedua batas adalah penolakan fail-closed yang disengaja, bukan kesalahan sementara.
• Deduplikasi bersifat seluruh-dokumen dan persis-byte. Dua masukan yang merender identik tetapi berbeda pada byte mana pun keduanya dipertahankan, dan duplicatesRemoved menghitung seluruh masukan yang dibuang meskipun nama deduplicatePages berorientasi halaman.
• sourceCount mencerminkan jumlah masukan asli, bukan jumlah dokumen setelah deduplikasi.
• Konsolidasi bookmark hanya terpicu ketika setidaknya satu masukan memiliki label tidak-kosong. Dengan consolidateBookmarks bernilai true tetapi setiap label kosong, tidak ada objek /Outlines yang ditulis.
• Entri outline yang disisipkan membawa judul dan tautan pohon /Parent, /Prev, /Next; entri tersebut tidak menyematkan tujuan /Dest eksplisit pada rilis ini.
• Penulisan-ulang tautan hanya menghitung aksi /S /GoTo; ia tidak menunjuk-ulang tujuan di seluruh objek yang dinomori ulang. Perlakukan linksRewritten sebagai hitungan deteksi.
• Deteksi SemanticSplitter bersifat leksikal. Ia berpatokan pada operator ukuran-font Tf, sehingga halaman hanya-gambar atau yang dikodekan secara tidak lazim tidak menghasilkan batas dan mengembalikan satu bagian seluruh-dokumen tunggal.

Perilaku mode FIPS

Tidak ada operasi kriptografis yang terjadi di modul ini, sehingga tidak ada perilaku spesifik mode FIPS. Fingerprint konten xxh128 yang dipakai untuk deduplikasi adalah hash deteksi-perubahan non-kriptografis dan tidak membawa bobot integritas atau pembuktian.

Kesesuaian

Klaim	Standar	Klausa
Bookmark terkonsolidasi ditulis sebagai dictionary /Outlines yang ditautkan dari document catalog	ISO 32000-2:2020	§7.7.2
Merge dasar memancarkan cross-reference table yang akurat-byte untuk setiap objek tak-langsung	ISO 32000-2:2020	§7.5.4
Judul entri outline di-escape sebagai PDF literal string, dengan penanganan backslash dan tanda kurung	ISO 32000-2:2020	§7.3.4.2
Resolusi-ulang tautan lintas-dokumen penuh	—	Tidak didukung (hanya deteksi GoTo)
Tujuan outline eksplisit per-bagian	—	Tidak dipancarkan pada rilis ini

Semua klausa diparafrasekan; NextPDF tidak mereproduksi teks normatif. Ini adalah pernyataan kapabilitas, bukan sertifikasi; NextPDF tidak memegang sertifikasi dan tidak memberikan sertifikasi apa pun.

Catatan pengembangan

• Ketersediaan dalam paket Pro: SmartMerger, MergeInput, SmartMergeConfig, SmartMergeResult, dan SemanticSplitter sejak 2.2.0. Semuanya current di nextpdf/pro 3.1.0.
• Merge dasar mendelegasikan ke Pro PdfSplitter::mergeDocuments(). Core PdfMerger::merge() lawas adalah stub fail-closed pada rilis ini dan tidak pernah dipanggil.
• Aktifkan deduplicatePages hanya ketika masukan mungkin merupakan dokumen utuh yang identik-byte; ia tidak menciutkan salinan nyaris-duplikat atau yang dikodekan ulang.
• Gunakan SmartMergeConfig::basic() untuk penggabungan murni dan ::default() untuk bookmark plus pemindaian tautan.
• Tangkap OverflowException saat me-merge masukan tak-tepercaya; batas jumlah dan ukuran adalah penolakan yang disengaja.
• Lebih baik gunakan Pro PdfSplitter secara langsung untuk pemisahan rentang halaman sederhana; gunakan SemanticSplitter hanya ketika penseksian berbasis-heading diperlukan.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Merge (kapabilitas) — instalasi, mulai cepat, dan contoh produksi.
• Toc — Referensi Mendalam
• Diff — Referensi Mendalam
• Document — Referensi Mendalam — splitter Pro dan mesin merge dasar.