Writer

Tổng quan nhanh

Module Writer thêm các revision incremental-update vào một PDF và đóng gói các đối tượng nhỏ vào các Object Stream. Bộ writer incremental thực thi một quy tắc chỉ-thêm (append-only): các byte đã tồn tại trước revision không được thay đổi.

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. Không có cờ giấy phép riêng theo từng tính năng; mã được phát hành cùng phiên bản Pro.

Cài đặt

composer require nextpdf/pro:^3

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

Tổng quan khái niệm

Hai năng lực được cung cấp:

• IncrementalUpdateWriter ghi một revision mới. Nó ghi lại catalog với các mục đã gộp, thêm một bảng tham chiếu chéo truyền thống cho các đối tượng mới và đã sửa đổi, và ghi một trailer liên kết tới revision trước đó. Nó thực thi một quy tắc chỉ-thêm fail-closed.
• ObjectStreamWriter nhóm các đối tượng nhỏ vào một Object Stream nén duy nhất. Điều này làm giảm kích thước bảng tham chiếu chéo và cải thiện độ nén. Nó từ chối các đối tượng sẽ vượt quá kích thước stream tối đa và từ chối một stream rỗng.

Quy tắc chỉ-thêm bảo vệ các chữ ký hiện có. Mỗi byte mà buffer đã giữ trước revision phải xuất hiện không thay đổi ở cùng vị trí sau revision. Nếu bất kỳ byte trước đó nào thay đổi, writer làm phát sinh một lỗi và không tạo ra đầu ra.

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

Lựa chọn chịu tải là nơi đặt cổng chỉ-thêm. Nó nằm ở phạm vi writer, không chỉ trong các bộ điều phối cấp cao hơn, nên mọi caller hiện tại và tương lai đều thừa hưởng phạm vi bao phủ fail-closed. Phép kiểm tra là một bài kiểm tra bằng-nhau-tiền-tố thuần túy: writer chụp lại tiền tố buffer trước khi thêm, rồi xác nhận mọi byte trước đó không thay đổi sau đó. Điều này bảo vệ bất kỳ chữ ký nào có /ByteRange bao trùm tiền tố, vì một byte bị thay đổi sẽ âm thầm làm nó vô hiệu. Các bảng tham chiếu chéo truyền thống và một con trỏ /Prev mang theo revision mới, bởi các incremental update phải thêm chứ không ghi lại. Chi phí xác minh tuyến tính theo tiền tố hiện có, và chi phí đó được chấp nhận có chủ đích: tính toàn vẹn của byte đã ký được ưu tiên hơn một bản sao thứ hai.

Bối cảnh thiết kế: Incremental update và vì sao chúng quan trọng.

Hợp đồng hành vi

• IncrementalUpdateWriter::writeRevision(...) trả về byte offset của bảng tham chiếu chéo mới, để bạn có thể xâu chuỗi thêm các revision.
• Writer xác minh tiền tố gốc là byte-equal trước và sau khi ghi. Một sai lệch làm phát sinh một writer exception mang theo một trạng thái vi-phạm-chỉ-thêm.
• Revision mới dùng một bảng tham chiếu chéo truyền thống và một trailer với một con trỏ /Prev; việc trộn lẫn các bảng và stream qua các revision được cho phép.
• ObjectStreamWriter::addObject() làm phát sinh một lỗi tràn khi việc thêm một đối tượng sẽ vượt quá kích thước stream tối đa (65.536 byte chưa nén cho index cộng body).
• ObjectStreamWriter::build() làm phát sinh một lỗi khi không có đối tượng nào được thêm; ngược lại nó trả về nội dung Object Stream đã nén.

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

Đoạn sau phản ánh API công khai đã được ghi tài liệu. Kho mã không kèm theo một ví dụ chạy được cho module này.

use NextPDF\Pro\Writer\ObjectStreamWriter;

$writer = new ObjectStreamWriter();
$writer->addObject(10, $serializedObjectBody);
$objStm = $writer->build();

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

use NextPDF\Pro\Writer\IncrementalUpdateWriter;

$newXrefOffset = IncrementalUpdateWriter::writeRevision(
    $buffer,
    $registry,
    $prevXrefOffset,
    $catalogObject,
    $catalogEntries,
    $catalogUpdates,
    $newObjectNumbers,
    $fileId,
);
// A WriterException here means the append-only rule was violated.
// Treat it as a hard failure; do not emit the output.

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

• Phép kiểm tra chỉ-thêm sao chép tiền tố hiện có. Chi phí tăng theo kích thước của tài liệu đã được ghi. Chi phí này là có chủ đích và bảo vệ các byte đã ký.
• Giới hạn kích thước Object Stream áp dụng cho index và body kết hợp trước khi nén. Hãy nhóm các đối tượng cho phù hợp.
• Các Object Stream không được chứa một số kiểu đối tượng nhất định (ví dụ, từ điển mã hóa). Hãy đặt những đối tượng đó làm các đối tượng gián tiếp trực tiếp.

Hiệu năng

Việc xác minh chỉ-thêm tuyến tính theo kích thước của tiền tố tài liệu hiện có. Việc đóng gói Object Stream làm giảm kích thước tham chiếu chéo và cải thiện độ nén với chi phí một lượt nén thêm. Không có con số thông lượng nào được công bố. Hãy đo bằng các tài liệu đại diện.

Lưu ý bảo mật

Bộ writer incremental là fail-closed. Nếu một đường dẫn mã sẽ thay đổi một byte mà một chữ ký trước đó bao trùm, writer làm phát sinh một lỗi thay vì tạo ra một tài liệu. Điều này bảo vệ tính toàn vẹn của chữ ký cho các quy trình xâu chuỗi revision. Không có nội dung tài liệu nào được ghi nhật ký.

Tính phù hợp

Mã nguồn chú giải ngữ pháp incremental-update và mô hình Object Stream trong ISO 32000-2 và các yêu cầu xâu chuỗi revision trong hồ sơ PAdES của ETSI EN 319 142-1. Vì kho ngữ liệu RAG không khả dụng tại thời điểm soạn thảo, trang này chỉ lặp lại các tham chiếu điều khoản mà chính mã nguồn khai báo và không khẳng định định danh điều khoản bên ngoài bổ sung nào.

Lưu ý về ranh giới Enterprise

Enterprise bổ sung các tính năng vòng đời chữ ký bậc cao hơn (xác thực dài hạn và gia hạn) được xây dựng trên các incremental update ở mức hành vi. Module Writer chỉ cung cấp nguyên hàm revision; những tính năng bậc cao hơn đó được ghi tài liệu riêng và không bắt buộc để ghi một revision.

Phương án dự phòng / thay thế của Core

Nếu không có Pro, hãy dùng bộ writer cơ bản của NextPDF Core; các revision incremental-update với cổng chỉ-thêm và việc đóng gói Object Stream là các bổ sung của Pro. Xem /modules/writer/.

Ranh giới công bố

Trang này chỉ ghi tài liệu 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 nằm ngoài phạm vi.

Xem thêm

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