Interop

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

NextPDF Pro предоставляет версионированный набор объектов передачи данных (DTO) результатов, которые сериализуют вывод анализа PDF — сведения о документе, страницы, текстовые блоки, сегментацию и данные форм — в стабильную, зафиксированную схемой форму JSON для потребления внешними системами и инструментами.

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

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

Установка

composer require nextpdf/pro:^3

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

Когда вывод обработки PDF пересекает границу процесса или службы, получателю нужен стабильный контракт. Поверхность Interop V1 предоставляет его:

• InteropResultInterface — каждый DTO результата реализует его. Каждый сериализуется в безопасный для JSON массив, который всегда несёт ключ schema_version, и в строку JSON.
• DTO результатов — DocumentInfo, PageInfo, BoundingBox, ExtractedText / ExtractedPage / TextBlock, DocumentSegmentation / Segment и FormData / FormField. Каждый — это неизменяемое представление одного результата анализа.
• SchemaLock — защита CI. Она хранит SHA-256 замороженной схемы и завершает сборку с ошибкой, если файл схемы изменяется без соответствующего повышения версии, чтобы контракт передачи данных не мог измениться молча.

Поверхность Interop явно версионирована (SCHEMA_VERSION). Относитесь к ней как к контракту публичного API: аддитивные изменения повышают схему; ломающие изменения требуют новой мажорной версии.

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

Форма сериализации рассматривается как контракт публичного API, а не как деталь реализации. Каждый DTO несёт ключ schema_version, поэтому потребители ветвятся по получаемой форме, а не гадают. SchemaLock фиксирует SHA-256 замороженной схемы в CI, поэтому формат не может измениться без повышения версии. Именно это позволяет внешним системам безопасно строиться на JSON: контракт меняется только вместе с версией. Вывод остаётся переносимым — документированные, версионированные данные, которыми владеете вы, а не форма, которая меняется под вами.

Проектный контекст: Open core, без привязки к поставщику.

Поверхность API

Класс	Назначение
InteropResultInterface	Общий контракт сериализации.
DocumentInfo, PageInfo, BoundingBox	Общие DTO документа/страницы.
ExtractedText, ExtractedPage, TextBlock	DTO извлечения текста.
DocumentSegmentation, Segment	DTO сегментации документа.
FormData, FormField	DTO данных форм.
SchemaLock	Защита CI от дрейфа схемы.

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

$json = $result->toJson(JSON_PRETTY_PRINT);
$array = $result->toArray(); // includes 'schema_version'

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

use NextPDF\Pro\Interop\V1\SchemaLock;

if (! SchemaLock::verify()) {
    throw new RuntimeException('Interop schema drift detected — version bump required.');
}
$payload = $result->toArray();
$httpClient->postJson($endpoint, $payload);

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

• toArray() всегда включает schema_version; нижестоящие потребители должны ветвиться по нему.
• SchemaLock::verify() возвращает false, если файл схемы отсутствует или изменён.
• DTO — это представления только для чтения; они не запускают анализ заново.

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

Сериализация линейна по размеру графа результата.

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

DTO несут только тот вывод анализа, который вы заполняете. Во время сериализации не происходит ввода-вывода файловой системы или сети.

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

Interop определяет версионированную схему, принадлежащую NextPDF; он не реализует внешний стандарт.

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

• Каждый DTO результата реализует InteropResultInterface и сериализуется в безопасный для JSON массив, который всегда несёт ключ schema_version, и в строку JSON.
• DTO результатов (DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField) — это неизменяемые представления только для чтения; они не запускают анализ заново.
• SchemaLock::verify() хранит SHA-256 замороженной схемы и возвращает false, если файл схемы отсутствует или изменён, чтобы контракт передачи данных не мог измениться молча.
• Поверхность явно версионирована (SCHEMA_VERSION): аддитивные изменения повышают схему; ломающие изменения требуют новой мажорной версии.
• Во время сериализации не происходит ввода-вывода файловой системы или сети.

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

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

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

В Core нет аналога для зафиксированных схемой, версионированных DTO результатов. Это дополнение Pro.

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

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

См. также

• Extraction — формирует результаты текста и сегментов.
• Form — формирует результаты данных форм.
• Interop — Deep Reference — полный справочник полей DTO.