AST

Кратко

Модуль AST превращает PDF в неизменяемое, навигируемое дерево документа. Он использует дерево тегированной структуры, когда оно присутствует, и возвращается к эвристическому конструктору для нетегированных документов, прикрепляя к каждому узлу ограничивающие прямоугольники и текст.

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

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

Отдельного флага лицензии для каждой функции не существует. Код поставляется с редакцией Pro; поведением построения полностью управляет AstBuildOptions (ограничения ресурсов и диапазоны страниц), а не лицензионный переключатель.

Установка

composer require nextpdf/pro:^3

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

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

AstBuilder оркестрирует конвейер «PDF в дерево»: проверить кеш, рано отклонить зашифрованный вход, прочитать дерево структуры для тегированных PDF, иначе перейти к нетегированному пути, прикрепить ограничивающие прямоугольники из анализа потока содержимого, затем закешировать результат. Выход — это AstDocument, узлы которого неизменяемы; обновления реконструируют затронутое поддерево снизу вверх, а не изменяют его на месте.

Для нетегированных PDF существуют две резервные стратегии: голый резервный путь и необязательный эвристический конструктор (AstBuildOptions::$useHeuristic). Модуль также предоставляет путь эмиттера, который может записать AST обратно в PDF и проверить результат, плюс журнал мутаций для отслеживания изменений, применённых к дереву.

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

Дерево неизменяемо по построению. Каждое редактирование перестраивает только затронутый путь от корня к узлу и разделяет нетронутые поддеревья по идентичности, поэтому построенный AstDocument можно безопасно держать, кешировать и передавать конкурентным читателям без защитных копий. Это отражает то, как сам PDF изменяется на диске: путь обратной записи добавляет инкрементальное обновление через AstWriter, а не переписывает файл, оставляя исходные байты — и любые существующие подписи — нетронутыми. Ревизию с добавлением-только также дёшево проверить структурно, поэтому AstWriter может проверить свой собственный вывод перед его возвратом. Реконструкция поддеревьев вместо изменения на месте — это единственное решение, которое делает модуль одновременно навигируемым и безопасно редактируемым.

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

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

• AstBuilder::build($sourceHash) принимает полный SHA-256 в hex исходного PDF и возвращает AstDocument.
• Зашифрованные PDF отклоняются с отдельной ошибкой неподдерживаемого шифрования; расшифруйте перед построением.
• Когда дерево структуры отсутствует, конструктор автоматически использует нетегированный путь — эвристический, если включён, иначе голый резервный.
• Ограничения ресурсов в AstBuildOptions (макс. узлов, макс. глубина, макс. память, таймаут по времени) вызывают ошибку предела или таймаута построения, а не неограниченную работу.
• Ключ кеша включает хеш источника и хеш опций, поэтому два построения с идентичными входами и опциями возвращают одно и то же дерево.
• AstNode неизменяем; потребители получают новые экземпляры узлов при изменении дерева.

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

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

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$builder = new AstBuilder($pdfReader, new AstBuildOptions());
$document = $builder->build($sha256OfPdf);

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

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$options = new AstBuildOptions(
    maxNodes: 100_000,
    maxDepth: 200,
    maxMemoryBytes: 256 * 1024 * 1024,
    timeoutSeconds: 30.0,
    useHeuristic: true,
);

$builder = new AstBuilder($pdfReader, $options, $astCache);

try {
    $document = $builder->build($sha256OfPdf);
} catch (\NextPDF\Pro\Ast\Exception\AstUnsupportedEncryptionException $e) {
    // Decrypt the source first, then retry.
}

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

• Страницы, поток содержимого которых не удаётся разобрать, пропускаются при прикреплении ограничивающих прямоугольников; дерево всё равно возвращается, просто без прямоугольников для этих страниц.
• Эвристический конструктор включается по выбору. С отключённым конструктором нетегированные PDF дают более грубое дерево из голого резервного пути.
• Диапазон страниц в AstBuildOptions использует 0-индексированные включительные индексы; если оставить обе границы null, обрабатываются все страницы.

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

Стоимость построения масштабируется с числом узлов и числом страниц; AstBuildOptions ограничивает оба. Кеш короткозамыкает повторные построения того же входа с теми же опциями. NextPDF не публикует здесь фиксированного времени на документ; таймаут по времени (по умолчанию 30 с) и потолок узлов (по умолчанию 100 000) ограничивают худший случай работы. Измеряйте на репрезентативных документах.

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

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

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

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

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

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

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

Без Pro нет эквивалентного дерева документа; вызывающий код разбирает потоки содержимого напрямую, используя примитивы NextPDF Core. См. /modules/ast/.

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

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

См. также

• AST — глубокий справочник
• Projection
• Diff
• Output Pipeline