Pro phiên bản

Diff

Tổng quan nhanh

NextPDF\Pro\Diff so sánh hai tài liệu PDF và báo cáo những gì đã thay đổi. Đường nhanh tạo ra một diff văn bản căn theo trang; đường có cấu trúc bổ sung việc phát hiện thay đổi về hình ảnh và metadata, và định dạng kết quả dưới dạng JSON hoặc HTML.

Tính khả dụng & cấp phép

Năng lực này có sẵn trong NextPDF Pro (nextpdf/pro) và được kích hoạt bằng một license envelope hạng Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và nhận giấy phép.

Không có cờ năng lực lúc chạy nào kiểm soát các lớp Diff; chúng luôn hiện diện bất cứ khi nào gói Pro được cài đặt.

Cài đặt

composer require nextpdf/pro:^3

Tổng quan khái niệm

PdfDiffer::compare() trích xuất văn bản theo từng trang từ mỗi tài liệu, tách nó thành các dòng, và chạy một diff dòng theo thuật toán Myers cho mỗi cặp trang, tạo ra các vùng được thêm, bị xóa và bị sửa đổi. Việc trích xuất văn bản phân tích các toán tử hiển thị văn bản của ISO 32000-2:2020 §9.4 (Tj, TJ, ').

StructuredDiffer xây dựng trên đó: nó nhóm các vùng văn bản thành các thay đổi ở mức đoạn văn, so sánh các hình ảnh nhúng, so sánh metadata, và tạo ra một StructuredDiffResult với một bản tóm tắt tổng hợp. DiffFormatter tuần tự hóa kết quả đó thành một chuỗi JSON hoặc một mảnh báo cáo HTML.

Khi bộ đọc PDF Artisan tùy chọn được cài đặt, việc trích xuất văn bản sẽ dùng nó để có nội dung chính xác theo trang; nếu không, một phương án dự phòng ở mức byte có giới hạn sẽ quét trực tiếp các content stream.

Vì sao nó hoạt động theo cách này

Bộ diff so sánh văn bản và cấu trúc đã trích xuất, chứ không phải các pixel đã kết xuất. Một so sánh cấu trúc là tất định, rẻ, và ánh xạ tới các thay đổi biên tập mà một người rà soát quan tâm. Một diff pixel thay vào đó sẽ đánh dấu nhiễu từ khử răng cưa và font-hinting như thể là nội dung. Vì một PDF lưu trữ các glyph và định vị, chứ không phải các ký tự sẵn-sàng-đọc, mỗi lần so sánh trước tiên phải tái dựng văn bản từ content stream. Bước trích xuất đó là lý do bộ đọc Artisan làm sắc nét độ chính xác, lý do phương án dự phòng FlateDecode có giới hạn đánh đổi phạm vi lấy an toàn, và lý do các trang được quét gần như không diff được. Việc căn trang vẫn dựa trên chỉ số để đảm bảo tính dự đoán được, nên một trang được chèn vào sẽ đọc thành một sự dịch chuyển rõ ràng về phía sau.

Bối cảnh thiết kế: Vì sao văn bản trong một PDF không thực sự là văn bản.

Hợp đồng hành vi

Đầu vào. Các byte PDF thô cho nguồn và đích. Một buffer không bắt đầu bằng %PDF sẽ làm phát sinh InvalidArgumentException.
Đầu ra (đường nhanh). DiffResult với các danh sách vùng added, removed, modified cùng isIdentical(), hasDifferences(), totalChanges().
Đầu ra (đường có cấu trúc). StructuredDiffResult với các diff đoạn văn, diff hình ảnh, thay đổi metadata và một DiffSummary.
Đầu ra báo cáo. DiffFormatter phát ra một chuỗi JSON hoặc một mảnh HTML. Nó không tạo ra một PDF redline song song trực quan.
Giới hạn tài nguyên. Kích thước content-stream sau giải nén được giới hạn để phòng vệ trước các bom giải nén; bộ quét ở mức byte tránh việc quay lui regex thảm họa trên đầu vào được tạo dựng có chủ đích.
Tính tất định. Với cùng đầu vào, các vùng diff và đầu ra đã định dạng là ổn định.

Bề mặt API công khai

Kiểu	Loại	Thành viên chính
`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`	text diff, paragraphs, images, metadata changes, summary
`NextPDF\Pro\Diff\DiffType`	`enum`	`Added`, `Removed`, `Modified`, `Unchanged`

Mẫu mã — Khởi đầu nhanh

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

Mẫu mã — Production

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

Trường hợp biên & lưu ý

Diff được căn theo trang theo chỉ số. Việc chèn một trang ở phía trước sẽ đẩy tất cả các trang sau và báo cáo những thay đổi lớn ở phía sau — điều này là như mong đợi đối với một so sánh căn theo chỉ số.
So sánh hình ảnh phát hiện các hình ảnh nhúng được thêm, bị xóa và bị sửa đổi; nó không phải là một diff trực quan theo cảm nhận và không kết xuất các trang thành pixel.
Các PDF chỉ-hình-ảnh được quét tạo ra rất ít hoặc không có diff văn bản vì không có OCR nào được thực hiện.
Nếu không có bộ đọc Artisan tùy chọn, việc trích xuất sẽ dùng phương án dự phòng có giới hạn; các tài liệu nén nặng có thể cho ra phạm vi văn bản giảm xuống.

Hiệu năng

Việc trích xuất văn bản là tuyến tính theo số byte của tài liệu; diff Myers là gần-tuyến-tính đối với các tài liệu tương tự và bậc hai trong trường hợp xấu nhất cho mỗi cặp trang. Mức giới hạn giải nén ràng buộc bộ nhớ. Xem performance_budget.

Ghi chú về bảo mật

Phương án dự phòng ở mức byte dùng quét dựa trên strpos thay vì regex không giới hạn để tránh việc quay lui thảm họa trên các PDF được tạo dựng có chủ đích, và giới hạn đầu ra giải nén. Việc so sánh diff không thực thi các script nhúng. Xem mô hình bảo mật của Core.

Sự phù hợp tiêu chuẩn

Tuyên bố	Điều khoản tiêu chuẩn	Trạng thái
Toán tử văn bản `Tj` được phân tích để trích xuất	ISO 32000-2:2020 §9.4	Đã xác minh (bộ kiểm thử đơn vị)
Toán tử văn bản mảng `TJ` được phân tích để trích xuất	ISO 32000-2:2020 §9.4	Đã xác minh (bộ kiểm thử đơn vị)
Đầu ra PDF redline song song trực quan	—	Không hỗ trợ (chỉ JSON/HTML)

Phương án dự phòng / thay thế trong Core

Không có tương đương trong Core cho việc so sánh tài liệu. Bộ đọc Artisan tùy chọn cải thiện độ chính xác trích xuất khi được cài đặt nhưng không bắt buộc.

Ghi chú ranh giới Enterprise

Đây là một bộ phát hiện thay đổi nội dung. Nó không phải là một bộ phân tích khác biệt pháp y và không tạo ra các báo cáo làm bằng chứng hay quy gán giả mạo; những mối quan tâm đó nằm ngoài phạm vi của module này.

Ranh giới công bố

Trang này chỉ ghi lại hành vi có thể quan sát từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook và tiền tố ticket đều nằm ngoài phạm vi.