Writer

Кратко

Модуль Writer дописывает к PDF ревизии инкрементального обновления и упаковывает малые объекты в Object Stream. Инкрементальный writer применяет правило «только дописывание»: байты, существовавшие до ревизии, не должны меняться.

Доступность и лицензирование

Эта возможность поставляется в составе NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без этого права доступа не загружает классы возможности. Сравните редакции и получите лицензию. Отдельного флага лицензии на конкретную функцию нет; код поставляется с редакцией Pro.

Установка

composer require nextpdf/pro:^3

Код находится в пространстве имён NextPDF\Pro\Writer.

Концептуальный обзор

Предоставляются две возможности:

• IncrementalUpdateWriter пишет новую ревизию. Он перезаписывает каталог с объединёнными записями, дописывает традиционную таблицу перекрёстных ссылок для новых и изменённых объектов и пишет трейлер, ссылающийся на предыдущую ревизию. Он применяет правило «только дописывание» в режиме fail-closed.
• ObjectStreamWriter группирует малые объекты в один сжатый Object Stream. Это уменьшает размер таблицы перекрёстных ссылок и улучшает сжатие. Он отклоняет объекты, которые превысили бы максимальный размер потока, и отклоняет пустой поток.

Правило «только дописывание» защищает существующие подписи. Каждый байт, который буфер хранил до ревизии, должен появиться неизменным на той же позиции после ревизии. Если хоть один более ранний байт изменился, writer возбуждает ошибку и не формирует вывода.

Почему это работает именно так

Несущее решение — где размещён гейт «только дописывание». Он находится на уровне writer, а не только в оркестраторах более высокого уровня, поэтому каждый нынешний и будущий вызывающий код наследует fail-closed-покрытие. Проверка — это чистое сравнение префикса на равенство: writer делает снимок префикса буфера перед дописыванием, а затем подтверждает, что каждый более ранний байт остался неизменным. Это защищает любую подпись, чей /ByteRange покрывал префикс, поскольку один изменённый байт незаметно сделал бы её недействительной. Новую ревизию несут традиционные таблицы перекрёстных ссылок и указатель /Prev, потому что инкрементальные обновления должны дописывать, а не переписывать. Стоимость проверки линейна по размеру существующего префикса, и эта стоимость принимается намеренно: целостность подписанных байтов важнее второй копии.

Проектный контекст: Инкрементальные обновления и почему они важны.

Контракт поведения

• IncrementalUpdateWriter::writeRevision(...) возвращает байтовое смещение новой таблицы перекрёстных ссылок, чтобы можно было сцеплять дальнейшие ревизии.
• Writer проверяет, что исходный префикс побайтово равен до и после записи. Расхождение возбуждает исключение writer, несущее состояние нарушения правила «только дописывание».
• Новая ревизия использует традиционную таблицу перекрёстных ссылок и трейлер с указателем /Prev; смешивание таблиц и потоков между ревизиями разрешено.
• ObjectStreamWriter::addObject() возбуждает ошибку переполнения, когда добавление объекта превысило бы максимальный размер потока (65 536 байт без сжатия для индекса плюс тела).
• ObjectStreamWriter::build() возбуждает ошибку, когда не было добавлено ни одного объекта; в противном случае он возвращает сжатое содержимое Object Stream.

Пример кода — быстрый старт

Следующее отражает документированный публичный API. Репозиторий не поставляет работающего примера для этого модуля.

use NextPDF\Pro\Writer\ObjectStreamWriter;

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

Пример кода — продакшн

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.

Граничные случаи и подводные камни

• Проверка «только дописывание» копирует существующий префикс. Стоимость растёт с размером уже записанного документа. Эта стоимость преднамеренна и защищает подписанные байты.
• Предел размера Object Stream — на совокупный индекс и тело до сжатия. Группируйте объекты соответственно.
• Object Stream не должен содержать определённые типы объектов (например, словарь шифрования). Размещайте их как прямые косвенные объекты.

Производительность

Проверка «только дописывание» линейна по размеру существующего префикса документа. Упаковка Object Stream уменьшает размер перекрёстных ссылок и улучшает сжатие ценой одного дополнительного прохода сжатия. Опубликованного показателя пропускной способности нет. Измеряйте на представительных документах.

Замечания по безопасности

Инкрементальный writer работает в режиме fail-closed. Если путь кода изменил бы байт, покрытый более ранней подписью, writer возбуждает ошибку вместо того, чтобы сформировать документ. Это защищает целостность подписи для процессов со сцеплением ревизий. Никакое содержимое документа не журналируется.

Соответствие

Источник аннотирует грамматику инкрементального обновления и модель Object Stream в ISO 32000-2, а также требования к сцеплению ревизий в профиле PAdES ETSI EN 319 142-1. Поскольку корпус RAG был недоступен на момент написания, на этой странице повторяются только ссылки на пункты, объявленные самим источником, и не утверждаются дополнительные внешние идентификаторы пунктов.

Замечание о границе Enterprise

Enterprise добавляет возможности жизненного цикла подписи более высокого уровня (долгосрочная проверка и обновление), которые надстраиваются над инкрементальными обновлениями на уровне поведения. Модуль Writer предоставляет только примитив ревизии; эти возможности более высокого уровня документируются отдельно и не требуются для записи ревизии.

Резервный режим Core / альтернатива

Без Pro используйте базовый writer из NextPDF Core; ревизии инкрементального обновления с гейтом «только дописывание» и упаковкой Object Stream — это дополнения Pro. См. /modules/writer/.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую поверхность публичного API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов выходят за рамки.

См. также

• Writer — глубокий справочник
• Document
• Optimizer
• Output Pipeline