Pro редакция

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

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

Эта страница — справочник контрактного уровня для NextPDF\Pro\Interop\V1. Модуль содержит четырнадцать публичных символов: один контракт сериализации (InteropResultInterface), один страж целостности для CI (SchemaLock), три DTO результата верхнего уровня (ExtractedText, DocumentSegmentation, FormData) и девять вспомогательных объектов-значений и перечислений. Каждый DTO — это неизменяемое, сериализуемое в JSON представление одного результата анализа. Форма данных на проводе версионирована и заблокирована; ничто на этой поверхности не запускает анализ повторно. Ориентированное на задачи представление находится на странице возможности.

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

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

Ни один рантайм-флаг возможности не закрывает этот модуль. Классы доступны всегда, когда nextpdf/pro установлен и лицензирован.

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

Символ	Параметры	Поведение по умолчанию	Возвращает	Бросает или завершается ошибкой с	Примечания
`InteropResultInterface`	—	Контракт для DTO результата верхнего уровня; расширяет `JsonSerializable`	—	Не бросает исключений	`SCHEMA_VERSION` — это строка `'1.0'`.
`InteropResultInterface::toArray()`	нет	Сериализует в JSON-безопасный массив, всегда несущий `schema_version`	`array<string, mixed>`	Не бросает исключений	Реализации также выдают дискриминатор `type`.
`InteropResultInterface::toJson()`	`int $flags = 0`	Кодирует вывод `toArray()`; `JSON_THROW_ON_ERROR` всегда добавляется через OR	`string`	`JsonException` на некодируемых данных	Передавайте флаги, такие как `JSON_PRETTY_PRINT`.
`SchemaLock::verify()`	нет	Хеширует V1 `schema.json` на диске и сравнивает с заблокированным SHA-256	`bool`	Не бросает исключений	`false`, когда файл схемы отсутствует, нечитаем или изменён.
`SchemaLock::expectedHash()`	нет	Возвращает заблокированный хеш	`string`	Не бросает исключений	Диагностический вывод для разбора сбоя в CI.
`SchemaLock::actualHash()`	нет	Возвращает хеш текущего файла схемы	`string`	Не бросает исключений	Строки-сигналы `FILE_NOT_FOUND` / `READ_FAILED` заменяют хеш при ошибке ввода-вывода.
`BoundingBox`	`float $x`, `float $y`, `float $width`, `float $height`	Неизменяемый прямоугольник в точках пользовательского пространства PDF, начало координат в левом нижнем углу	—	Не бросает исключений	`area()`, `overlaps()`, `toArray()`, `fromArray()`.
`DocumentInfo`	`int $pageCount` плюс шесть необязательных полей метаданных	Неизменяемые метаданные документа	—	Не бросает исключений	`fromArray()` проверяет тип каждого поля; отсутствующие поля откатываются к значениям по умолчанию.
`PageInfo`	`int $pageNumber`, `float $width`, `float $height`, `int $rotation = 0`	Неизменяемые метаданные страницы	—	Не бросает исключений	`isLandscape()`; `fromArray()` приводит числовые строки и числа с плавающей точкой.
`ExtractedText`	`list<ExtractedPage> $pages`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Результат извлечения текста по всему документу	—	Только `JsonException` из `toJson()`	`page()`, `totalBlockCount()`, `plainText()`, `fromArray()`.
`ExtractedPage`	`PageInfo $pageInfo`, `list<TextBlock> $textBlocks`	Постраничный контейнер текстовых блоков в порядке чтения	—	Не бросает исключений	`plainText()` соединяет содержимое блоков одиночными пробелами.
`TextBlock`	`string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `string $fontName = ''`, `float $fontSize = 0.0`	Позиционированный непрерывный участок текста	—	Не бросает исключений	Имя и размер шрифта определяются по мере возможности (доминирующий шрифт в блоке).
`DocumentSegmentation`	`list<Segment> $segments`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Результат сегментации с учётом макета	—	Только `JsonException` из `toJson()`	`segmentCount()`, `ofType()`, `onPage()`, `contentSegments()`, `fromArray()`.
`Segment`	`SegmentType $type`, `string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `float $confidence = 1.0`, `list<Segment> $children = []`	Классифицированная область страницы; дочерние элементы вкладываются рекурсивно	—	Не бросает исключений	Порог `isHighConfidence()` равен 0.8; `descendantCount()` рекурсивен.
`SegmentType`	перечисление на основе строки	Двенадцать вариантов, от `heading` до `unknown`	—	Не бросает исключений	`isContent()` и `isStructural()` разбивают варианты на группы.
`FormData`	`list<FormField> $fields`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Результат извлечения формы по всему документу	—	Только `JsonException` из `toJson()`	`field()`, `dataFields()`, `filledCount()`, `toKeyValueMap()`, `fromArray()`.
`FormField`	`string $name`, `FormFieldType $type`, плюс шесть необязательных полей	Одно извлечённое поле формы	—	Не бросает исключений	`isFilled()` — это `value !== ''`.
`FormFieldType`	перечисление на основе строки	Восемь вариантов, от `text` до `button`	—	Не бросает исключений	`isDataField()` равно `false` для `button` и `signature`.

interface InteropResultInterface extends JsonSerializable

public const SCHEMA_VERSION = '1.0';

public function toArray(): array;

public function toJson(int $flags = 0): string;

final class SchemaLock

public static function verify(): bool

public static function expectedHash(): string

public static function actualHash(): string

final readonly class ExtractedText implements InteropResultInterface

public function __construct(
    public array $pages,
    public DocumentInfo $documentInfo,
    public float $processingTimeMs = 0.0,
)

public function page(int $pageNumber): ?ExtractedPage

public function totalBlockCount(): int

public function plainText(): string

public static function fromArray(array $data): self

final readonly class DocumentSegmentation implements InteropResultInterface

public function __construct(
    public array $segments,
    public DocumentInfo $documentInfo,
    public float $processingTimeMs = 0.0,
)

public function ofType(SegmentType $type): array

public function onPage(int $pageNumber): array

public function contentSegments(): array

public static function fromArray(array $data): self

final readonly class FormData implements InteropResultInterface

public function __construct(
    public array $fields,
    public DocumentInfo $documentInfo,
    public float $processingTimeMs = 0.0,
)

public function field(string $name): ?FormField

public function dataFields(): array

public function toKeyValueMap(): array

public static function fromArray(array $data): self

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

Версионированный конверт. Каждый DTO верхнего уровня (ExtractedText, DocumentSegmentation, FormData) реализует InteropResultInterface. Вывод его toArray() всегда несёт schema_version ('1.0') и дискриминатор type: extracted_text, document_segmentation или form_data.
Кодирование JSON. toJson() делегирует json_encode с JSON_THROW_ON_ERROR, добавленным через OR к флагам вызывающего. jsonSerialize() делегирует toArray(), поэтому json_encode($dto) производит ту же форму.
Детерминированная сериализация. Порядок ключей и форма фиксированы DTO. Segment::toArray() опускает ключ children, когда он пуст; FormField::toArray() опускает bounding_box, когда он null. Потребители должны считать оба ключа необязательными.
Круговой обход. Каждый DTO предоставляет статический fromArray(), принимающий декодированный объект JSON. Поля проверяются по типу на этой межпроцессной границе: отсутствующие или неверно типизированные значения откатываются к документированным значениям по умолчанию вместо бросания исключения.
Откаты перечислений. Нераспознанная строка type отображается в SegmentType::Unknown в Segment::fromArray() и в FormFieldType::Text в FormField::fromArray().
Координаты. Координаты BoundingBox — это единицы пользовательского пространства PDF (точки, 1/72 дюйма) с началом координат в левом нижнем углу страницы. Номера страниц везде отсчитываются от единицы.
Соединение обычного текста. ExtractedPage::plainText() соединяет содержимое блоков одиночными пробелами. ExtractedText::plainText() соединяет страницы пустыми строками ("\n\n").
Запросы сегментации. ofType(), onPage() и contentSegments() фильтруют только сегменты верхнего уровня и возвращают переиндексированные списки. contentSegments() выбирает типы, для которых SegmentType::isContent() равно true: heading, sub_heading, paragraph, table, list, code.
Запросы формы. FormData::dataFields() и toKeyValueMap() исключают типы полей, не являющиеся данными (button, signature). filledCount() считает поля, значение которых является непустой строкой.
Блокировка схемы. SchemaLock::verify() читает V1 schema.json, поставляемый с пакетом, нормализует CRLF в LF, хеширует с SHA-256 и сравнивает с заблокированной константой за постоянное время. CI использует это для блокировки молчаливого дрейфа схемы; значение блокировки меняется только при намеренном версионированном изменении схемы.
Политика версионирования. Поверхность V1 — это явный публичный контракт. Аддитивные изменения повышают версию схемы; ломающие изменения требуют новой основной версии.

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

Единственный бросающий исключения член на этой поверхности — toJson(): JsonException, когда массив не поддаётся кодированию, например при некорректном UTF-8 в извлечённом содержимом.
SchemaLock::verify() возвращает false — никогда не бросает исключений, — когда файл схемы отсутствует, нечитаем или изменён. Сравните expectedHash() с actualHash(), чтобы отличить дрейф от ошибки ввода-вывода.
Откаты fromArray() молчаливы по замыслу. Неверно типизированный page_number становится 1; неверно типизированный confidence становится значением по умолчанию. Проверяйте данные выше по потоку, когда сфабрикованные значения по умолчанию неприемлемы.
Приведение числовых строк асимметрично. PageInfo::fromArray() принимает числовые строки для своих полей int и float; Segment и TextBlock принимают только int или float для confidence и font_size.
BoundingBox::fromArray() требует все четыре ключа согласно своей документированной форме массива. DTO, которые его встраивают, подставляют нулевой прямоугольник (или null для FormField), когда ключ-обёртка отсутствует.
ExtractedPage::fromArray() подставляет запасной page_info со страницей 1 размером 595 × 842 точки, когда ключ отсутствует или неверно типизирован.
FormField::fromArray() принимает только строгие булевы значения для required и read_only; истинностные строки и целые числа отображаются в false.
Дочерние элементы Segment рекурсируют без ограничения глубины. Крайне глубокая вложенность ограничена только лимитами памяти и стека PHP.
В этом модуле не происходит операций с криптографическими ключами или подписями. SchemaLock использует SHA-256 исключительно как контрольную сумму целостности файла, поэтому специфического для режима FIPS поведения нет.

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

Interop V1 — это версионированный проводной контракт, принадлежащий NextPDF. Он не реализует внешний стандарт, поэтому нормативной таблицы цитирования нет. Семантика BoundingBox согласуется с моделью координат пользовательского пространства PDF, которую используют производящие подсистемы Core; это утверждение о структурном согласовании, а не результат теста на соответствие. NextPDF не имеет никакой сертификации и не предоставляет её.

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

Ветвитесь по schema_version у потребителей. Считайте аддитивные ключи совместимыми; явно отклоняйте неизвестные основные версии.
Запускайте SchemaLock::verify() в CI. При сбое логируйте expectedHash() и actualHash() и требуйте намеренного версионированного изменения схемы, а никогда правки на месте.
Для межпроцессных круговых обходов декодируйте с ассоциативными массивами (json_decode($json, true)) и передавайте результат в соответствующий fromArray().
Все DTO являются final и readonly. Расширяйте через композицию; выводите новые представления из публичных полей.
toKeyValueMap() уплощает только поля, несущие данные. Читайте поля signature напрямую из FormData::$fields, когда их наличие важно.
Повторное использование безопасно: DTO не хранят изменяемого состояния и ресурсов, поэтому их можно кешировать, разделять между запросами и сериализовать многократно.

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

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