Pro sürüm

Diff — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF Pro diff modülünün (NextPDF\Pro\Diff) sözleşme düzeyindeki başvurusudur. Modül iki PDF belgesini karşılaştırır ve metin, görüntü ve meta veri değişikliklerini raporlar. PdfDiffer, sayfa hizalı bir Myers satır diff’i üretir. StructuredDiffer, paragraf gruplama, görüntü karşılaştırma ve meta veri karşılaştırma ekler. DiffFormatter, yapılandırılmış sonucu JSON’a veya bir HTML parçasına dizileştirir. Bu sayfa genel API’yi, gözlemlenebilir davranış sözleşmesini, kaynak sınırlarını ve hata biçimlerini belirtir. Göreve yönelik kurulum ve örnekler Diff yetenek sayfasında yer alır.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile sunulur ve Pro katmanlı bir lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve lisans edinin.

Hiçbir çalışma zamanı yetenek bayrağı bu modülü kapılamaz. Diff sınıfları, nextpdf/pro yüklü ve lisanslı olduğu her durumda kullanılabilir.

Genel API yüzeyi

Sembol	Parametreler	Varsayılan davranış	Döndürür	Şununla hata verir veya başarısız olur	Notlar
`PdfDiffer::compare()`	`string $sourcePdf`, `string $targetPdf`	Sayfa başına metni çıkarır, ardından kaynağın i. sayfasını hedefin i. sayfasıyla karşılaştırır	`DiffResult`	Bir arabellek `%PDF` başlığından yoksun olduğunda veya isteğe bağlı okuyucu ayrıştıramadığında `InvalidArgumentException`; bir kaynak sınırında `OverflowException`	Statik giriş noktası
`PdfDiffer::compareTexts()`	`array $sourcePages`, `array $targetPages` (her biri `list<string>`)	Çıkarımı atlayarak önceden çıkarılmış sayfa metinlerini karşılaştırır	`DiffResult`	Bir kaynak sınırında `OverflowException`	Statik; metin zaten mevcut olduğunda kullanın
`PdfDiffer::extractText()`	`string $contentStream`	Tek bir ham içerik akışından metin gösteren operatörleri ayrıştırır	`string`	— (hataya dayanıklı; ayrıştırılamayan giriş boş bir dize verir)	Statik
`StructuredDiffer::__construct()`	`?ImageDiffer $imageDiffer = null`, `?MetadataDiffer $metadataDiffer = null`	`null` argümanları varsayılan karşılaştırıcıları oluşturur	—	—	Test için kurucu enjeksiyonu
`StructuredDiffer::compare()`	`string $sourcePdf`, `string $targetPdf`	Metin, paragraf, görüntü ve meta veri karşılaştırmasını çalıştırır, ardından bir özet oluşturur	`StructuredDiffResult`	Metin yolundan `InvalidArgumentException` ve `OverflowException`’ı yayar	Tüm modül üzerinde düzenleyici
`DiffFormatter::toJson()`	`StructuredDiffResult $result`	Biçimlendirilmiş JSON belgesi	`string`	Kodlama başarısız olduğunda `JsonException`	—
`DiffFormatter::toHtml()`	`StructuredDiffResult $result`	Özet, paragraf ve meta veri bölümleri içeren HTML parçası; metin değerleri varlık kaçışıyla korunur	`string`	—	Yalnızca parça, tam belge değil
`DiffFormatter::toArray()`	`StructuredDiffResult $result`	`toJson()`’ı destekleyen dizileştirme dizisi	`array<string, mixed>`	—	Kararlı snake_case anahtarları
`ImageDiffer::diff()`	`string $sourcePdf`, `string $targetPdf`	Görüntü XObject’lerini karma değerine dönüştürür ve eklenen, kaldırılan ve değiştirilen görüntüleri raporlar	`list<ImageDiff>`	— (çözülemeyen yapılar hataya kapalı biçimde atlanır)	Kimlik, sayfa kovası artı nesne numarasıdır
`MetadataDiffer::diff()`	`string $sourcePdf`, `string $targetPdf`	Sekiz `/Info` alanını karşılaştırır (Title, Author, Subject, Keywords, Creator, Producer, CreationDate, ModDate)	`list<MetadataChange>`	— (uyumsuz girişte asla istisna fırlatmaz)	Değerler çözülmüş dizeler olarak karşılaştırılır
`DiffEngine::diff()`	`array $sourceLines`, `array $targetLines`, `int $pageIndex = 0`, `int $maxLines = 10000`	İki satır listesi üzerinde Myers satır diff’i	`list<DiffRegion>`	Birleşik satırlar `$maxLines`’ı aştığında veya düzenleme mesafesi bellek sınırlı üst sınırı aştığında `OverflowException`	Statik; tüm metin yolları için bölge üreticisi
`TextExtractor::fromContentStream()`	`string $contentStream`	Akışı belirteçlere ayırır ve metin durumu makinesini çalıştırır	`list<TextBlock>`	—	Statik
`TextExtractor::fromOperations()`	`array $operations` (`list<ContentStreamOp>`)	Önceden ayrıştırılmış işlemler üzerinde metin durumu makinesini çalıştırır	`list<TextBlock>`	—	Statik
`ContentStreamParser::parse()`	kurucu `string $data` alır	Operatörleri ve işlenenleri belirteçlere ayırır; sözlükleri ve yorumları atlar; hataya dayanıklı	`list<ContentStreamOp>`	—	Tanınmayan baytlar atlanır, asla ölümcül değildir
`ContentStreamOp`	`string $operator`, `list<mixed> $operands`	Salt okunur işlem değer nesnesi; `isTextOp()`, metinle ilgili operatörleri sınıflandırır	—	—	—
`DiffResult`	`list<DiffRegion> $regions`, `int $sourcePagesCount`, `int $targetPagesCount`	Bölgeleri `$added`, `$removed`, `$modified` içine gruplar; `isIdentical()`, `hasDifferences()`, `totalChanges()`’i açığa çıkarır	—	—	Salt okunur; `Unchanged` bölgeler yalnızca `$regions` içinde kalır
`StructuredDiffResult`	metin diff’i, paragraflar, görüntüler, meta veri değişiklikleri, özet	Toplam sonuç; `hasDifferences()`, `isIdentical()` özete devreder	—	—	Salt okunur
`DiffSummary`	kategori başına sayımlar artı sayfa sayımları	Metin, görüntü ve meta veri sayımları üzerinde `hasDifferences()` ve `totalChanges()`	—	—	Salt okunur
`DiffRegion`	`DiffType $type`, `string $text`, `int $pageIndex`, `int $lineIndex`, `?string $counterpartText = null`	Bir satır düzeyinde değişiklik	—	—	`$counterpartText`, sunulan motorda `null` kalır
`ParagraphDiff`	tür, metin, sayfa dizini, başlangıç/bitiş satırı, bölgeler	Bir sayfada ardışık aynı türdeki bölgeler; `lineCount()`	—	—	Salt okunur
`ImageDiff`	tür, sayfa dizini, kaynak karma, hedef karma, nesne kimliği	Bir görüntü değişikliği girdisi	—	—	Karma değerleri, eksik tarafta boş dizelerdir
`MetadataChange`	`string $field`, `?string $sourceValue`, `?string $targetValue`	Bir alan değişikliği; `isAdded()`, `isRemoved()`, `isModified()`	—	—	`null`, alanın mevcut olmadığı anlamına gelir
`TextBlock`	metin, x, y, yazı tipi adı, yazı tipi boyutu, satır dizini	Yaklaşık konumla çıkarılmış bir metin dizisi	—	—	Salt okunur
`DiffType`	enum: `Added`, `Removed`, `Modified`, `Unchanged`	Metin için dize destekli değişiklik sınıflandırması	—	—	Davranış sözleşmesindeki `Modified` notuna bakın
`ImageDiffType`	enum: `Added`, `Removed`, `Modified`, `Unchanged`	Görüntüler için dize destekli değişiklik sınıflandırması	—	—	—

Giriş noktası imzaları

public static function compare(string $sourcePdf, string $targetPdf): DiffResult

public static function compareTexts(array $sourcePages, array $targetPages): DiffResult

public static function extractText(string $contentStream): string

public function __construct(
    ?ImageDiffer $imageDiffer = null,
    ?MetadataDiffer $metadataDiffer = null,
)

public function compare(string $sourcePdf, string $targetPdf): StructuredDiffResult

public function toJson(StructuredDiffResult $result): string

public function toHtml(StructuredDiffResult $result): string

public function toArray(StructuredDiffResult $result): array

public static function diff(
    array $sourceLines,
    array $targetLines,
    int $pageIndex = 0,
    int $maxLines = self::MAX_DIFF_LINES,
): array

Davranış sözleşmesi

Sayfa hizalama ve satır diff’i

PdfDiffer::compare(), sayfa başına metni çıkarır, ardından kaynağın i. sayfasını hedefin i. sayfasıyla karşılaştırır. Sayfa sayıları farklı olduğunda, eksik taraf, fazla sayfalar için boş metin olarak ele alınır. Her sayfa çiftinde metin, satır sonlarında bölünür ve her sayfa için bir Myers satır diff’i çalışır. Motor Added, Removed ve Unchanged bölgeleri üretir. Değişen bir satır, bir Removed artı bir Added bölge olarak ortaya çıkar; sunulan motor asla Modified metin bölgeleri üretmez. DiffResult kurucusu genel olduğundan, Modified durumu ve DiffResult::$modified kovası, çağıran tarafından oluşturulan sonuçlara hizmet eder. totalChanges(), eklenen, kaldırılan ve değiştirilen bölgeleri sayar; değişmeyen bölgeler hariç tutulur.

Çıkarım yolları

Çıkarımın iki yolu vardır:

İsteğe bağlı Artisan okuyucu mevcut. İsteğe bağlı NextPDF\Parser\PdfReader sınıfı yüklendiğinde, sayfa içerik akışları, sayfaya doğru metin için bunun aracılığıyla okunur. Trailer’ın sayfa sayısı döngüyü yönlendirir. Okunamayan bir sayfa, karşılaştırmayı iptal etmek yerine boş metin katkısı yapar.
Yedek. Sınırlı bir bayt düzeyi tarayıcı, stream/endstream çiftlerini strpos ile bulur, FlateDecode verisini sabit 50 MB çıktı üst sınırıyla açar ve akış sözlüğü /DecodeParms aracılığıyla bir tane istediğinde ISO 32000-2:2020 §7.4.4.4 uyarınca bir PNG öngörücüsünü ters filtreler. Hatalı biçimlendirilmiş veya desteklenmeyen bir öngörücü, çözülmüş baytları değiştirmeden bırakır. Yedek, kurtarılan tüm metni tek bir sayfa kovasında birleştirir, bu nedenle sayfa düzeyinde hizalama yalnızca okuyucu yolunda sayfaya doğrudur.

Her iki yol da §9.4 metin gösteren operatörleri Tj, TJ ve '’yi ayrıştırır. Durum makinesi BT/ET, Tm (yalnızca köken), Td/TD, T* ve Tf’yi izler.

Yapılandırılmış karşılaştırma

StructuredDiffer::compare(), metin diff’ini çalıştırır, aynı sayfadaki ardışık aynı türdeki bölgeleri paragraflar hâlinde gruplar (değişmeyen diziler dâhil), ardından görüntü ve meta veri karşılaştırmasını çalıştırır ve bir DiffSummary derler. Özet paragraf sayımları yalnızca eklenen, kaldırılan ve değiştirilen paragrafları kapsar.

Görüntü karşılaştırması, PDF nesnelerini yapısal olarak sıralar. Bir akış gövdesinin kapsamı, §7.3.8.2 uyarınca /Length girdisiyle yönetilir, bu nedenle yalnızca nesne söz dizimine benzeyen ikili baytlar asla hayalet nesne olarak kaydedilmez. Sıkıştırılmış nesne akışları (/Type /ObjStm), içlerine yerleştirilmiş görüntü XObject’leri görünür olsun diye §7.5.7 uyarınca çözülür. Algılanan her görüntü, kriptografik olmayan xxh128 işleviyle içerik karmasına dönüştürülür; kimlik, sayfa kovası ve nesne numarasının çiftidir. Akış sırasında sahip sayfası olmayan görüntüler sayfa 0’a atfedilir.

Meta veri karşılaştırması, mümkün olduğunda gerçek /Info sözlüğünü trailer aracılığıyla çözer, böylece bir içerik akışındaki sahte bir alan belirteci belge meta verisiyle karıştırılmaz. Alan değerleri PDF dizeleri olarak çözülür: §7.3.4.2 uyarınca değişmez biçim ve §7.3.4.3 uyarınca onaltılık biçim. Çözülebilir bir trailer olmadan, arama tüm girişe geri döner. Tarihler, ayrıştırılmış zaman damgaları olarak değil, çözülmüş dizeler olarak karşılaştırılır.

Rapor çıktısı

DiffFormatter::toJson(), biçimlendirilmiş JSON döndürür ve JSON_THROW_ON_ERROR ile kodlar, böylece bir kodlama hatası false döndürmek yerine JsonException fırlatır. toHtml(), bir <div class="nextpdf-diff"> parçası döndürür; paragraf metni ve meta veri değerleri HTML varlık kaçışından geçer. Yan yana görsel bir kırmızı çizgi (redline) PDF çıktısı yoktur. Aynı girişler için bölgeler ve biçimlendirilmiş çıktı belirlenimcidir.

Uç durumlar ve hata biçimleri

Sayfa hizalama konumsaldır. Tek bir eklenen veya silinen sayfa, sonraki tüm sayfaların hizalamasını kaydırır ve alt akış değişiklik sayımlarını şişirir.
Yedek çıkarım yolunda, tüm metin sayfa dizini 0’a düşer. Okuyucuyla çıkarılmış bir belgeyi, yedek yolundan gelen beklentilere karşı karşılaştırmak farklı sayfa atfı verir.
%PDF ile başlamayan bir kaynak veya hedef arabellek, herhangi bir karşılaştırmadan önce InvalidArgumentException ile başarısız olur.
Bir sayfa çiftinde 10,000’den fazla birleşik satır, OverflowException ile başarısız olur (satır sayısı sınırı).
Çok az satır paylaşan iki sayfa metni, Myers düzenleme mesafesi bellek sınırlı üst sınırı aştığında OverflowException ile başarısız olur. Meşru düzeltmeler çoğu satırı paylaşır ve etkilenmez; kötü niyetli düşük ortaklık girişleri sınırı tetikler.
50 MB’den büyük açılmış yedek akış çıktısı, OverflowException ile başarısız olur (sıkıştırma bombası sınırı). Tarayıcı, sınırsız regex değil, strpos kullanır, bu nedenle özenle hazırlanmış giriş felaket niteliğinde geri izlemeyi tetikleyemez.
" metin gösteren operatörü belirteçlere ayrılır ancak 3.1.0’da hiçbir metin bloğu üretmez; yalnızca " aracılığıyla gösterilen metin diff’e katılmaz.
Taranmış, yalnızca görüntü içeren PDF’ler çok az metin diff’i üretir veya hiç üretmez. Hiçbir OCR çalışmaz.
Görüntü değişikliği algılama, algısal değil, yapısaldır. Sayfaları rasterleştirmez ve aynı piksellerle yeniden kodlanmış bir görüntü, baytları farklı olduğunda değiştirilmiş olarak raporlanır.
Düzeltmeler arasında sayfa kovası veya nesne numarası değişen bir görüntü, değiştirilmiş olarak değil, bir kaldırılan-artı-eklenen çift olarak raporlanır.
FlateDecode dışındaki filtrelerle sıkıştırılmış nesne akışları, hataya kapalı biçimde atlanır; üye görüntüleri karşılaştırılmaz.
Bu modülde hiçbir kriptografik işlem gerçekleşmez, bu nedenle FIPS moduna özgü bir davranış yoktur. Görüntü karması yalnızca değişiklik algılama içindir ve hiçbir bütünlük veya kanıt ağırlığı taşımaz.

Uygunluk

İddia	Standart	Madde
`Tj` ve `TJ` metin gösteren operatörleri çıkarım için ayrıştırılır	ISO 32000-2:2020	§9.4
Yedek akış verisi, `stream` anahtar sözcüğünü izleyen CRLF veya LF’den sonra başlar	ISO 32000-2:2020	§7.3.8.1
Görüntü tarama akış kapsamları, sözlük `/Length` girdisiyle yönetilir	ISO 32000-2:2020	§7.3.8.2
Nesne akışı üyeleri, `/N` çift tablosu ve `/First` uzaklığı aracılığıyla bulunur	ISO 32000-2:2020	§7.5.7
PNG öngörücü tersine çevirme, `/DecodeParms` `Predictor` parametresini izler	ISO 32000-2:2020	§7.4.4.4
Meta veri değerleri, değişmez ve onaltılık dize biçimlerini çözer	ISO 32000-2:2020	§7.3.4.2, §7.3.4.3
Yan yana görsel kırmızı çizgi (redline) PDF çıktısı	—	Desteklenmiyor (yalnızca JSON/HTML)

Tüm maddeler açımlanmıştır; NextPDF normatif metni çoğaltmaz. Bunlar sertifikalar değil, yetenek beyanlarıdır; NextPDF hiçbir sertifikaya sahip değildir ve hiçbirini vermez. Metin kurtarma, satır metnini metin gösteren operatörlerden yeniden oluşturur. Tam §9.4 metin durumu makinesini çalıştırmaz, bu nedenle diff, geometri düzeyinde değil, içerik düzeyindedir.

Geliştirme notları

Pro paketi içinde kullanılabilirlik: PdfDiffer, DiffEngine, TextExtractor ve bunların değer nesneleri 1.8.0’dan beri; StructuredDiffer, DiffFormatter, ImageDiffer, MetadataDiffer ve bunlarınkiler 2.2.0’dan beri. Tümü nextpdf/pro 3.1.0’da günceldir.
Sayfa metni zaten mevcut olduğunda PdfDiffer::compareTexts()’i tercih edin; çıkarımı ve onun hata biçimlerini tamamen atlar.
İsteğe bağlı Artisan okuyucu, çıkarım doğruluğunu ve sayfa atfını iyileştirir. Çalışma zamanında algılanır ve asla gerekli değildir.
Güvenilmeyen girişi karşılaştırırken OverflowException’ı yakalayın; sınırlar geçici hatalar değil, kasıtlı hataya kapalı reddetmelerdir.
DiffFormatter::toHtml(), sınıf adları (diff-added, diff-removed, diff-modified, diff-unchanged) yayar ancak hiçbir stil sayfası vermez; kendi CSS’inizi sağlayın.
Metin yolunu görüntü ve meta veri taramasından yalıtmak için testlerde StructuredDiffer’ı taslak karşılaştırıcılarla oluşturun.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dâhili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışındadır.

Ayrıca bkz.

Diff (yetenek) — kurulum, hızlı başlangıç ve üretim örnekleri.
Converter — Derinlemesine başvuru
Filter — Derinlemesine başvuru