Perbandingan

Sekilas pandang

NextPDF\Pro\Diff membandingkan dua dokumen PDF dan melaporkan apa yang berubah. Jalur cepat menghasilkan diff teks yang selaras-halaman; jalur terstruktur menambahkan deteksi perubahan gambar dan metadata serta memformat hasilnya sebagai JSON atau HTML.

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 menggerbangi kelas-kelas Diff; kelas-kelas itu hadir setiap kali paket Pro terpasang.

Pemasangan

composer require nextpdf/pro:^3

Tinjauan konseptual

PdfDiffer::compare() mengekstrak teks per halaman dari setiap dokumen, membaginya menjadi baris, dan menjalankan Myers line diff per pasangan halaman, menghasilkan region yang ditambahkan, dihapus, dan dimodifikasi. Ekstraksi teks mengurai operator pemunculan-teks ISO 32000-2:2020 §9.4 (Tj, TJ, ').

StructuredDiffer membangun di atas itu: ia mengelompokkan region teks menjadi perubahan tingkat-paragraf, membandingkan gambar tertanam, membandingkan metadata, dan menghasilkan sebuah StructuredDiffResult dengan ringkasan agregat. DiffFormatter menserialisasi hasil tersebut ke string JSON atau fragmen laporan HTML.

Ketika pembaca PDF Artisan opsional terpasang, ekstraksi teks menggunakannya untuk konten yang akurat-per-halaman; jika tidak, fallback tingkat-byte terbatas memindai content stream secara langsung.

Mengapa bekerja seperti ini

Differ membandingkan teks dan struktur yang diekstrak, bukan piksel yang dirender. Perbandingan struktural bersifat deterministik, murah, dan memetakan ke perubahan editorial yang diperhatikan seorang peninjau. Diff piksel justru akan menandai derau antialiasing dan font-hinting sebagai konten. Karena PDF menyimpan glyph dan pemosisian, bukan karakter yang siap-dibaca, setiap perbandingan terlebih dahulu merekonstruksi teks dari content stream. Langkah ekstraksi itulah alasan pembaca Artisan menajamkan akurasi, alasan fallback FlateDecode terbatas menukar cakupan demi keamanan, dan alasan halaman hasil pindai nyaris tidak menghasilkan diff. Penyelarasan halaman tetap berbasis-indeks demi keterprediksian, sehingga halaman yang disisipkan terbaca sebagai pergeseran hilir yang jelas.

Latar belakang desain: Mengapa teks dalam PDF sebenarnya bukan teks.

Kontrak perilaku

• Input. Byte PDF mentah untuk sumber dan target. Buffer yang tidak diawali %PDF memunculkan InvalidArgumentException.
• Output (jalur cepat). DiffResult dengan daftar region added, removed, modified ditambah isIdentical(), hasDifferences(), totalChanges().
• Output (jalur terstruktur). StructuredDiffResult dengan diff paragraf, diff gambar, perubahan metadata, dan sebuah DiffSummary.
• Keluaran laporan. DiffFormatter memancarkan string JSON atau fragmen HTML. Ia tidak menghasilkan PDF redline berdampingan secara visual.
• Batas sumber daya. Ukuran content stream yang sudah didekompresi dibatasi untuk menjaga terhadap decompression bomb; pemindai tingkat-byte menghindari backtracking regex katastrofik pada input yang dibuat-buat.
• Determinisme. Untuk input yang identik, region diff dan keluaran terformat bersifat stabil.

Permukaan API publik

Tipe	Jenis	Anggota kunci
NextPDF\Pro\Diff\PdfDiffer	final class	static compare(string $sourcePdf, string $targetPdf): DiffResult, static compareTexts(array $sourcePages, array $targetPages): DiffResult, static extractText(string $contentStream): string
NextPDF\Pro\Diff\StructuredDiffer	final class	__construct(?ImageDiffer $imageDiffer = null, ?MetadataDiffer $metadataDiffer = null), compare(string $sourcePdf, string $targetPdf): StructuredDiffResult
NextPDF\Pro\Diff\DiffFormatter	final class	toJson(StructuredDiffResult $result): string, toHtml(StructuredDiffResult $result): string
NextPDF\Pro\Diff\DiffResult	final readonly class	array $added, array $removed, array $modified, isIdentical(): bool, hasDifferences(): bool, totalChanges(): int
NextPDF\Pro\Diff\StructuredDiffResult	final readonly class	diff teks, paragraf, gambar, perubahan metadata, ringkasan
NextPDF\Pro\Diff\DiffType	enum	Added, Removed, Modified, Unchanged

Contoh kode — Mulai cepat

<?php

declare(strict_types=1);

use NextPDF\Pro\Diff\PdfDiffer;

$diff = PdfDiffer::compare(
    file_get_contents('v1.pdf'),
    file_get_contents('v2.pdf'),
);

if ($diff->hasDifferences()) {
    echo $diff->totalChanges(), " text changes detected\n";
}

Contoh kode — Produksi

<?php

declare(strict_types=1);

use NextPDF\Pro\Diff\DiffFormatter;
use NextPDF\Pro\Diff\StructuredDiffer;

function reviewReport(string $oldPdf, string $newPdf): string
{
    $result = (new StructuredDiffer())->compare($oldPdf, $newPdf);

    // JSON for machine consumption; toHtml() for a review UI fragment.
    return (new DiffFormatter())->toJson($result);
}

Kasus tepi & jebakan

• Diff diselaraskan-halaman berdasarkan indeks. Menyisipkan halaman lebih awal menggeser semua halaman berikutnya dan melaporkan perubahan hilir yang besar — ini diharapkan untuk perbandingan yang diselaraskan-indeks.
• Perbandingan gambar mendeteksi gambar tertanam yang ditambahkan, dihapus, dan dimodifikasi; ia bukan diff-visual perseptual dan tidak merender piksel halaman.
• PDF hasil pindai yang hanya berupa gambar menghasilkan sedikit atau tanpa diff teks karena tidak ada OCR yang dilakukan.
• Tanpa pembaca Artisan opsional, ekstraksi menggunakan fallback terbatas; dokumen yang sangat terkompresi dapat menghasilkan cakupan teks yang berkurang.

Performa

Ekstraksi teks bersifat linear terhadap byte dokumen; Myers diff bersifat nyaris-linear untuk dokumen serupa dan kuadratik dalam kasus terburuk per pasangan halaman. Batas dekompresi membatasi memori. Lihat performance_budget.

Catatan keamanan

Fallback tingkat-byte menggunakan pemindaian berbasis strpos alih-alih regex tak terbatas untuk menghindari backtracking katastrofik pada PDF yang dibuat-buat, dan membatasi keluaran dekompresi. Diffing tidak mengeksekusi skrip tertanam. Lihat model keamanan Core.

Konformansi

Klaim	Klausa spec	Status
Operator teks Tj diurai untuk ekstraksi	ISO 32000-2:2020 §9.4	Terverifikasi (suite unit)
Operator teks array TJ diurai untuk ekstraksi	ISO 32000-2:2020 §9.4	Terverifikasi (suite unit)
Keluaran PDF redline berdampingan secara visual	—	Tidak didukung (hanya JSON/HTML)

Fallback / alternatif Core

Tidak ada padanan Core untuk perbandingan dokumen. Pembaca Artisan opsional meningkatkan akurasi ekstraksi saat terpasang tetapi tidak diwajibkan.

Catatan batas Enterprise

Ini adalah pendeteksi perubahan-konten. Ia bukan penganalisis perbedaan forensik dan tidak menghasilkan laporan pembuktian atau atribusi-pengubahan; urusan tersebut berada di luar cakupan modul ini.

Batas publikasi

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

Lihat juga

• Referensi Diff
• Converter
• Filter
• Merge