Pro phiên bản

Hợp nhất

Tổng quan nhanh

NextPDF\Pro\Merge\SmartMerger gộp nhiều PDF thành một, rồi áp dụng các cải tiến của Pro: một cây dấu trang được hợp nhất từ các nhãn theo từng đầu vào, khử trùng lặp trang theo content-hash, và chọn phạm vi trang theo từng đầu vào. Việc lắp ráp tài liệu cơ sở chạy qua engine gộp object-graph của Pro. Nó đánh số lại mọi đầu vào vào một không gian đối tượng và ghi ra một bảng tham chiếu chéo thực sự.

Tình trạng khả dụng & cấp phép

Năng lực này đi kèm trong NextPDF Pro (nextpdf/pro) và 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 tải các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Các lớp Merge có sẵn bất cứ khi nào gói Pro được cài đặt. Không có cờ năng lực lúc chạy nào kiểm soát module này.

Cài đặt

composer require nextpdf/pro:^3

Tổng quan khái niệm

SmartMerger nhận một danh sách các value object MergeInput. Mỗi đầu vào mang theo các byte PDF nguồn, một danh sách phạm vi trang tùy chọn, và một nhãn tùy chọn. Các đầu vào có phạm vi trang được rút gọn về các trang đã chọn trước khi gộp. Tài liệu hợp nhất được tạo ra bởi engine gộp object-graph của Pro, engine này đánh số lại mọi đầu vào vào một không gian đối tượng liền mạch và phát ra một bảng tham chiếu chéo thực sự; lớp Pro sau đó bổ sung các cải tiến được yêu cầu.

SmartMergeConfig điều khiển các cải tiến:

Hợp nhất dấu trang chèn một mục outline cho mỗi đầu vào có nhãn, trỏ đến điểm bắt đầu của phần thuộc đầu vào đó. Việc này theo mô hình /Outlines của document catalog trong ISO 32000-2:2020 §7.7.2.
Khử trùng lặp trang loại bỏ các trang trùng lặp giống hệt theo byte trên các đầu vào, được so sánh theo content hash.
Viết lại liên kết quét các action GoTo nội bộ trong kết quả hợp nhất.

SmartMergeResult báo cáo các byte đã hợp nhất cùng thống kê: tổng số trang, số nguồn, kích thước đầu ra, số dấu trang đã thêm, số trùng lặp đã loại bỏ, số liên kết đã phát hiện, và các nhãn đầu vào đã sắp thứ tự.

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

Gộp các PDF không phải là nối chuỗi byte: mỗi đầu vào mang theo số đối tượng riêng, bảng tham chiếu chéo, và cây trang riêng, nên một phép ghép ngây thơ sẽ không tải được trong bất kỳ trình đọc tuân thủ chuẩn nào. Do đó SmartMerger ủy thác việc lắp ráp cơ sở cho engine object-graph của Pro (PdfSplitter::mergeDocuments()), engine này đánh số lại mọi đầu vào vào một không gian đối tượng liền mạch, dựng lại một cây trang duy nhất, và phát ra một bảng tham chiếu chéo thực sự với các offset byte thật. Các cải tiến của Pro — hợp nhất dấu trang, khử trùng lặp, và phát hiện liên kết — sau đó xếp lớp trên đầu ra đã kiểm chứng đó thay vì tái hiện thực việc lắp ráp. Khử trùng lặp toàn tài liệu và xử lý liên kết chỉ-phát-hiện là các ranh giới phạm vi có chủ đích giữ cho phép gộp có tính tất định và an toàn trên đầu vào không tin cậy.

Bối cảnh thiết kế: Giải phẫu một tệp PDF.

Hợp đồng hành vi

Đầu vào. Một danh sách MergeInput không rỗng. Một danh sách rỗng phát sinh InvalidArgumentException. Số đầu vào và kích thước byte theo từng đầu vào bị giới hạn bởi SmartMergeConfig (maxInputs, maxBytesPerInput).
Đầu ra. Một SmartMergeResult. isValid() là true khi đầu ra bắt đầu bằng header %PDF.
Hợp nhất dấu trang thêm một mục cho mỗi đầu vào có một nhãn không rỗng, khi consolidateBookmarks được bật.
Khử trùng lặp là tùy chọn bật (deduplicatePages, mặc định tắt) và so khớp toàn trang theo content hash, không phải các trang tương tự về mặt trực quan.
Viết lại liên kết trong bản phát hành hiện tại phát hiện và đếm các action GoTo nội bộ; nó không thực hiện việc tái-phân-giải đích đầy đủ xuyên tài liệu. Hãy coi linksRewritten là một số đếm phát hiện.
Tính tất định. Với các đầu vào và cấu hình giống hệt, dòng byte đã hợp nhất ổn định, tùy thuộc vào hồ sơ tính tất định đã được ghi tài liệu của engine gộp Pro.

Bề mặt Public API

Kiểu	Loại	Thành viên chính
`NextPDF\Pro\Merge\SmartMerger`	`final class`	`__construct(?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null)`, `merge(array $inputs, SmartMergeConfig $config = new SmartMergeConfig()): SmartMergeResult`
`NextPDF\Pro\Merge\MergeInput`	`final readonly class`	`__construct(string $pdfData, array $pageRanges = [], string $label = '')`, `hasPageRanges(): bool`
`NextPDF\Pro\Merge\SmartMergeConfig`	`final readonly class`	`__construct(bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000)`, `default()`, `basic()`
`NextPDF\Pro\Merge\SmartMergeResult`	`final readonly class`	`string $pdfData`, `int $totalPages`, `int $sourceCount`, `int $bookmarksAdded`, `int $duplicatesRemoved`, `int $linksRewritten`, `array $inputLabels`, `isValid(): bool`, `hasOptimizations(): bool`

Mẫu mã — Bắt đầu nhanh

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMerger;

$result = (new SmartMerger())->merge([
    new MergeInput(file_get_contents('cover.pdf'), label: 'Cover'),
    new MergeInput(file_get_contents('body.pdf'),  label: 'Body'),
]);

echo $result->totalPages, " pages, ",
     $result->bookmarksAdded, " bookmarks\n";

Mẫu mã — Sản phẩm

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMergeConfig;
use NextPDF\Pro\Merge\SmartMerger;

function assemblePacket(array $sections): string
{
    $inputs = [];
    foreach ($sections as $label => $bytes) {
        $inputs[] = new MergeInput($bytes, label: (string) $label);
    }

    $config = new SmartMergeConfig(
        consolidateBookmarks: true,
        deduplicatePages: true,
        rewriteLinks: false,
        maxInputs: 50,
    );

    $result = (new SmartMerger())->merge($inputs, $config);

    if (! $result->isValid()) {
        throw new RuntimeException('merge produced invalid output');
    }

    return $result->pdfData;
}

Trường hợp ngoại lệ & lưu ý

Một đầu vào đơn lẻ là hợp lệ và gộp thành một bản sao đã chuẩn hóa của tài liệu đó.
Khử trùng lặp so sánh nội dung byte toàn trang; các trang chỉ khác nhau ở metadata hoặc cách đánh số đối tượng không được coi là trùng lặp.
Việc chọn phạm vi trang trên một đầu vào được áp dụng trước khi sắp thứ tự gộp.
linksRewritten là một số đếm action đã phát hiện, không phải một bảo đảm rằng mọi đích liên kết xuyên tài liệu đã được trỏ lại.

Hiệu năng

Chi phí bị chi phối bởi engine gộp Pro và tỷ lệ thuận với tổng byte đầu vào và số trang. Khử trùng lặp thêm một content hash cho mỗi trang. Phần frontmatter performance_budget là tham chiếu theo từng lần gộp.

Lưu ý bảo mật

Số đầu vào và kích thước theo từng đầu vào bị giới hạn bởi SmartMergeConfig để giới hạn cạn kiệt tài nguyên từ các đầu vào thù địch. Việc gộp không thực thi các script tài liệu nhúng. Xem mô hình bảo mật Core để biết cách làm cứng phân tích cú pháp dòng byte.

Tính phù hợp

Tuyên bố	Điều khoản đặc tả	Tình trạng
Dấu trang hợp nhất qua `/Outlines`	ISO 32000-2:2020 §7.7.2	Đã kiểm chứng (bộ unit)
Khử trùng lặp trang theo content-hash	—	Đã kiểm chứng (bộ unit)
Tái-phân-giải liên kết xuyên tài liệu đầy đủ	—	Không được hỗ trợ (chỉ phát hiện)

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

Đối với việc nối chuỗi cơ bản không có hợp nhất của Pro, lớp Core mã nguồn mở NextPDF\Document\PdfMerger là đường dẫn độc lập được hỗ trợ. SmartMerger không ủy thác cho nó; phép gộp của Pro chạy trên engine object-graph riêng của mình. Xem /modules/core/document/.

Lưu ý ranh giới Enterprise

Module này thực hiện việc gộp cấu trúc. Nó không thực hiện lắp ráp legal-hold, xóa che, hay đóng gói chuỗi giám hộ chứng cứ; những thứ đó không được cung cấp ở đây.

Ranh giới công bố

Trang này chỉ mô tả hành vi quan sát được từ bên ngoài và bề mặt public API đượ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 nằm ngoài phạm vi.