Pro редакция

Конвертер

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

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

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

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

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

Установка

composer require nextpdf/pro:^3

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

Converter разбирает операторы вывода текста внутри потока содержимого PDF — Tj, TJ и ' согласно ISO 32000-2:2020 §9.4 — и восстанавливает приблизительное представление каждой страницы. Он читает позиционирование из текстовых операторов Td и Tm, а размер шрифта — из Tf, затем сопоставляет точки с выходными координатами.

Предоставляются три конвертера, по одному на каждую ConversionTarget:

PdfToHtmlConverter оборачивает каждую страницу в позиционированный контейнер и выводит абсолютно позиционированные элементы <div> для каждого текстового фрагмента. Результат — самодостаточный документ HTML5.
PdfToSvgConverter разбирает ограниченный набор операторов рисования (прямоугольники через re, линии через m/l) плюс текст и выводит соответствующие элементы <rect>, <line> и <text> для одной страницы.
PdfToTextConverter извлекает только декодированный текст, страница за страницей, разделённый маркером разрыва страницы.

Это намеренно ограниченный экспортёр. Он приближает позицию текста; он не выполняет перекомпоновку, не растеризует и не воспроизводит векторные траектории, заливку градиентом, обрезку, прозрачность или встроенные изображения. Для отрисовки HTML в PDF с полной точностью в обратном направлении используйте конвейер HTML из Core.

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

PDF хранит текст как позиционированные операторы вывода глифов, а не как семантические символы, поэтому нет надёжного текста документа, который можно было бы прочитать обратно. Поэтому Converter сканирует операторы потока содержимого напрямую — Tj, TJ, ', а также Td, Tm и Tf для размещения — и восстанавливает приблизительный макет вместо перекомпоновки или растеризации страницы. Именно это ограниченное сканирование делает экспорт линейным по длине в байтах, детерминированным для одинакового входа и безопасным на недоверенных байтах без исполнения встроенной логики. Оно же задаёт честный потолок: глифы не отображаются обратно в Unicode, поэтому шрифты с пользовательской кодировкой экспортируются как исходные байты, а точная визуальная точность остаётся вне области применения. Проектный контекст: Почему текст в PDF на самом деле не текст.

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

Вход. Исходные байты PDF (string). Пустая строка вызывает InvalidArgumentException.
Выход. Объект-значение ConversionResult, содержащий полученную строку, ConversionTarget, число обработанных страниц и измерение времени обработки.
Покрытие. Экспорт текста (Tj/TJ/') — проверенный путь, испытанный набором модульных тестов. Экспорт SVG охватывает только прямоугольники, прямые линии и текст. Цвет обводки RGB пока не передаётся в вывод SVG.
Детерминированность. Для одинакового входа и конфигурации получаемый поток байтов HTML, SVG или текста стабилен. Поле processingTimeMs — это измерение реального времени, и оно не входит в детерминированную поверхность.
Кодирование. Вывод HTML экранируется через htmlspecialchars; вывод SVG экранируется как XML. Распространённые управляющие последовательности строк PDF (\n, \r, \t, $, $, \\) декодируются для текстовой цели.

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

Тип	Вид	Ключевые члены
`NextPDF\Pro\Converter\PdfToHtmlConverter`	`final class`	`convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult`
`NextPDF\Pro\Converter\PdfToSvgConverter`	`final class`	`convert(string $pdfData, int $pageIndex = 0, ?ConversionConfig $config = null): ConversionResult`
`NextPDF\Pro\Converter\PdfToTextConverter`	`final class`	`convert(string $pdfData): ConversionResult`, `extractPage(string $pdfData, int $pageIndex): string`
`NextPDF\Pro\Converter\ConversionConfig`	`final readonly class`	`__construct(ConversionTarget $target, bool $embedFonts = false, bool $embedImages = true, float $scaleFactor = 1.0, string $cssClass = 'pdf-page')`
`NextPDF\Pro\Converter\ConversionResult`	`final readonly class`	`string $output`, `ConversionTarget $target`, `int $pageCount`, `float $processingTimeMs`, `size(): int`, `isValid(): bool`
`NextPDF\Pro\Converter\ConversionTarget`	`enum`	`Html5`, `Svg`, `PlainText`; `mimeType(): string`, `fileExtension(): string`

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Converter\PdfToTextConverter;

$pdf    = file_get_contents('report.pdf');
$result = (new PdfToTextConverter())->convert($pdf);

echo $result->pageCount, " pages, ", $result->size(), " bytes of text\n";
echo $result->output;

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Converter\ConversionConfig;
use NextPDF\Pro\Converter\ConversionTarget;
use NextPDF\Pro\Converter\PdfToHtmlConverter;

function exportPreview(string $pdfBytes): string
{
    if ($pdfBytes === '') {
        throw new InvalidArgumentException('empty PDF payload');
    }

    $config = new ConversionConfig(
        target: ConversionTarget::Html5,
        scaleFactor: 1.0,
        cssClass: 'doc-preview',
    );

    $result = (new PdfToHtmlConverter())->convert($pdfBytes, $config);

    if (! $result->isValid()) {
        throw new RuntimeException('converter produced no output');
    }

    return $result->output;
}

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

PDF без текстовых блоков BT/ET даёт пустой вывод или только оболочку страницы; отсканированные PDF (только из изображений) не дают текста, потому что шага OCR нет.
PdfToSvgConverter преобразует по одной странице за раз, выбираемой через $pageIndex; индекс вне диапазона даёт пустой поток страницы.
Позиционирование приблизительное. Текст, размещённый с нетекстовыми преобразованиями, повёрнутый текст или текст с колоночным потоком может не воспроизвести исходный визуальный макет.
Сопоставление глифов с Unicode не применяется; текст из шрифтов с пользовательскими кодировками может экспортироваться как исходная последовательность байтов.

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

Разбор линеен по длине байтов PDF. Память отслеживает вход плюс получаемую строку вывода. Front-matter performance_budget — это эталон на один вызов для типичного офисного документа.

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

Converter разбирает недоверенные байты PDF с ограниченным сканированием через strpos/substr по текстовым операторам; он не выполняет встроенный JavaScript и не следует за внешними ссылками. Относитесь к экспортированному HTML как к недоверенному содержимому и экранируйте его соответственно его назначению. См. модель безопасности Core.

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

Утверждение	Пункт стандарта	Статус
Оператор вывода текста `Tj` разбирается	ISO 32000-2:2020 §9.4	Проверено (набор модульных тестов)
Оператор массива вывода текста `TJ` разбирается	ISO 32000-2:2020 §9.4	Проверено (набор модульных тестов)
Полная векторная/растровая точность страницы	—	Не поддерживается (вне области применения)

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

В Core нет аналога для экспорта PDF. Для прямого направления (создание PDF из HTML) поддерживаемым путём является конвейер HTML из Core с открытым исходным кодом. См. /modules/core/html/.

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

Converter — это экспортёр текста/фигур уровня Pro. Он не выполняет OCR, семантическую реконструкцию или понимание документов. Это отдельные задачи, и они не предоставляются этим модулем.

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

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