Pro редакция

Converter — глубокий справочник

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

NextPDF\Pro\Converter экспортирует существующий PDF в позиционированный HTML, упрощённый SVG или обычный текст и разбивает содержимое документа на типизированные структурные области. Этот глубокий справочник перечисляет публичную поверхность API, матрицу охвата операторов, контракт поведения и режимы отказа. Это экспортёр для извлечения содержимого, а не попиксельно точный визуализатор.

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

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

Никакой флаг возможностей времени выполнения не закрывает этот модуль. Классы конвертера разрешаются всегда, когда пакет Pro установлен и лицензирован.

Публичная поверхность API

Символ	Параметры	Поведение по умолчанию	Возвращает	Возбуждает или отказывает с	Примечания
`PdfToHtmlConverter::convert()`	`string $pdfData`, `?ConversionConfig $config = null`	Экспортирует каждую страницу с текстом в один самодостаточный документ HTML5	`ConversionResult` (цель `Html5`)	`InvalidArgumentException`, когда `$pdfData` пуст	При null-конфигурации по умолчанию используется `ConversionTarget::Html5`
`PdfToSvgConverter::convert()`	`string $pdfData`, `int $pageIndex = 0`, `?ConversionConfig $config = null`	Экспортирует одну страницу в отдельный документ SVG	`ConversionResult` (цель `Svg`; `pageCount` всегда равен 1)	`InvalidArgumentException`, когда `$pdfData` пуст	`$pageIndex` вне диапазона даёт SVG только с фоном
`PdfToTextConverter::convert()`	`string $pdfData`	Извлекает декодированный текст со всех страниц, разделяя их маркером разрыва страницы	`ConversionResult` (цель `PlainText`)	`InvalidArgumentException`, когда `$pdfData` пуст	Только эта цель декодирует escape-последовательности литеральных строк
`PdfToTextConverter::extractPage()`	`string $pdfData`, `int $pageIndex`	Извлекает декодированный текст для одной страницы с нулевой индексацией	`string`	Не возбуждает исключение; возвращает `''` при отсутствующей странице или пустом вводе	В отличие от `convert()`, без проверки пустого ввода
`DocumentSegmentationEngine::segment()`	`string $pdfData`	Классифицирует содержимое страницы в типизированные структурные сегменты с помощью пространственных и шрифтовых эвристик	`NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation`	`InvalidArgumentException`, когда ввод пуст или структуру PDF не удаётся разобрать	На основе правил; не выполняет ИИ-вывод
`ConversionConfig::__construct()`	`ConversionTarget $target`, `bool $embedFonts = false`, `bool $embedImages = true`, `float $scaleFactor = 1.0`, `string $cssClass = 'pdf-page'`	Неизменяемые настройки конвертации	`ConversionConfig`	—	`embedFonts` и `embedImages` принимаются, но не используются в 3.1.0
`ConversionResult::size()`	—	Длина в байтах созданного вывода	`int`	—	Публичные readonly-поля: `output`, `target`, `pageCount`, `processingTimeMs`
`ConversionResult::isValid()`	—	Сообщает, непустой ли вывод	`bool`	—	Оболочки документов HTML и SVG никогда не пусты; вместо этого проверяйте `pageCount`
`ConversionTarget`	Строковые варианты `Html5`, `Svg`, `PlainText`	Выбирает цель экспорта	`mimeType(): string`, `fileExtension(): string`	—	`fileExtension()` отображается в `html`, `svg`, `txt`

Сигнатуры точек входа:

public function convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult

public function convert(
    string $pdfData,
    int $pageIndex = 0,
    ?ConversionConfig $config = null,
): ConversionResult

public function convert(string $pdfData): ConversionResult
public function extractPage(string $pdfData, int $pageIndex): string

public function segment(string $pdfData): DocumentSegmentation

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

На входе — необработанные байты PDF; на выходе — объект-значение ConversionResult. Три экспортирующих конвертера используют общую модель сканирования: находят границы stream/endstream, выделяют текстовые блоки BT/ET и разбирают операторы показа текста. Они не разбирают таблицу перекрёстных ссылок и не распаковывают сжатые потоки. DocumentSegmentationEngine отличается: он разрешает трейлер, каталог и дерево страниц и распаковывает содержимое страниц FlateDecode перед классификацией.

Охват операторов:

Оператор PDF	HTML	SVG	Текст
`Tj` (показать строку)	да	да	да
`TJ` (показать массив)	да	да	да
`'` (переход + показ)	нет	нет	да
`Td` / `Tm` (позиция)	да	да	н/д
`Tf` (размер шрифта)	да	да	н/д
`re` (прямоугольник)	нет	да	нет
`m` / `l` (линия)	нет	да	нет
`RG` (обводка RGB)	нет	да (применяется к обводке прямоугольника/линии)	нет
кривые, затенение, отсечение, изображения	нет	нет	нет

Позиционирование. Каждый блок BT/ET определяет одну позицию по первому совпадению Td или Tm; Tm имеет приоритет, когда присутствуют оба. Ось Y переворачивается из пользовательского пространства PDF в выходное пространство с началом в левом верхнем углу. Размер шрифта по умолчанию — 12 pt, когда Tf отсутствует.
Геометрия страницы. HTML и SVG предполагают страницу формата A4 (595 x 842 pt), умноженную на scaleFactor. Корневой элемент SVG несёт соответствующие атрибуты viewBox, width и height поверх белого фонового прямоугольника.
Цвет обводки. Операторы RG разрешаются позиционно, поэтому в потоке, меняющем цвет обводки более одного раза, каждый прямоугольник и линия окрашиваются по последнему предшествующему оператору. Компоненты ограничиваются диапазоном 0..1 перед преобразованием в hex. Заливка прямоугольника всегда чёрная; оператор заливки rg не вычисляется.
Декодирование строк. Текстовая цель декодирует escape-последовательности литеральных строк согласно ISO 32000-2:2020 §7.3.4.2: именованные escape-последовательности, восьмеричные коды \ddd, маскируемые до одного байта, продолжения строк обратной косой чертой и удаление одиночной обратной косой черты. Цели HTML и SVG выводят необработанные байты между скобками после HTML- или XML-экранирования; они не декодируют escape-последовательности.
Сборка вывода. Текстовая цель соединяет тексты блоков пробелом, а страницы — маркером --- Page Break ---, обрамлённым пустыми строками. Цель HTML выводит один абсолютно позиционированный <div> на каждый текстовый блок внутри контейнера страницы, несущего настроенный CSS-класс и атрибут data-page.
Детерминизм. При одинаковом вводе и конфигурации создаваемые байты HTML, SVG или текста стабильны. processingTimeMs — это измерение по настенным часам, оно исключено из детерминированной поверхности.

Граничные случаи и режимы отказа

Пустой ввод: каждая точка входа convert() и segment() возбуждает InvalidArgumentException (“PDF data must not be empty”). Частичный вывод не создаётся. Исключение — extractPage(): он возвращает '' без возбуждения исключения.
Потоки без BT/ET пропускаются конвертерами HTML и текста. PDF, содержащий только такие потоки, даёт нулевой pageCount с пустым текстовым выводом или оболочку HTML без страниц.
isValid() проверяет только непустоту вывода. Конвертеры HTML и SVG всегда выводят оболочку документа, поэтому isValid() остаётся true, даже когда текст не найден; используйте pageCount (HTML, текст) для обнаружения пустого извлечения.
Содержимое FlateDecode не распаковывается тремя экспортирующими конвертерами. PDF только со сжатым содержимым экспортируют через них мало содержимого или вообще ничего. segment() действительно распаковывает потоки страниц FlateDecode.
segment() ограничивает распаковку размером на поток, коэффициентом сжатия и совокупным бюджетом. Поток, превышающий предел, деградирует до пустого содержимого страницы вместо исчерпания памяти; исключение при этом не возбуждается.
segment() возбуждает InvalidArgumentException, когда не удаётся разрешить трейлер, смещение перекрёстных ссылок, каталог документа или дерево страниц.
Индексация страниц различается у конвертеров. Конвертеры HTML и текста считают только потоки с текстом; конвертер SVG считает потоки, содержащие любой распознаваемый графический или текстовый оператор. Поэтому один и тот же $pageIndex может адресовать разные потоки.
Числовые корректировки кернинга TJ отбрасываются; строки массива соединяются без межглифовых интервалов.
Отображение глифов в Unicode не применяется. Текст, набранный шрифтами с пользовательскими кодировками, экспортируется как необработанная последовательность байтов.
Повёрнутый текст, нетекстовые преобразования и потоковое размещение по колонкам аппроксимируются позиционированием по первому совпадению и могут не воспроизводить исходную вёрстку.
В этом модуле не выполняется никакой криптографической операции, поэтому режим FIPS не имеет поведения, специфичного для модуля.

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

NextPDF документирует возможности относительно цитируемых пунктов. Утверждения о поддержке описывают реализованное поведение; это не результаты тестирования на соответствие и не сертификаты, и NextPDF не имеет никакой сертификации.

Утверждение	Пункт спецификации	Статус
Оператор показа текста `Tj` разбирается	ISO 32000-2:2020 §9.4	Проверено (модульный набор)
Оператор показа текста-массива `TJ` разбирается	ISO 32000-2:2020 §9.4	Проверено (модульный набор)
Оператор перехода-и-показа `'` разбирается (только текстовая цель)	ISO 32000-2:2020 §9.4	Проверено (модульный набор)
Escape-последовательности литеральных строк декодируются (только текстовая цель)	ISO 32000-2:2020 §7.3.4.2	Реализовано; байты возвращаются как есть, интерпретация кодировки — на последующей стадии
Построение контура `re`, `m`, `l` распознаётся (цель SVG)	ISO 32000-2:2020 §8.5.2	Частично: подмножество без кривых, замыкания или вычисления режима закраски
Полный конечный автомат состояния текста и рендеринг страницы	—	Не поддерживается (вне области)

Конвертер разбирает операторы показа текста для восстановления содержимого; он не реализует полный конечный автомат состояния текста, поэтому позиционирование глифов приблизительное, а не точное по спецификации.

Заметки по разработке

Разбор линеен по длине PDF в байтах. Память отслеживает ввод плюс создаваемую строку вывода. Front matter performance_budget — это ориентир на один вызов для типичного офисного документа.
Конвертеры разбирают недоверенные байты PDF ограниченным сканированием strpos/substr. Они не выполняют встроенный JavaScript и не следуют внешним ссылкам. Считайте экспортированный HTML недоверенным содержимым и экранируйте его для места назначения.
Вывод HTML экранируется с помощью htmlspecialchars (ENT_QUOTES, HTML5); текст SVG экранируется XML. Настроенный cssClass экранируется перед выводом.
Использование конфигурации: scaleFactor применяется к целям HTML и SVG; cssClass применяется только к HTML; embedFonts и embedImages зарезервированы и сейчас не используются; поле target не переопределяет собственный формат вывода конвертера.
Экспортирующие конвертеры поставляются с 1.9.0; DocumentSegmentationEngine поставляется с 2.1.0 и обеспечивает работу инструмента Pro MCP segment_document и контракта сегментации Interop.
PdfPageExtractor и PdfPageData в том же пространстве имён являются внутренними для движка сегментации и не входят в публичный API.

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

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