Merge — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tài liệu tham chiếu cấp hợp đồng cho module NextPDF Pro Merge, NextPDF\Pro\Merge. SmartMerger ghép nhiều tài liệu đầu vào thành một và áp dụng các nâng cấp của Pro: một cây dấu trang được hợp nhất từ nhãn của từng đầu vào, khử trùng lặp toàn tài liệu, chọn dải trang cho từng đầu vào, và phát hiện liên kết nội bộ. SemanticSplitter là điểm vào tách theo cấu trúc đi kèm. Trang này nêu API công khai, hợp đồng hành vi quan sát được, các giới hạn tài nguyên, và các chế độ lỗi. Phần thiết lập theo tác vụ và ví dụ mẫu nằm ở trang năng lực Merge.

Tình trạng cung cấp & cấp phép

Năng lực này đi kèm trong NextPDF Pro (nextpdf/pro) và được kích hoạt bằng một phong bì giấy phép bậc 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à lấy giấy phép.

Không có cờ năng lực lúc chạy nào kiểm soát module này. Các lớp Merge có thể dùng được bất cứ khi nào nextpdf/pro được cài đặt và cấp phép.

Bề mặt API công khai

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
SmartMerger::__construct()	?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null	Nhận và bỏ qua core merger cũ; một null splitter sẽ dựng splitter Pro mặc định	—	—	$coreMerger được giữ lại chỉ để dựng tương thích ngược
SmartMerger::merge()	list<MergeInput> $inputs, SmartMergeConfig $config = new SmartMergeConfig()	Thu gọn các dải trang, khử trùng lặp toàn đầu vào, ủy thác việc ghép nền, rồi chèn dấu trang và đếm liên kết theo config	SmartMergeResult	InvalidArgumentException khi danh sách đầu vào rỗng; OverflowException khi số đầu vào vượt maxInputs hoặc một đầu vào vượt maxBytesPerInput	Điểm vào gộp duy nhất
MergeInput::__construct()	string $pdfData, list<PageRange> $pageRanges = [], string $label = ''	Value object; một $pageRanges rỗng chọn tất cả các trang	—	—	Readonly
MergeInput::hasPageRanges()	—	Đúng khi đầu vào mang ít nhất một dải trang	bool	—	—
SmartMergeConfig::__construct()	bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000	Value object giữ các công tắc nâng cấp và các giới hạn tài nguyên	—	—	Readonly; khử trùng lặp là tùy chọn bật
SmartMergeConfig::default()	—	Bật dấu trang và quét liên kết, tắt khử trùng lặp	self	—	Static factory
SmartMergeConfig::basic()	—	Tắt mọi nâng cấp; chỉ nối nền	self	—	Static factory
SmartMergeResult::__construct()	string $pdfData, int $totalPages, int $sourceCount, int $mergedSize, int $bookmarksAdded = 0, int $duplicatesRemoved = 0, int $linksRewritten = 0, list<string> $inputLabels = []	Bộ mang readonly cho các byte đã gộp và số liệu thống kê hợp nhất	—	—	Readonly
SmartMergeResult::isValid()	—	Đúng khi đầu ra bắt đầu bằng header %PDF	bool	—	Chỉ kiểm tra header
SmartMergeResult::hasOptimizations()	—	Đúng khi có bất kỳ bản trùng lặp nào bị loại bỏ hoặc bất kỳ liên kết nào được đếm	bool	—	—
SemanticSplitter::__construct()	?PdfSplitter $splitter = null	Một đối số null sẽ dựng splitter Pro mặc định	—	—	Tiêm qua constructor để kiểm thử
SemanticSplitter::splitByStructure()	string $pdfData, float $headingFontThreshold = 14.0	Phát hiện các toán tử Tf cỡ tiêu đề làm điểm bắt đầu phần và tách tại các ranh giới đó; nếu không phát hiện cấu trúc thì trả về một phần toàn tài liệu	SplitResult	InvalidArgumentException khi buffer rỗng hoặc thiếu header %PDF; OverflowException khi đầu vào vượt 100 MB	Lùi về tách theo dải trang của Core

Chữ ký điểm vào

public function __construct(
    ?PdfMerger $coreMerger = null,
    ?PdfSplitter $splitter = null,
)

public function merge(
    array $inputs,
    SmartMergeConfig $config = new SmartMergeConfig(),
): SmartMergeResult

public function __construct(
    public string $pdfData,
    public array $pageRanges = [],
    public string $label = '',
)

public function hasPageRanges(): bool

public function __construct(
    public bool $consolidateBookmarks = true,
    public bool $deduplicatePages = false,
    public bool $rewriteLinks = true,
    public int $maxInputs = 100,
    public int $maxBytesPerInput = 100_000_000,
)

public static function default(): self

public static function basic(): self

public function isValid(): bool

public function hasOptimizations(): bool

public function __construct(?PdfSplitter $splitter = null)

public function splitByStructure(
    string $pdfData,
    float $headingFontThreshold = 14.0,
): SplitResult

Hợp đồng hành vi

Pipeline gộp

SmartMerger::merge() chạy một pipeline cố định, quan sát được từ bên ngoài như sau.

1. Một danh sách đầu vào rỗng sẽ ném InvalidArgumentException. Số đầu vào sau đó bị giới hạn bởi maxInputs; vượt quá sẽ ném OverflowException.
2. Mỗi đầu vào được kiểm tra kích thước so với maxBytesPerInput trước khi dùng. Khi đầu vào khai báo các dải trang, nó được thu gọn về các trang đã chọn trước qua splitter Pro, rồi chỉ đóng góp các trang đó.
3. Khi deduplicatePages được bật, toàn bộ chuỗi byte của mỗi tài liệu đầu vào được lấy vân tay bằng hàm không mật mã xxh128. Một đầu vào có byte trùng khớp chính xác với một đầu vào trước đó sẽ bị bỏ. Khử trùng lặp là toàn tài liệu và chính xác đến từng byte.
4. Việc ghép nền ủy thác cho engine PdfSplitter::mergeDocuments() 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ật.
5. Hợp nhất dấu trang được áp dụng khi consolidateBookmarks được bật và ít nhất một đầu vào mang nhãn không rỗng. Một từ điển /Outlines tối thiểu được chèn vào, liên kết từ catalog tài liệu, với một mục outline cho mỗi đầu vào theo thứ tự gộp.
6. Khi rewriteLinks được bật, đầu ra đã gộp được quét tìm các action /S /GoTo và số lượng của chúng được báo cáo.

Số liệu thống kê kết quả

SmartMergeResult báo cáo các byte đã gộp cùng số liệu thống kê. totalPages đến từ bước gộp nền. sourceCount là số đầu vào ban đầu, lấy trước khi khử trùng lặp. mergedSize là độ dài byte của đầu ra. bookmarksAdded chỉ đếm các đầu vào cung cấp nhãn không rỗng. duplicatesRemoved đếm các đầu vào toàn phần bị bỏ. linksRewritten là số GoTo được phát hiện. inputLabels liệt kê các nhãn đã phân giải theo thứ tự gộp. isValid() kiểm tra header %PDF; hasOptimizations() là đúng khi một bản trùng lặp bị loại bỏ hoặc một liên kết được đếm.

Tiêu đề dấu trang

Mỗi mục outline mang nhãn đầu vào dưới dạng một /Title, được escape thành một chuỗi literal PDF theo ISO 32000-2:2020 §7.3.4.2. Dấu gạch chéo ngược được nhân đôi trước, dấu ngoặc đơn được escape, các byte điều khiển có tên dùng chuỗi đã định nghĩa của chúng, và bất kỳ byte không in được nào còn lại trở thành một escape bát phân ba chữ số. Vì vậy một nhãn thù địch không thể làm mất đồng bộ dấu phân giới chuỗi literal hoặc tiêm cấu trúc đối tượng. Các đầu vào có nhãn rỗng nhận một tiêu đề giữ chỗ Document N, đánh chỉ số từ một.

Ghép nền

PdfMerger::merge() của Core cũ là một stub cố tình fail-closed trong bản phát hành này; nó không bao giờ được SmartMerger gọi. Bước gộp nền thay vào đó chạy qua PdfSplitter::mergeDocuments() của Pro, nên tệp đã gộp mang một bảng tham chiếu chéo chính xác đến từng byte với một mục cho mỗi đối tượng gián tiếp theo ISO 32000-2:2020 §7.5.4. Tính tất định tuân theo hồ sơ đã tài liệu hóa của splitter Pro: đầu vào và cấu hình giống hệt nhau tạo ra một luồng byte ổn định.

Tách theo cấu trúc

SemanticSplitter::splitByStructure() quét các content stream của trang tìm các toán tử đặt font Tf tại hoặc trên headingFontThreshold (mặc định 14.0) và coi mỗi trang như vậy là một điểm bắt đầu phần. Các ranh giới được chuyển thành các dải trang và ủy thác cho PdfSplitter::split() của Pro. Khi không phát hiện ranh giới nào, toàn tài liệu được trả về như một phần duy nhất. Đầu vào phải bắt đầu bằng %PDF và nằm trong giới hạn 100 MB.

Trường hợp ngoại lệ & chế độ lỗi

• Một danh sách đầu vào rỗng thất bại với InvalidArgumentException trước bất kỳ việc ghép nào.
• Số đầu vào trên maxInputs (mặc định 100), hoặc bất kỳ đầu vào nào trên maxBytesPerInput (mặc định 100 MB), thất bại với OverflowException. Cả hai giới hạn đều là những từ chối fail-closed cố tình, không phải lỗi tạm thời.
• Khử trùng lặp là toàn tài liệu và chính xác đến từng byte. Hai đầu vào kết xuất giống hệt nhau nhưng khác nhau ở bất kỳ byte nào đều được giữ lại, và duplicatesRemoved đếm các đầu vào toàn phần bị bỏ bất chấp tên deduplicatePages mang tính hướng trang.
• sourceCount phản ánh số đầu vào ban đầu, không phải số tài liệu sau khi khử trùng lặp.
• Hợp nhất dấu trang chỉ kích hoạt khi ít nhất một đầu vào có nhãn không rỗng. Với consolidateBookmarks là đúng nhưng mọi nhãn đều rỗng, không có đối tượng /Outlines nào được ghi.
• Các mục outline được chèn mang tiêu đề và các liên kết cây /Parent, /Prev, /Next; chúng không nhúng đích /Dest tường minh trong bản phát hành này.
• Việc ghi lại liên kết chỉ đếm các action /S /GoTo; nó không trỏ lại các đích trên các đối tượng đã được đánh số lại. Hãy coi linksRewritten là một số đếm phát hiện.
• Phát hiện của SemanticSplitter mang tính từ vựng. Nó dựa vào các toán tử cỡ font Tf, nên các trang chỉ có ảnh hoặc mã hóa bất thường không tạo ra ranh giới nào và trả về một phần toàn tài liệu duy nhất.

Hành vi ở chế độ FIPS

Không có thao tác mật mã nào xảy ra trong module này, nên không có hành vi đặc thù chế độ FIPS. Vân tay nội dung xxh128 dùng cho khử trùng lặp là một hash phát hiện thay đổi không mật mã và không mang trọng lượng toàn vẹn hay chứng cứ nào.

Tính phù hợp

Tuyên bố	Tiêu chuẩn	Điều khoản
Dấu trang hợp nhất được ghi dưới dạng một từ điển /Outlines liên kết từ catalog tài liệu	ISO 32000-2:2020	§7.7.2
Bước gộp nền phát ra một bảng tham chiếu chéo chính xác đến từng byte cho mọi đối tượng gián tiếp	ISO 32000-2:2020	§7.5.4
Tiêu đề mục outline được escape thành các chuỗi literal PDF, với xử lý dấu gạch chéo ngược và dấu ngoặc đơn	ISO 32000-2:2020	§7.3.4.2
Phân giải lại liên kết chéo tài liệu đầy đủ	—	Không hỗ trợ (chỉ phát hiện GoTo)
Đích outline tường minh cho từng phần	—	Không phát ra trong bản phát hành này

Mọi điều khoản đều được diễn giải lại; NextPDF không tái tạo văn bản quy phạm. Đây là các tuyên bố về năng lực, không phải chứng nhận; NextPDF không nắm giữ chứng nhận nào và không cấp chứng nhận nào.

Ghi chú phát triển

• Tình trạng cung cấp trong gói Pro: SmartMerger, MergeInput, SmartMergeConfig, SmartMergeResult, và SemanticSplitter từ 2.2.0. Tất cả đều hiện hành trong nextpdf/pro 3.1.0.
• Bước gộp nền ủy thác cho PdfSplitter::mergeDocuments() của Pro. PdfMerger::merge() của Core cũ là một stub fail-closed trong bản phát hành này và không bao giờ được gọi.
• Chỉ bật deduplicatePages khi các đầu vào có thể là các tài liệu toàn phần giống hệt nhau đến từng byte; nó không gộp các bản gần trùng lặp hoặc đã mã hóa lại.
• Dùng SmartMergeConfig::basic() cho việc nối thuần túy và ::default() cho dấu trang cộng với quét liên kết.
• Bắt OverflowException khi gộp đầu vào không tin cậy; các giới hạn về số lượng và kích thước là những từ chối có chủ đích.
• Ưu tiên dùng trực tiếp PdfSplitter của Pro cho việc tách theo dải trang đơn giản; chỉ dùng đến SemanticSplitter khi cần phân đoạn theo tiêu đề.

Ranh giới xuất bản

Trang này chỉ tài liệu hóa hành vi quan sát được 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.

Xem thêm

• Merge (năng lực) — cài đặt, khởi động nhanh, và các ví dụ mẫu cho môi trường sản xuất.
• Toc — Tài liệu tham chiếu chuyên sâu
• Diff — Tài liệu tham chiếu chuyên sâu
• Document — Tài liệu tham chiếu chuyên sâu — splitter Pro và engine gộp nền.