Pro редакция

Документ

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

Модуль Document разбивает PDF на сегменты по диапазону страниц и собирает PDF-портфолио (Collections) с сортируемыми столбцами схемы. Обе операции ограничены против враждебного ввода.

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

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

Установка

composer require nextpdf/pro:^3

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

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

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

PdfSplitter извлекает диапазоны страниц в самостоятельные PDF-сегменты. Он обнаруживает страницы, сканируя исходный ввод на объекты страниц, и оборачивает выбранные страницы в минимальный каталог и дерево страниц. Он поддерживает разбиение по диапазонам, разбиение фиксированного размера (splitEvery) и извлечение одного диапазона (extractPages).
PdfPortfolio строит словарь PDF Collection, который агрегирует вложенные файлы с заданной схемой. Он поддерживает режимы отображения «плитка», «детали» и «скрытый» и выводит словарь, пригодный для включения в каталог документа.

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

Разбиение PDF — это не байтовый срез. Объект страницы ссылается на общие ресурсы, шрифты и потоки содержимого через косвенные ссылки. Он также наследует /MediaBox и /Resources от своих предков в дереве страниц. Поэтому splitter реконструирует каждый сегмент как самодостаточный граф объектов: он обходит транзитивное замыкание ссылок выбранных страниц, материализует унаследованные атрибуты, перенумеровывает их в свежее пространство идентификаторов и записывает таблицу перекрёстных ссылок с точными до байта смещениями. Обход замыкания ограничен, потому что враждебный граф с разветвлением иначе мог бы втянуть неограниченный объём работы в один сегмент. Результат открывается как корректный самостоятельный PDF, а не фрагмент с висячими ссылками.

Проектная предыстория: Анатомия PDF-файла.

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

PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) применяет ограничение размера ввода и ограничение числа диапазонов и отклоняет ввод, не начинающийся с заголовка PDF.
splitEvery($pdfData, $pagesPerSegment) отклоняет размер сегмента меньше 1; последний сегмент может содержать меньше страниц.
PdfPortfolio отклоняет при конструировании любой режим отображения, кроме «плитка», «детали» или «скрытый».
addSchema() и addEntry() возвращают портфолио для текучего связывания вызовов; generateCollectionDictionary() возвращает строку словаря Collection.
Имена полей схемы очищаются для использования как объекты-имена PDF; строковые значения экранируются для литеральных строк PDF.

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

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

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$result = (new PdfSplitter())->split($pdfBytes, [new PageRange(1, 5)]);

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

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$splitter = new PdfSplitter();

try {
    $result = $splitter->split(
        $pdfBytes,
        [new PageRange(1, 10), new PageRange(11, 20)],
        maxBytes: 50_000_000,
        maxRanges: 100,
    );
} catch (\InvalidArgumentException $e) {
    // Input rejected (not a PDF, or limits exceeded).
}

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

Splitter реконструирует каждый сегмент как свежий граф объектов с реальной, точной до байта таблицей перекрёстных ссылок; сегменты являются действительными самостоятельными PDF. Он перенумеровывает их в новое пространство идентификаторов, а не сохраняет исходный байтовый макет, поэтому передавайте байты сегментов модулю Writer для сценариев инкрементального обновления или подписи.
Диапазон, которому не соответствует ни одна страница, даёт минимальный одностраничный сегмент, а не ошибку.
Сортировка портфолио по умолчанию выполняется по первому полю схемы, по возрастанию.

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

Разбиение и сборка портфолио линейны по размеру ввода и числу записей. Потолок ввода по умолчанию — 100 МБ, а потолок числа диапазонов по умолчанию — 1000; оба настраиваются вызывающим кодом в меньшую сторону. Измеряйте на представительных документах.

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

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

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

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

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

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

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

Без Pro используйте базовые примитивы документов NextPDF Core; разбиение по диапазонам страниц и сборка портфолио — это дополнения Pro. См. /modules/document/.

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

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