Pro phiên bản

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

Tổng quan nhanh

Module Writer ghi các revision incremental-update của PDF và đóng gói các đối tượng nhỏ vào Object Stream. Trình ghi incremental thực thi một quy tắc chỉ-thêm (append-only) đóng-khi-lỗi: mọi byte mà buffer nắm giữ trước một revision phải giữ nguyên không đổi sau đó. Trình dựng Object Stream nhóm các đối tượng đủ điều kiện vào một đối tượng /Type /ObjStm được nén bằng FlateDecode dưới một kích thước có giới hạn.

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

Khả năng này đi kèm trong NextPDF Pro (nextpdf/pro) và kích hoạt với một license envelope tầng Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của khả năng 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 theo từng tính năng; mã đi kèm với phiên bản Pro.

Bề mặt API công khai

Module nằm dưới namespace NextPDF\Pro\Writer. Tất cả các ký hiệu công khai được liệt kê bên dưới. Các value object là các lớp final readonly bất biến.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`IncrementalUpdateWriter::writeRevision`	`BinaryBuffer $buffer, ObjectRegistry $registry, int $prevXrefOffset, int $catalogObject, array $catalogEntries, array $catalogUpdates, array $newObjectNumbers, string $fileId`	Tĩnh. Ghi lại catalog với các mục đã gộp, chèn 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 với `/Size`, `/Root`, `/Prev`, và `/ID`. Sau đó xác minh tiền tố trước-revision là bằng nhau theo byte.	`int` — byte offset của bảng tham chiếu chéo mới	`\NextPDF\Exception\WriterException` khi phép kiểm tra tiền tố chỉ-thêm thất bại; `getWriterState()` trả về `dss-append-only-invariant`	Điểm vào tĩnh. Không có đầu ra dùng được khi vi phạm.
`ObjectStreamWriter::addObject`	`int $objectNumber, string $content`	Chèn thêm một đối tượng vào stream đang chờ sau khi kiểm tra kích thước.	`void`	`OverflowException` khi index cộng body kết hợp lại vượt quá 65.536 byte	`$content` không bao gồm các lớp bao `N 0 obj` / `endobj`.
`ObjectStreamWriter::canAccept`	`string $content`	Ước lượng chi phí index và kiểm tra tổng đang chạy so với mức tối đa.	`bool`	Không ném ra	Vị từ thuần túy; không thay đổi trạng thái.
`ObjectStreamWriter::build`	không có	Dựng index, nối các body, nén bằng FlateDecode, và bao từ điển `/Type /ObjStm`.	`string` — nội dung Object Stream thô	`ObjectStreamWriteException` khi không có đối tượng nào được thêm, hoặc khi nén zlib thất bại	Bên gọi gán số đối tượng và bao các marker.
`ObjectStreamWriter::getEntries`	không có	Tính lại các offset tương đối với body cho các đối tượng đã tích lũy.	`list<ObjectStreamEntry>`	Không ném ra	Các offset là tương đối với phần body.
`ObjectStreamWriter::count`	không có	Báo cáo số lượng đối tượng đã tích lũy.	`int`	Không ném ra	—
`ObjStmCompressor::__construct`	`int $maxStreamSize = 65536, int $maxObjectsPerStream = 200`	Lưu các giới hạn kích thước và số lượng đối tượng dùng cho việc nhóm.	—	Không ném ra	Các mặc định khớp với việc tinh chỉnh Object Stream của module.
`ObjStmCompressor::groupObjects`	`list<array{number: int, generation?: int, content: string}> $objects`	Lọc các đối tượng không đủ điều kiện, rồi đóng gói phần còn lại vào các writer trong giới hạn kích thước và số lượng.	`list<ObjectStreamWriter>`	Không ném ra; các đối tượng không đủ điều kiện bị bỏ qua	Các đối tượng có generation khác không được chuyển sang tuần tự hóa thông thường.
`ObjStmCompressor::isEligible`	`string $content, int $generation = 0`	Từ chối các đối tượng stream, `/Encrypt`, `/XRef`, `/Catalog`, và mọi generation khác không.	`bool`	Không ném ra	Việc so khớp `/Type` khoan dung với khoảng trắng và escape `#xx`.
`ObjStmCompressor::writeToBuffer`	`list<ObjectStreamWriter> $streams, BinaryBuffer $buffer, ObjectRegistry $registry`	Cấp phát một đối tượng vận chuyển cho mỗi stream, đăng ký các mục nén type-2, và ghi mỗi khối ObjStm.	`list<int>` — các số đối tượng vận chuyển	Truyền `ObjectStreamWriteException` từ `build()` khi hiếm hoi có lỗi nén	Chạy sau khi các đối tượng không đủ điều kiện được ghi và trước khi tham chiếu chéo được phát ra.
`ObjStmCompressor::estimateSavings`	`list<ObjectStreamWriter> $streams, int $originalSize`	Dựng mỗi stream để đo kích thước đã nén so với bản gốc.	`ObjStmCompressionResult`	Truyền `ObjectStreamWriteException` từ `build()` khi hiếm hoi có lỗi nén	Trình trợ giúp đo lường chỉ-đọc.
`ObjectStreamEntry::__construct`	`int $objectNumber, string $content, int $offset`	Bản ghi bất biến của một đối tượng đã đóng gói và offset body của nó.	—	Không ném ra	`final readonly`; các thuộc tính public.
`ObjStmCompressionResult::__construct`	`int $originalObjectCount, int $streamCount, int $estimatedOriginalSize, int $estimatedCompressedSize`	Bộ chứa số liệu bất biến.	—	Không ném ra	`final readonly`; các thuộc tính public.
`ObjStmCompressionResult::savedBytes`	không có	Trả về kích thước gốc trừ đi kích thước đã nén.	`int`	Không ném ra	Có thể âm khi việc đóng gói làm dữ liệu phình ra.
`ObjStmCompressionResult::savedPercent`	không có	Trả về phần trăm giảm.	`float`	Không ném ra	Trả về `0.0` khi kích thước gốc bằng không.
`ObjStmCompressionResult::compressionRatio`	không có	Trả về kích thước đã nén trên kích thước gốc.	`float`	Không ném ra	Trả về `1.0` khi kích thước gốc bằng không.
`ObjectStreamWriteException`	—	Báo hiệu một lỗi dựng Object Stream.	—	Kế thừa `RuntimeException`	Được ném bởi `build()`; có thể bắt qua `RuntimeException` để tương thích ngược.

Chữ ký điểm vào

final class IncrementalUpdateWriter
{
    public static function writeRevision(
        BinaryBuffer $buffer,
        ObjectRegistry $registry,
        int $prevXrefOffset,
        int $catalogObject,
        array $catalogEntries,
        array $catalogUpdates,
        array $newObjectNumbers,
        string $fileId,
    ): int;
}

final class ObjectStreamWriter
{
    public function addObject(int $objectNumber, string $content): void;
    public function canAccept(string $content): bool;
    public function build(): string;
    /** @return list<ObjectStreamEntry> */
    public function getEntries(): array;
    public function count(): int;
}

final class ObjStmCompressor
{
    public function __construct(
        int $maxStreamSize = 65536,
        int $maxObjectsPerStream = 200,
    );

    /**
     * @param list<array{number: int, generation?: int, content: string}> $objects
     * @return list<ObjectStreamWriter>
     */
    public function groupObjects(array $objects): array;

    public function isEligible(string $content, int $generation = 0): bool;

    /**
     * @param list<ObjectStreamWriter> $streams
     * @return list<int>
     */
    public function writeToBuffer(array $streams, BinaryBuffer $buffer, ObjectRegistry $registry): array;

    /** @param list<ObjectStreamWriter> $streams */
    public function estimateSavings(array $streams, int $originalSize): ObjStmCompressionResult;
}

Hợp đồng hành vi

writeRevision ghi một revision incremental-update. Nó chụp ảnh tiền tố buffer hiện có trước khi ghi. Nó ghi lại catalog với các mục đã gộp, đăng ký các offset đối tượng mới, ghi một bảng tham chiếu chéo truyền thống được nhóm thành các phần con liền kề, và ghi một trailer với /Size, /Root, /Prev, và /ID. Sau khi ghi, nó so sánh lại tiền tố. Nếu bất kỳ byte trước đó nào thay đổi, nó làm phát sinh WriterException mang theo trạng thái vi-phạm-chỉ-thêm và không trả về đầu ra dùng được. Khi thành công, nó trả về byte offset của bảng tham chiếu chéo mới để xâu chuỗi thêm các revision. Việc trộn lẫn các bảng tham chiếu chéo và stream qua các revision được cho phép.

ObjectStreamWriter tích lũy các đối tượng. addObject làm phát sinh một lỗi tràn khi index và body kết hợp lại vượt quá mức tối đa 65.536 byte chưa nén. build làm phát sinh một lỗi trên một stream rỗng; ngược lại nó nén index cộng với body và trả về nội dung Object Stream với các mục /Type /ObjStm, /N, /First, /Length, và /Filter /FlateDecode. Bên gọi gán số đối tượng và bao các marker N 0 obj / endobj.

ObjStmCompressor quyết định đối tượng nào để đóng gói. Nó loại trừ các đối tượng stream, các từ điển mã hóa, các stream tham chiếu chéo, catalog tài liệu, và mọi đối tượng có số generation khác không. writeToBuffer cấp phát một đối tượng vận chuyển cho mỗi stream, đăng ký mỗi đối tượng đã đóng gói như một mục tham chiếu chéo nén type-2, và ghi khối ObjStm tại offset buffer hiện tại. estimateSavings dựng mỗi stream để tính các số liệu kích thước mà không làm thay đổi buffer.

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

Phép kiểm tra chỉ-thêm sao chép tiền tố hiện có. Chi phí của nó 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 Object Stream áp dụng cho index cộng body chưa nén. Hãy đặt từ điển mã hóa và các kiểu đối tượng bị loại trừ khác làm các đối tượng gián tiếp trực tiếp.
Việc loại trừ /Type khoan dung với khoảng trắng giữa các token bất kỳ và escape hex #xx. Các dạng như /Type /Encrypt, /Type\n/Encrypt, và /Type /#45ncrypt đều bị từ chối, không chỉ riêng cách viết chuẩn tắc theo mặt chữ.
Bất kỳ đối tượng nào mang số generation khác không đều được coi là không đủ điều kiện và chuyển sang tuần tự hóa N G obj … endobj thông thường, vì generation của một đối tượng đã nén ngầm định bằng không.
writeToBuffer phải chạy sau khi tất cả các đối tượng không đủ điều kiện đã được ghi và trước khi tham chiếu chéo được phát ra. Các đối tượng đã đóng gói không được đồng thời tuần tự hóa riêng.

Hành vi ở chế độ FIPS

Module Writer không thực hiện thao tác mã hóa nào. Nó bảo vệ các byte đã ký bằng cách từ chối phát ra khi một byte trước đó sẽ thay đổi, đây là một phép kiểm tra bằng-nhau theo byte chứ không phải phép kiểm tra mã hóa. Việc chọn thuật toán FIPS cho ký và băm được điều chỉnh bởi module ký, không phải bởi writer này. Việc bật hay tắt chế độ FIPS không làm thay đổi hành vi của bất kỳ phương thức Writer nào.

Tính phù hợp

NextPDF triển khai module theo ISO 32000-2:2020. Trình ghi incremental tuân theo ngữ pháp incremental-update §7.5.6: mỗi revision chèn thêm một phần tham chiếu chéo chỉ bao gồm các đối tượng mới, đã thay đổi, hoặc đã xóa, và một trailer mà mục /Prev của nó cho offset của tham chiếu chéo trước đó. Trình dựng Object Stream tuân theo mô hình object-stream §7.5.7: một index gồm các cặp số-đối-tượng và offset, với các offset được đo từ mục /First theo thứ tự tăng dần, đứng trước các body đối tượng đã đóng gói. Cả hai tham chiếu điều khoản đều được kiểm chứng đối chiếu với kho ngữ liệu ISO 32000-2:2020. Việc xâu chuỗi revision cho các quy trình PAdES B-LT và B-LTA tuân theo ETSI EN 319 142-1 §5.4, như đã chú giải trong mã nguồn. Việc hỗ trợ một điều khoản là một tuyên bố năng lực kỹ thuật, không phải một chứng nhận; NextPDF không nắm giữ chứng nhận phù hợp chính thức nào.

Ghi chú phát triển

Cài đặt gói bằng composer require nextpdf/pro:^3. Các lớp phân giải dưới NextPDF\Pro\Writer.
IncrementalUpdateWriter::writeRevision là một điểm vào tĩnh; nó không giữ trạng thái instance nào giữa các revision.
ObjectStreamEntry, ObjStmCompressionResult, IncrementalUpdateWriter, và compressor cùng nhau tạo thành bề mặt công khai của module; kho lưu trữ không đi kèm ví dụ chạy được nào cho nó.
Một WriterException từ writeRevision cho biết một vi phạm chỉ-thêm. Hãy coi đó là một lỗi nghiêm trọng và loại bỏ buffer.
Các đối tượng vận chuyển Object Stream là các đối tượng gián tiếp; bên gọi gán số đối tượng của chúng thông qua registry.

Ranh giới xuất bản

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