Pro phiên bản

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

Tổng quan nhanh

Module Document cung cấp ba nguyên thủy lắp ráp của Pro: tách theo dải trang, gộp nhiều tài liệu, và dựng từ điển PDF Portfolio (Collection). PdfSplitter trích các dải trang thành các PDF độc lập, đạt chuẩn về cấu trúc và gộp toàn bộ tài liệu thành một tệp được đánh số lại. PdfPortfolio dựng từ điển Collection trình bày các tệp nhúng với các cột schema có thể sắp xếp. Mọi điểm vào đều giới hạn kích thước đầu vào và số lượng đối tượng để chống lại đầu vào thù địch.

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

Năng lực này có 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à lấy giấy phép.

Bề mặt API công khai

Tất cả các kiểu của module nằm trong namespace NextPDF\Pro\Document. PageRange và MergeResult là các đối tượng giá trị của Core từ NextPDF\Document.

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ú
`PdfSplitter::split()`	`string $pdfData`, `list<PageRange> $ranges`, `int $maxBytes = 100_000_000`, `int $maxRanges = 1000`	Dựng một đoạn PDF độc lập cho mỗi dải	`SplitResult`	`InvalidArgumentException` khi thiếu header `%PDF`; `OverflowException` khi vi phạm guard về kích thước, số lượng dải, hoặc closure	Các guard chạy trước bất kỳ thao tác phân tích nào
`PdfSplitter::splitEvery()`	`string $pdfData`, `int $pagesPerSegment`	Suy ra các dải N-trang liền kề; đoạn cuối có thể ngắn hơn	`SplitResult`	`InvalidArgumentException` khi `$pagesPerSegment < 1` hoặc thiếu header	Ủy thác cho `split()` với các mức trần mặc định
`PdfSplitter::extractPages()`	`string $pdfData`, `PageRange $range`	Trả về một dải dưới dạng các byte PDF độc lập	`string`	`InvalidArgumentException` khi thiếu header; `OverflowException` khi vi phạm guard closure	Đường dẫn này không có tham số mức trần
`PdfSplitter::mergeDocuments()`	`list<string> $pdfs`, `int $maxInputs = 100`, `int $maxBytesEach = 100_000_000`	Gộp các đầu vào theo thứ tự thành một PDF được đánh số lại	`MergeResult`	`InvalidArgumentException` khi danh sách rỗng hoặc đầu vào không phải PDF; `OverflowException` khi vi phạm guard về số lượng, kích thước mỗi đầu vào, hoặc closure	Từ 3.1.0; phiên bản đầu vào cao nhất quyết định header đầu ra
`SplitResult`	readonly `$segments`, `$ranges`, `$totalPages`	Mang các byte đoạn thô cùng metadata nguồn	—	—	Đối tượng giá trị `final readonly`
`SplitResult::count()`	—	Đếm các đoạn được tạo ra	`int`	—	—
`SplitResult::segment()`	`int $index`	Trả về các byte của một đoạn	`string`	`OutOfRangeException` khi chỉ số vượt ngoài phạm vi	Chỉ số bắt đầu từ 0
`PdfPortfolio::__construct()`	`string $viewMode = 'tile'`	Xác thực chế độ hiển thị lúc khởi tạo	—	`InvalidArgumentException` khi chế độ khác `tile`, `detail`, `hidden`	—
`PdfPortfolio::addSchema()`	`PortfolioField $field`	Thêm một cột schema	`self`	—	Fluent
`PdfPortfolio::addEntry()`	`PortfolioEntry $entry`	Thêm một mục tệp	`self`	—	Fluent
`PdfPortfolio::getSchema()`	—	Trả về các trường schema đã tích lũy	`list<PortfolioField>`	—	—
`PdfPortfolio::getEntries()`	—	Trả về các mục tệp đã tích lũy	`list<PortfolioEntry>`	—	—
`PdfPortfolio::count()`	—	Đếm các mục tệp	`int`	—	—
`PdfPortfolio::generateCollectionDictionary()`	—	Phát ra chuỗi từ điển Collection	`string`	—	Các khối schema và sort chỉ xuất hiện khi có trường
`PortfolioEntry`	`$filename`, `$data`, `$description = ''`, `$mimeType = 'application/octet-stream'`, `$customFields = []`	Đối tượng giá trị mục-tệp bất biến	—	—	`size()` trả về độ dài byte của dữ liệu
`PortfolioField`	`$name`, `PortfolioFieldType $type`, `$displayName = ''`, `$order = 0`, `$visible = true`	Đối tượng giá trị cột-schema bất biến	—	—	`effectiveDisplayName()` quay về `$name`
`PortfolioFieldType`	Enum chuỗi: `Text`, `Date`, `Number`, `FileName`, `Description`, `Size`, `ModDate`, `CreationDate`	Ánh xạ mỗi case tới một `/Subtype` PDF qua `pdfSubtype()`	`string` (`S`, `D`, `N`, `F`, `Desc`)	—	Các case kiểu ngày dùng chung subtype `D`; các case số dùng chung `N`

Chữ ký các điểm vào:

public function split(string $pdfData, array $ranges, int $maxBytes = 100_000_000, int $maxRanges = 1000): SplitResult

public function mergeDocuments(
    array $pdfs,
    int $maxInputs = 100,
    int $maxBytesEach = 100_000_000,
): MergeResult

public function __construct(
    private readonly string $viewMode = 'tile',
)

public function generateCollectionDictionary(): string

Hợp đồng hành vi

Việc tách và gộp dùng chung một pipeline đồ thị đối tượng:

Đầu vào phải bắt đầu bằng header %PDF. Các guard về kích thước và số lượng chạy trước khi phân tích và phát sinh OverflowException khi vi phạm.
Các trang lá được phát hiện bằng cách quét tìm các marker đối tượng trang; các nút cây trang bị loại khỏi phép đếm.
Bộ phân tích lập chỉ mục mọi đối tượng gián tiếp không nén bằng một lượt quét terminator có nhận biết stream. Lần xuất hiện đầu tiên của một object id sẽ thắng, nên các ghi đè từ cập nhật gia tăng không được áp dụng.
Các thuộc tính cây trang có thể kế thừa (/Resources, /MediaBox, /CropBox, /Rotate) được cụ thể hóa lên từng trang được trích bằng cách đi theo chuỗi /Parent của nó, nên các đoạn là tự chứa.
Bao đóng tham chiếu gián tiếp bắc cầu của mỗi trang được thu thập, loại trừ cạnh ngược /Parent, và được đánh số lại vào một không gian id liền kề mới.
Bộ tuần tự hóa phát ra header, Catalog, cây Pages, các đối tượng trang, và các đối tượng bao đóng, rồi một bảng cross-reference với các offset chính xác đến byte và một startxref trỏ tới từ khóa xref.
mergeDocuments lặp lại pipeline cho từng đầu vào vào một không gian id chung. Phiên bản PDF đầu vào cao nhất quyết định header đầu ra. Đây là bản thay thế đạt chuẩn cho bộ gộp của Core đã bị vô hiệu, vốn vẫn ở trạng thái fail-closed.
Đầu ra có tính tất định. Không phát ra dấu thời gian hay định danh ngẫu nhiên nào, nên đầu vào giống nhau cho ra các byte giống nhau.

Lắp ráp Portfolio:

Hàm khởi tạo xác thực chế độ hiển thị. Token /View được phát ra là /T, /D, hoặc /H tương ứng với tile, detail, và hidden.
generateCollectionDictionary() phát ra /Type /Collection, token /View, một khối /Schema khi có trường, và một chỉ thị /Sort trên trường schema đầu tiên, theo thứ tự tăng dần.
Mỗi trường schema phát ra /Subtype (từ pdfSubtype()), /N (tên hiển thị đã escape), /O (thứ tự), và /V (khả năng hiển thị).
Tên trường được làm sạch thành các name token PDF hợp lệ; các ký tự không phải chữ trở thành dấu gạch dưới. Các giá trị chuỗi được escape thành các chuỗi literal PDF.
Các mục tệp được lộ ra qua getEntries() để tầng ghi nhúng. Bản thân từ điển Collection chỉ mang view, schema, và sort.

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

Một dải không khớp trang nào cho ra một đoạn một-trang tối thiểu (MediaBox 612 x 792), không phải một lỗi.
Một tài liệu không có marker trang phát hiện được sẽ được tính là một trang.
Các trang lưu bên trong object stream không được phát hiện; chỉ các đối tượng gián tiếp không nén tham gia vào việc trích.
Khi tồn tại các object id trùng lặp, bản sửa có offset thấp nhất được dùng; các bản sửa cập nhật gia tăng về sau bị bỏ qua.
Bao đóng tham chiếu cho mỗi đoạn bị giới hạn ở 50,000 đối tượng; một đồ thị tự tham chiếu hoặc fan-out mang tính độc hại sẽ phát sinh OverflowException.
Các mức trần mặc định: đầu vào 100 MB, 1,000 dải, 100 đầu vào gộp. Tất cả đều có thể được bên gọi tinh chỉnh theo từng lần gọi.
splitEvery() từ chối kích thước đoạn nhỏ hơn 1 với InvalidArgumentException.
SplitResult::segment() từ chối chỉ số vượt ngoài phạm vi với OutOfRangeException.
Hai tên trường schema chỉ khác nhau ở dấu câu sẽ được làm sạch thành cùng một khóa từ điển; trường xuất hiện sau âm thầm che khuất trường trước trong schema được phát ra.
Module này không thực hiện thao tác mã hóa nào; chế độ FIPS không làm thay đổi hành vi của nó.

Tính phù hợp

Đầu ra đoạn và gộp tuân theo mô hình đối tượng trang của ISO 32000-2; nguồn chú thích các điều khoản liên quan. Các khẳng định có thể kiểm chứng từ bên ngoài:

Bố cục trailer, byte offset của startxref, và terminator %%EOF tuân theo ISO 32000-2:2020, §7.5.5 — reference ef0f2a4b563b84f81b3e6428612bc47c510d94fc8096849d339abf0f3247d845.
Các giá trị /View của từ điển Collection (/T, /D, /H) tuân theo ISO 32000-2:2020, §12.3.5 — reference 5cefaaeb40f3ff98e3aba135ac57c9424a05c43144c1b9b5156bfd4295e08ddd.
Các mục /Subtype, /N, /O, và /V của trường Collection tuân theo ISO 32000-2:2020, §12.3.5 (collection field dictionary) — reference 6300fbfdc8a913a8dc6f6ae34eff99f2bd03c4313a77777cdd5a8dd856d9537a.

Các phát biểu này mô tả năng lực đã được triển khai và được kiểm chứng bởi các test của module. Việc hỗ trợ một cấu trúc không phải là một khẳng định về tính phù hợp, và tính phù hợp không phải là chứng nhận; NextPDF không giữ chứng nhận bên thứ ba nào cho module này.

Ghi chú phát triển

Tất cả các lớp của module đều là final; các kiểu result và đối tượng giá trị đều là readonly. Các kiểu splitter và Portfolio có từ 1.9.0; mergeDocuments() được thêm vào ở 3.1.0.
PageRange và MergeResult là các kiểu của Core, nên các call site vẫn có thể chuyển đổi giữa các phiên bản.
Các trailer của đoạn chỉ mang /Size và /Root; không phát ra định danh tệp /ID hay từ điển /Info nào.
Đối với các quy trình cập nhật gia tăng hoặc ký, hãy chuyển các byte đoạn cho module Writer thay vì chỉnh sửa chúng tại chỗ về sau.
Module không ghi log nội dung tài liệu nào.

Ranh giới xuất bản

Trang này chỉ tài liệu hóa 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ộ, các lớp helper, các bảng cơ chế, tên tệp runbook, và các tiền tố ticket đều nằm ngoài phạm vi.