Pro редакция

Projection

Краткий обзор

Projection разбирает поток содержимого PDF в плоский список токенов и выдаёт из этих токенов новый поток содержимого. Выдача требует явно объявленного намерения. Этот модуль не является PDF-редактором общего назначения.

Примечание. «Projection» здесь означает проекцию токенов потока содержимого. Это не координатная или геопространственная проекция. О геопространственных возможностях см. модуль Geo.

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

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

Отдельного пофункционального лицензионного флага нет. Обязательный аргумент ProjectionIntent ограничивает выдачу на уровне API, а не лицензионным переключателем.

Установка

composer require nextpdf/pro:^3

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

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

ContentProjectionWriter предоставляет три статические операции:

tokenize() разбирает поток содержимого в плоский упорядоченный список токенов. Это только чтение и не требует намерения.
emit() записывает новый поток содержимого из (возможно изменённого) списка токенов. Он требует ProjectionIntent.
roundTrip() токенизирует, затем повторно выдаёт без изменений — для валидации.

Вывод концептуально является новым потоком содержимого, а не отредактированной копией оригинала. Эмиттер нормализует пробельные символы и комментарии, но сохраняет последовательность операторов и значения операндов в точности. Перечисление намерения имеет ровно два случая — санитизацию (редактирование) и стеганографическое встраивание — и намеренно не имеет общего случая, чтобы статический анализ мог обнаружить непреднамеренное использование.

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

Projection отказывается быть PDF-редактором общего назначения. Выдача заново строит свежий поток содержимого из плоского списка токенов, поэтому оригинал никогда не изменяется на месте. Именно эта односторонняя модель делает редактирование заслуживающим доверия: удалённые токены отсутствуют в выводе, а не закрашены поверх. Поэтому emit() требует явного ProjectionIntent, а перечисление предлагает только санитизацию и стеганографическое встраивание — без общего случая. Тогда статический анализ может отметить любую выдачу, у которой нет объявленной, известной цели. Этот подход жертвует удобством редактирования ради гарантии того, что разрушительное намерение всегда видно в точке вызова.

Проектная предыстория: Редактирование — это не чёрный прямоугольник.

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

tokenize($contentStream) возвращает список токенов, охватывающих строки, имена, числа, массивы, словари, булевы значения, null и операторы.
emit($tokens, $intent) требует явного намерения; система типов обеспечивает это в точке вызова.
Вывод roundTrip() не байт-идентичен входу, но последовательность операторов и значения операндов совпадают.
Эмиттер форматирует числа так, чтобы сохранить различие между целым и числом с плавающей точкой, и повторно экранирует литеральные строки.
Два объявленных намерения — это санитизация (разрушительная, необратимая операция редактирования) и стеганографическое встраивание.

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

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

use NextPDF\Pro\Projection\ContentProjectionWriter;

$tokens = ContentProjectionWriter::tokenize($contentStream);

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

use NextPDF\Pro\Projection\ContentProjectionWriter;
use NextPDF\Pro\Projection\ProjectionIntent;

$tokens = ContentProjectionWriter::tokenize($contentStream);

// Validate first: a clean round-trip must hold before any modification.
$check = ContentProjectionWriter::roundTrip($contentStream);

// Apply your modification to $tokens, then emit with a declared intent.
$output = ContentProjectionWriter::emit($tokens, ProjectionIntent::Sanitization);

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

Запустите roundTrip() и убедитесь, что он проходит, прежде чем доверять последовательности «изменить и выдать». Считайте неудавшийся круговой проход условием остановки.
Намерение санитизации необратимо. Удалённое содержимое нельзя восстановить из вывода.
Эмиттер нормализует пробельные символы и отбрасывает комментарии, поэтому побайтовое сравнение с оригиналом будет различаться даже для неизменённого кругового прохода.

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

Токенизация и выдача линейны по длине потока содержимого. Токенизатор ограничивает чтение восьмеричных escape-последовательностей и обработку шестнадцатеричных строк. Опубликованного показателя пропускной способности нет. Измеряйте на репрезентативных потоках содержимого.

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

Обязательный аргумент намерения предотвращает использование не по назначению как редактора общего назначения. Намерение санитизации разрушительно и необратимо; сначала проверьте круговой проход и подтвердите отредактированный вывод перед распространением. Этот модуль не журналирует содержимое.

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

Токенизация следует лексическим и связанным с потоком содержимого соглашениям из ISO 32000-2; источник аннотирует соответствующие пункты. На момент написания корпус RAG был недоступен, поэтому эта страница не утверждает внешних идентификаторов пунктов и ограничивает заявления о соответствии поведением, проверенным тестами модуля.

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

Enterprise не меняет поведение Projection. Enterprise добавляет возможности конфиденциальности и соответствия требованиям более высокого уровня, документированные отдельно; они не требуются для использования API проекции.

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

Эквивалента в Core нет. Без Pro вызывающие стороны должны строить собственный токенизатор потока содержимого; ограниченная по намерению модель проекции — дополнение, доступное только в Pro.

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

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