Pro sürüm

Karşılaştırma

Bir bakışta

NextPDF\Pro\Diff, iki PDF belgesini karşılaştırır ve neyin değiştiğini raporlar. Hızlı yol, sayfa hizalı bir metin farkı üretir; yapılandırılmış yol, görüntü ve meta veri değişikliği algılaması ekler ve sonucu JSON veya HTML olarak biçimlendirir.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) içinde sunulur ve bir Pro katmanı 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 bir lisans edinin.

Hiçbir çalışma zamanı yetenek bayrağı Diff sınıflarını kapılamaz; Pro paketi yüklendiğinde her zaman mevcutturlar.

Kurulum

composer require nextpdf/pro:^3

Kavramsal genel bakış

PdfDiffer::compare(), her belgeden sayfa başına metni çıkarır, onu satırlara böler ve sayfa çifti başına bir Myers satır farkı çalıştırarak eklenen, kaldırılan ve değiştirilen bölgeleri üretir. Metin çıkarımı, ISO 32000-2:2020 §9.4 metin gösterme operatörlerini (Tj, TJ, ') ayrıştırır.

StructuredDiffer, bunun üzerine kurulur: metin bölgelerini paragraf düzeyinde değişiklikler hâlinde gruplar, gömülü görüntüleri karşılaştırır, meta veriyi karşılaştırır ve bütünleşik bir özetle birlikte bir StructuredDiffResult üretir. DiffFormatter, bu sonucu bir JSON dizesine veya bir HTML rapor parçasına serileştirir.

İsteğe bağlı Artisan PDF okuyucusu yüklü olduğunda, metin çıkarımı sayfa düzeyinde doğru içerik için onu kullanır; aksi hâlde, sınırlı bir bayt düzeyinde geri dönüş, içerik akışlarını doğrudan tarar.

Neden bu şekilde çalışır

Fark alıcı, işlenmiş pikselleri değil, çıkarılan metni ve yapıyı karşılaştırır. Yapısal bir karşılaştırma belirlenimci ve ucuzdur ve bir incelemecinin önemsediği editoryal değişikliklerle eşleşir. Bir piksel farkı ise kenar yumuşatma ve yazı tipi ipucu gürültüsünü içerik olarak işaretlerdi. Bir PDF, okumaya hazır karakterleri değil, glifleri ve konumlandırmayı depoladığından, her karşılaştırma önce içerik akışından metni yeniden oluşturur. Bu çıkarım adımı, Artisan okuyucusunun doğruluğu neden keskinleştirdiğini, sınırlı FlateDecode geri dönüşünün kapsamı neden güvenlik için takas ettiğini ve taranmış sayfaların neden pek fark üretmediğini açıklar. Sayfa hizalaması, öngörülebilirlik için dizin tabanlı kalır; böylece eklenen bir sayfa, net bir aşağı akış kayması olarak okunur.

Tasarım arka planı: Bir PDF’teki metin neden gerçekten metin değildir.

Davranış sözleşmesi

Girdi. Kaynak ve hedef için ham PDF baytları. %PDF ile başlamayan bir arabellek, InvalidArgumentException oluşturur.
Çıktı (hızlı yol). added, removed, modified bölge listeleriyle birlikte isIdentical(), hasDifferences(), totalChanges() içeren bir DiffResult.
Çıktı (yapılandırılmış yol). Paragraf farkları, görüntü farkları, meta veri değişiklikleri ve bir DiffSummary içeren bir StructuredDiffResult.
Rapor çıktısı. DiffFormatter, bir JSON dizesi veya bir HTML parçası yayar. Görsel, yan yana bir kırmızı çizgili PDF üretmez.
Kaynak sınırları. Açma bombalarına karşı korumak için açılmış içerik akışı boyutu sınırlandırılır; bayt düzeyindeki tarayıcı, hazırlanmış girdide felaket düzeyinde regex geri izlemesinden kaçınır.
Belirlenimcilik. Aynı girdiler için fark bölgeleri ve biçimlendirilmiş çıktı kararlıdır.

Genel API yüzeyi

Tür	Çeşit	Temel üyeler
`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`	metin farkı, paragraflar, görüntüler, meta veri değişiklikleri, özet
`NextPDF\Pro\Diff\DiffType`	`enum`	`Added`, `Removed`, `Modified`, `Unchanged`

Kod örneği — Hızlı başlangıç

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

Kod örneği — Üretim

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

Uç durumlar ve dikkat edilmesi gerekenler

Fark, dizine göre sayfa hizalıdır. Erken bir sayfa eklemek tüm sonraki sayfaları kaydırır ve büyük aşağı akış değişiklikleri raporlar — bu, dizine hizalı bir karşılaştırma için beklenen durumdur.
Görüntü karşılaştırması, eklenen, kaldırılan ve değiştirilen gömülü görüntüleri algılar; algısal bir görsel fark değildir ve sayfaları piksel düzeyinde işlemez.
Taranmış, yalnızca görüntü içeren PDF’ler, hiçbir OCR yapılmadığı için pek az veya hiç metin farkı üretmez.
İsteğe bağlı Artisan okuyucusu olmadan çıkarım, sınırlı geri dönüşü kullanır; yoğun sıkıştırılmış belgeler azaltılmış metin kapsamı verebilir.

Performans

Metin çıkarımı, belge baytlarında doğrusaldır; Myers farkı, benzer belgeler için neredeyse doğrusaldır ve en kötü durumda sayfa çifti başına ikinci derecedendir. Açma üst sınırı belleği sınırlar. Bkz. performance_budget.

Güvenlik notları

Bayt düzeyindeki geri dönüş, hazırlanmış PDF’lerde felaket düzeyinde geri izlemeden kaçınmak için sınırsız regex yerine strpos tabanlı tarama kullanır ve açma çıktısını sınırlar. Fark alma, gömülü betikleri yürütmez. Core güvenlik modeline bakın.

Uygunluk

İddia	Standart maddesi	Durum
Çıkarım için `Tj` metin operatörü ayrıştırıldı	ISO 32000-2:2020 §9.4	Doğrulandı (birim paketi)
Çıkarım için `TJ` dizi metin operatörü ayrıştırıldı	ISO 32000-2:2020 §9.4	Doğrulandı (birim paketi)
Görsel yan yana kırmızı çizgili PDF çıktısı	—	Desteklenmiyor (yalnızca JSON/HTML)

Core geri dönüşü / alternatifi

Belge karşılaştırması için hiçbir Core eşdeğeri yoktur. İsteğe bağlı Artisan okuyucusu, yüklendiğinde çıkarım doğruluğunu artırır ancak gerekli değildir.

Enterprise sınır notu

Bu, bir içerik değişikliği algılayıcısıdır. Adli bir fark çözümleyicisi değildir ve delil niteliğinde veya kurcalama ataması raporları üretmez; bu konular bu modülün kapsamı dışındadır.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilen davranışı ve desteklenen genel API yüzeyini açıklar. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, çalışma kılavuzu dosya adları ve bilet önekleri kapsam dışındadır.