Tài liệu

Tổng quan nhanh

Module Document tách một PDF thành các phân đoạn theo dải trang và lắp ráp các PDF Portfolio (Collection) với các cột schema có thể sắp xếp. Cả hai thao tác đều được giới hạn để 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 envelope 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. Document là một phần của phiên bản Pro, không có cờ giấy phép riêng theo từng tính năng. So sánh các phiên bản và nhận giấy phép.

Cài đặt

composer require nextpdf/pro:^3

Mã nằm dưới namespace NextPDF\Pro\Document.

Tổng quan khái niệm

Có hai năng lực được cung cấp:

• PdfSplitter trích xuất các dải trang thành các phân đoạn PDF độc lập. Nó phát hiện các trang bằng cách quét các page object trong đầu vào thô và bọc các trang đã chọn trong một catalog và page tree tối thiểu. Nó hỗ trợ tách theo dải, tách theo kích thước cố định (splitEvery) và trích xuất một dải đơn (extractPages).
• PdfPortfolio xây dựng một dictionary PDF Collection tổng hợp các tệp đính kèm theo một schema đã định nghĩa. Nó hỗ trợ các chế độ xem tile, detail và hidden, và phát ra một dictionary phù hợp để đưa vào catalog của tài liệu.

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

Tách một PDF không phải là cắt byte. Một page object tham chiếu đến các tài nguyên dùng chung, font và content stream bằng tham chiếu gián tiếp. Nó cũng kế thừa /MediaBox và /Resources từ các tổ tiên trong page tree. Vì vậy bộ tách tái dựng mỗi phân đoạn thành một đồ thị đối tượng tự chứa: nó đi qua bao đóng tham chiếu bắc cầu của các trang đã chọn, hiện thực hóa các thuộc tính kế thừa, đánh số lại vào một không gian id mới, và ghi một bảng cross-reference với các offset chính xác đến từng byte. Việc đi qua bao đóng được giới hạn, vì một đồ thị fan-out thù địch nếu không sẽ kéo lượng công việc không giới hạn vào một phân đoạn. Kết quả mở ra như một PDF độc lập hợp lệ, chứ không phải một mảnh vỡ với các tham chiếu treo lơ lửng.

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

Hợp đồng hành vi

• PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) áp đặt một giới hạn kích thước đầu vào và một giới hạn số lượng dải, và từ chối đầu vào không bắt đầu bằng header PDF.
• splitEvery($pdfData, $pagesPerSegment) từ chối một kích thước phân đoạn dưới 1; phân đoạn cuối có thể chứa ít trang hơn.
• PdfPortfolio từ chối bất kỳ chế độ xem nào khác ngoài tile, detail hoặc hidden tại thời điểm khởi tạo.
• addSchema() và addEntry() trả về portfolio để xâu chuỗi theo kiểu fluent; generateCollectionDictionary() trả về chuỗi dictionary Collection.
• Tên trường schema được làm sạch để dùng làm PDF name object; các giá trị chuỗi được escape cho các chuỗi literal của PDF.

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

Phần sau phản ánh API công khai đã được ghi tài liệu. Kho không cung cấp một ví dụ chạy được cho module này.

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$result = (new PdfSplitter())->split($pdfBytes, [new PageRange(1, 5)]);

Mẫu mã — Production

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$splitter = new PdfSplitter();

try {
    $result = $splitter->split(
        $pdfBytes,
        [new PageRange(1, 10), new PageRange(11, 20)],
        maxBytes: 50_000_000,
        maxRanges: 100,
    );
} catch (\InvalidArgumentException $e) {
    // Input rejected (not a PDF, or limits exceeded).
}

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

• Bộ tách tái dựng mỗi phân đoạn thành một đồ thị đối tượng mới với một bảng cross-reference thật, chính xác đến từng byte; các phân đoạn là các PDF độc lập hợp lệ. Nó đánh số lại vào một không gian id mới thay vì giữ nguyên bố trí byte của nguồn, nên hãy chuyển các byte phân đoạn cho module Writer cho các luồng cập nhật gia tăng hoặc ký.
• Một dải không khớp với trang nào sẽ cho ra một phân đoạn một-trang tối thiểu thay vì một lỗi.
• Việc sắp xếp portfolio mặc định theo trường schema đầu tiên, tăng dần.

Hiệu năng

Việc tách và lắp ráp portfolio là tuyến tính theo kích thước đầu vào và số lượng mục. Mức trần đầu vào mặc định là 100 MB và mức trần dải mặc định là 1000; cả hai đều có thể được bên gọi điều chỉnh giảm. Hãy đo lường với các tài liệu đại diện.

Ghi chú về bảo mật

Hãy xem đầu vào là không tin cậy. Các bảo vệ về kích thước và số lượng giới hạn việc sử dụng tài nguyên. Module làm sạch tên trường và escape các giá trị chuỗi trước khi chúng đến dictionary đầu ra. Nó không ghi log nội dung tài liệu nào.

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

Dictionary Portfolio tuân theo mô hình PDF Collections và bộ tách tuân theo mô hình page-object được định nghĩa bởi ISO 32000-2; phần nguồn chú thích các điều khoản liên quan. Kho dữ liệu RAG không khả dụng tại thời điểm soạn thảo, nên trang này không khẳng định mã định danh điều khoản ngoài nào và giới hạn các tuyên bố về sự phù hợp ở những hành vi đã được các kiểm thử của module xác minh.

Ghi chú ranh giới Enterprise

Enterprise không thay đổi hành vi của Document. Enterprise bổ sung các tính năng lưu trữ và tuân thủ bậc cao hơn được ghi tài liệu riêng; chúng không bắt buộc cho việc tách hay lắp ráp Portfolio.

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

Nếu không có Pro, hãy dùng các nguyên thủy tài liệu cơ sở của NextPDF Core; việc tách theo dải trang và lắp ráp Portfolio là các bổ sung của Pro. Xem /modules/document/.

Ranh giới công bố

Trang này chỉ ghi tài liệu về 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.

Xem thêm

• Document — Tham chiếu chuyên sâu
• Writer
• Merge
• Output Pipeline