Merge

Sekilas pandang

NextPDF\Pro\Merge\SmartMerger menggabungkan beberapa PDF menjadi satu, lalu menerapkan peningkatan Pro: pohon bookmark terkonsolidasi dari label per-input, deduplikasi halaman berbasis content-hash, dan pemilihan rentang halaman per-input. Perakitan dokumen dasar berjalan melalui mesin penggabungan object-graph Pro. Ia menomori ulang setiap input ke dalam satu ruang objek dan menulis tabel cross-reference yang nyata.

Ketersediaan & lisensi

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

Kelas Merge tersedia kapan pun paket Pro terpasang. Tidak ada flag kapabilitas runtime yang menggerbang modul ini.

Pemasangan

composer require nextpdf/pro:^3

Tinjauan konseptual

SmartMerger menerima daftar value object MergeInput. Setiap input membawa byte PDF sumber, daftar rentang halaman opsional, dan label opsional. Input dengan rentang halaman direduksi menjadi halaman terpilih sebelum penggabungan. Dokumen gabungan dihasilkan oleh mesin penggabungan object-graph Pro, yang menomori ulang setiap input ke dalam satu ruang objek yang berdampingan dan memancarkan tabel cross-reference yang nyata; lapisan Pro kemudian menambahkan peningkatan yang diminta.

SmartMergeConfig mengendalikan peningkatan:

• Konsolidasi bookmark menyisipkan satu entri outline per input berlabel, yang menunjuk ke awal bagian input tersebut. Ini mengikuti model /Outlines document catalog dalam ISO 32000-2:2020 §7.7.2.
• Deduplikasi halaman menghapus halaman duplikat yang byte-identik di seluruh input, dibandingkan berdasarkan content hash.
• Penulisan ulang tautan memindai aksi GoTo internal dalam keluaran gabungan.

SmartMergeResult melaporkan byte hasil gabungan ditambah statistik: total halaman, jumlah sumber, ukuran keluaran, bookmark yang ditambahkan, duplikat yang dihapus, tautan yang terdeteksi, dan label input yang terurut.

Mengapa cara kerjanya begini

Menggabungkan PDF bukanlah konkatenasi byte: setiap input membawa nomor objek, tabel cross-reference, dan page tree-nya sendiri, sehingga penyambungan naif tidak dapat dimuat di pembaca yang konform mana pun. Oleh karena itu SmartMerger mendelegasikan perakitan dasar ke mesin object-graph Pro (PdfSplitter::mergeDocuments()), yang menomori ulang setiap input ke dalam satu ruang objek yang berdampingan, membangun ulang satu page tree, dan memancarkan tabel cross-reference yang nyata dengan offset byte yang sebenarnya. Peningkatan Pro — konsolidasi bookmark, deduplikasi, dan deteksi tautan — kemudian dilapiskan pada keluaran terverifikasi tersebut alih-alih mengimplementasikan ulang perakitan. Deduplikasi seluruh-dokumen dan penanganan tautan hanya-deteksi adalah batas cakupan yang disengaja untuk menjaga penggabungan tetap deterministik dan aman terhadap input tidak tepercaya.

Latar belakang desain: Anatomi berkas PDF.

Kontrak perilaku

• Input. Daftar MergeInput yang tidak kosong. Daftar kosong memunculkan InvalidArgumentException. Jumlah input dan ukuran byte per-input dibatasi oleh SmartMergeConfig (maxInputs, maxBytesPerInput).
• Keluaran. Sebuah SmartMergeResult. isValid() bernilai true ketika keluaran diawali dengan header %PDF.
• Konsolidasi bookmark menambahkan satu entri per input yang memiliki label tidak kosong, ketika consolidateBookmarks diaktifkan.
• Deduplikasi bersifat opt-in (deduplicatePages, baku nonaktif) dan mencocokkan halaman utuh berdasarkan content hash, bukan halaman yang mirip secara visual.
• Penulisan ulang tautan dalam rilis saat ini mendeteksi dan menghitung aksi GoTo internal; ia tidak melakukan resolusi-ulang destinasi lintas-dokumen penuh. Perlakukan linksRewritten sebagai jumlah deteksi.
• Determinisme. Untuk input dan konfigurasi yang identik, stream byte gabungan bersifat stabil, tunduk pada profil determinisme terdokumentasi mesin penggabungan Pro.

Permukaan API publik

Tipe	Jenis	Anggota utama
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

Contoh kode — Mulai cepat

<?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";

Contoh kode — Produksi

<?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;
}

Kasus tepi & jebakan

• Satu input valid dan tergabung menjadi salinan ternormalisasi dari dokumen tersebut.
• Deduplikasi membandingkan konten byte halaman-utuh; halaman yang berbeda hanya pada metadata atau penomoran objek tidak diperlakukan sebagai duplikat.
• Pemilihan rentang halaman pada sebuah input diterapkan sebelum pengurutan penggabungan.
• linksRewritten adalah jumlah aksi yang terdeteksi, bukan jaminan bahwa setiap target tautan lintas-dokumen ditunjuk-ulang.

Kinerja

Biaya didominasi oleh mesin penggabungan Pro dan berskala dengan total byte input dan jumlah halaman. Deduplikasi menambahkan satu content hash per halaman. Front-matter performance_budget adalah acuan per-penggabungan.

Catatan keamanan

Jumlah input dan ukuran per-input dibatasi oleh SmartMergeConfig untuk membatasi penghabisan sumber daya dari input yang berniat jahat. Penggabungan tidak mengeksekusi skrip dokumen tertanam. Lihat model keamanan Core untuk pengerasan penguraian stream-byte.

Kesesuaian

Klaim	Klausa spek	Status
Bookmark terkonsolidasi via /Outlines	ISO 32000-2:2020 §7.7.2	Verified (unit suite)
Deduplikasi halaman berbasis content-hash	—	Verified (unit suite)
Resolusi-ulang tautan lintas-dokumen penuh	—	Not supported (detection only)

Fallback / alternatif Core

Untuk konkatenasi dasar tanpa konsolidasi Pro, NextPDF\Document\PdfMerger Core sumber terbuka adalah jalur mandiri yang didukung. SmartMerger tidak mendelegasikan kepadanya; penggabungan Pro berjalan pada mesin object-graph-nya sendiri. Lihat /modules/core/document/.

Catatan batas Enterprise

Modul ini melakukan penggabungan struktural. Ia tidak melakukan perakitan legal-hold, penyamaran, atau pengemasan chain-of-custody pembuktian; semua itu tidak disediakan di sini.

Batas publikasi

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

Lihat juga

• Merge — Referensi Mendalam
• Toc
• Diff
• Model dokumen Core