Pro edycja

Porównanie różnic

W skrócie

NextPDF\Pro\Diff porównuje dwa dokumenty PDF i raportuje, co się zmieniło. Szybka ścieżka wytwarza wyrównaną względem stron różnicę tekstu; ścieżka strukturalna dodaje wykrywanie zmian obrazów i metadanych oraz formatuje wynik jako JSON lub HTML.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Żadna flaga możliwości w czasie wykonywania nie bramkuje klas Diff; są one obecne zawsze, gdy zainstalowano pakiet Pro.

Instalacja

composer require nextpdf/pro:^3

Przegląd koncepcyjny

PdfDiffer::compare() wyodrębnia tekst na stronę z każdego dokumentu, dzieli go na wiersze i uruchamia różnicowanie wierszy metodą Myersa na parę stron, wytwarzając regiony dodane, usunięte i zmodyfikowane. Ekstrakcja tekstu parsuje operatory pokazywania tekstu z ISO 32000-2:2020 §9.4 (Tj, TJ, ').

StructuredDiffer opiera się na tym: grupuje regiony tekstu w zmiany na poziomie akapitów, porównuje osadzone obrazy, porównuje metadane i wytwarza StructuredDiffResult z zagregowanym podsumowaniem. DiffFormatter serializuje ten wynik do ciągu JSON lub do fragmentu raportu HTML.

Gdy zainstalowano opcjonalny czytnik PDF Artisan, ekstrakcja tekstu używa go do uzyskania zawartości dokładnej co do strony; w przeciwnym razie ograniczone rozwiązanie awaryjne na poziomie bajtów skanuje strumienie zawartości bezpośrednio.

Dlaczego działa to w ten sposób

Narzędzie różnicujące porównuje wyodrębniony tekst i strukturę, a nie wyrenderowane piksele. Porównanie strukturalne jest deterministyczne, tanie i odwzorowuje zmiany redakcyjne, na których zależy recenzentowi. Różnica pikselowa zamiast tego oznaczałaby szum antyaliasingu i hintingu czcionek jako treść. Ponieważ PDF przechowuje glify i pozycjonowanie, a nie gotowe do odczytu znaki, każde porównanie najpierw rekonstruuje tekst ze strumienia zawartości. Ten krok ekstrakcji jest powodem, dla którego czytnik Artisan wyostrza dokładność, dla którego ograniczone rozwiązanie awaryjne FlateDecode wymienia pokrycie na bezpieczeństwo i dla którego zeskanowane strony ledwie się różnicują. Wyrównanie stron pozostaje oparte na indeksie dla przewidywalności, więc wstawiona strona odczytywana jest jako wyraźne przesunięcie w dół.

Tło projektowe: Dlaczego tekst w PDF nie jest naprawdę tekstem.

Kontrakt zachowania

Wejście. Surowe bajty PDF dla źródła i celu. Bufor nierozpoczynający się od %PDF zgłasza InvalidArgumentException.
Wyjście (szybka ścieżka). DiffResult z listami regionów added, removed, modified oraz isIdentical(), hasDifferences(), totalChanges().
Wyjście (ścieżka strukturalna). StructuredDiffResult z różnicami akapitów, różnicami obrazów, zmianami metadanych oraz DiffSummary.
Wyjście raportu. DiffFormatter emituje ciąg JSON lub fragment HTML. Nie wytwarza wizualnego pliku PDF z zaznaczeniem zmian obok siebie.
Granice zasobów. Rozmiar zdekompresowanego strumienia zawartości jest ograniczony, aby chronić przed bombami dekompresyjnymi; skaner na poziomie bajtów unika katastrofalnego nawracania wyrażeń regularnych na spreparowanym wejściu.
Determinizm. Dla identycznych wejść regiony różnic i sformatowane wyjście są stabilne.

Publiczna powierzchnia API

Typ	Rodzaj	Kluczowe składowe
`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`	różnica tekstu, akapity, obrazy, zmiany metadanych, podsumowanie
`NextPDF\Pro\Diff\DiffType`	`enum`	`Added`, `Removed`, `Modified`, `Unchanged`

Przykład kodu — Szybki start

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

Przykład kodu — Produkcja

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

Przypadki brzegowe i pułapki

Różnica jest wyrównywana względem stron według indeksu. Wstawienie strony wcześnie przesuwa wszystkie późniejsze strony i raportuje duże zmiany w dół — to zachowanie oczekiwane dla porównania wyrównanego względem indeksu.
Porównanie obrazów wykrywa dodane, usunięte i zmodyfikowane osadzone obrazy; nie jest to różnicowanie percepcyjne i wizualne, a strony nie są renderowane na poziomie pikseli.
Zeskanowane, wyłącznie obrazowe pliki PDF wytwarzają niewielką różnicę tekstu lub żadną, ponieważ nie wykonuje się OCR.
Bez opcjonalnego czytnika Artisan ekstrakcja używa ograniczonego rozwiązania awaryjnego; silnie skompresowane dokumenty mogą dać zmniejszone pokrycie tekstu.

Wydajność

Ekstrakcja tekstu jest liniowa względem bajtów dokumentu; różnicowanie metodą Myersa jest prawie liniowe dla podobnych dokumentów i kwadratowe w najgorszym przypadku na parę stron. Limit dekompresji ogranicza pamięć. Zobacz performance_budget.

Uwagi dotyczące bezpieczeństwa

Rozwiązanie awaryjne na poziomie bajtów używa skanowania opartego na strpos zamiast nieograniczonych wyrażeń regularnych, aby uniknąć katastrofalnego nawracania na spreparowanych plikach PDF, oraz ogranicza wyjście dekompresji. Różnicowanie nie wykonuje osadzonych skryptów. Zobacz model bezpieczeństwa Core.

Konformancja

Twierdzenie	Klauzula specyfikacji	Status
Operator tekstu `Tj` sparsowany do ekstrakcji	ISO 32000-2:2020 §9.4	Zweryfikowane (zestaw testów jednostkowych)
Operator tablicowy tekstu `TJ` sparsowany do ekstrakcji	ISO 32000-2:2020 §9.4	Zweryfikowane (zestaw testów jednostkowych)
Wizualne wyjście PDF z zaznaczeniem zmian obok siebie	—	Nieobsługiwane (tylko JSON/HTML)

Rozwiązanie awaryjne / alternatywa w Core

Nie istnieje odpowiednik w Core dla porównywania dokumentów. Opcjonalny czytnik Artisan poprawia dokładność ekstrakcji, gdy jest zainstalowany, ale nie jest wymagany.

Nota o granicy Enterprise

To detektor zmian zawartości. Nie jest śledczym analizatorem różnic i nie wytwarza raportów dowodowych ani przypisujących manipulacje; te kwestie są poza zakresem tego modułu.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne zewnętrznie oraz obsługiwaną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków i prefiksy zgłoszeń są poza zakresem.