Interop — Referência Profunda

Visão geral

Esta página é a referência em nível de contrato para NextPDF\Pro\Interop\V1. O módulo contém catorze símbolos públicos: um contrato de serialização (InteropResultInterface), um guarda de integridade de CI (SchemaLock), três DTOs de resultado de nível superior (ExtractedText, DocumentSegmentation, FormData) e nove value objects e enums de apoio. Cada DTO é uma visão imutável e serializável em JSON de um resultado de análise. O formato de transmissão é versionado e bloqueado; nada nesta superfície reexecuta a análise. A visão orientada a tarefas fica na página de capacidade.

Disponibilidade & licenciamento

Esta capacidade é fornecida no NextPDF Pro (nextpdf/pro) e é ativada com um envelope de licença de nível Pro. Uma implantação sem esse direito não carrega as classes da capacidade. Compare as edições e obtenha uma licença.

Nenhum sinalizador de capacidade em tempo de execução restringe este módulo. As classes ficam disponíveis sempre que nextpdf/pro está instalado e licenciado.

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
InteropResultInterface	—	Contrato para DTOs de resultado de nível superior; estende JsonSerializable	—	Não lança	SCHEMA_VERSION é a string '1.0'.
InteropResultInterface::toArray()	nenhum	Serializa para um array seguro em JSON que sempre carrega schema_version	array<string, mixed>	Não lança	As implementações também emitem um discriminador type.
InteropResultInterface::toJson()	int $flags = 0	Codifica a saída de toArray(); JSON_THROW_ON_ERROR é sempre combinado via OR	string	JsonException em dados não codificáveis	Passe sinalizadores como JSON_PRETTY_PRINT.
SchemaLock::verify()	nenhum	Faz o hash do schema.json V1 em disco e o compara com o SHA-256 bloqueado	bool	Não lança	false quando o arquivo de esquema está ausente, ilegível ou modificado.
SchemaLock::expectedHash()	nenhum	Retorna o hash bloqueado	string	Não lança	Saída de diagnóstico para triagem de falhas de CI.
SchemaLock::actualHash()	nenhum	Retorna o hash do arquivo de esquema atual	string	Não lança	As strings sentinela FILE_NOT_FOUND / READ_FAILED substituem o hash em falha de I/O.
BoundingBox	float $x, float $y, float $width, float $height	Caixa imutável em pontos do espaço de usuário do PDF, origem no canto inferior esquerdo	—	Não lança	area(), overlaps(), toArray(), fromArray().
DocumentInfo	int $pageCount mais seis campos opcionais de metadados	Metadados de documento imutáveis	—	Não lança	fromArray() faz type-guard de cada campo; campos ausentes recorrem aos padrões.
PageInfo	int $pageNumber, float $width, float $height, int $rotation = 0	Metadados de página imutáveis	—	Não lança	isLandscape(); fromArray() coage strings numéricas e floats.
ExtractedText	list<ExtractedPage> $pages, DocumentInfo $documentInfo, float $processingTimeMs = 0.0	Resultado de extração de texto do documento inteiro	—	JsonException apenas de toJson()	page(), totalBlockCount(), plainText(), fromArray().
ExtractedPage	PageInfo $pageInfo, list<TextBlock> $textBlocks	Contêiner por página de blocos de texto em ordem de leitura	—	Não lança	plainText() une o conteúdo dos blocos com espaços simples.
TextBlock	string $content, BoundingBox $boundingBox, int $pageNumber, string $fontName = '', float $fontSize = 0.0	Sequência de texto contígua e posicionada	—	Não lança	O nome e o tamanho da fonte são best-effort (fonte dominante no bloco).
DocumentSegmentation	list<Segment> $segments, DocumentInfo $documentInfo, float $processingTimeMs = 0.0	Resultado de segmentação com reconhecimento de layout	—	JsonException apenas de toJson()	segmentCount(), ofType(), onPage(), contentSegments(), fromArray().
Segment	SegmentType $type, string $content, BoundingBox $boundingBox, int $pageNumber, float $confidence = 1.0, list<Segment> $children = []	Região de página classificada; os filhos aninham recursivamente	—	Não lança	O limiar de isHighConfidence() é 0.8; descendantCount() é recursivo.
SegmentType	enum baseado em string	Doze casos, de heading a unknown	—	Não lança	isContent() e isStructural() particionam os casos.
FormData	list<FormField> $fields, DocumentInfo $documentInfo, float $processingTimeMs = 0.0	Resultado de extração de formulário do documento inteiro	—	JsonException apenas de toJson()	field(), dataFields(), filledCount(), toKeyValueMap(), fromArray().
FormField	string $name, FormFieldType $type, mais seis campos opcionais	Único campo de formulário extraído	—	Não lança	isFilled() é value !== ''.
FormFieldType	enum baseado em string	Oito casos, de text a button	—	Não lança	isDataField() é false para button e 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

Contrato de comportamento

• Envelope versionado. Cada DTO de nível superior (ExtractedText, DocumentSegmentation, FormData) implementa InteropResultInterface. Sua saída de toArray() sempre carrega schema_version ('1.0') e um discriminador type: extracted_text, document_segmentation ou form_data.
• Codificação JSON. toJson() delega a json_encode com JSON_THROW_ON_ERROR combinado via OR aos sinalizadores do chamador. jsonSerialize() delega a toArray(), de modo que json_encode($dto) produz o mesmo formato.
• Serialização determinística. A ordem e o formato das chaves são fixados pelo DTO. Segment::toArray() omite a chave children quando vazia; FormField::toArray() omite bounding_box quando é null. Os consumidores devem tratar ambas as chaves como opcionais.
• Ida e volta. Cada DTO expõe um fromArray() estático que aceita um objeto JSON decodificado. Os campos passam por type-guard nesta fronteira entre processos: valores ausentes ou com tipo incorreto recorrem aos padrões documentados em vez de lançar exceção.
• Fallbacks de enum. Uma string type não reconhecida mapeia para SegmentType::Unknown em Segment::fromArray() e para FormFieldType::Text em FormField::fromArray().
• Coordenadas. As coordenadas de BoundingBox são unidades do espaço de usuário do PDF (pontos, 1/72 de polegada) com a origem no canto inferior esquerdo da página. Os números de página são baseados em um em toda a superfície.
• Junções de texto simples. ExtractedPage::plainText() une o conteúdo dos blocos com espaços simples. ExtractedText::plainText() une as páginas com linhas em branco ("\n\n").
• Consultas de segmentação. ofType(), onPage() e contentSegments() filtram apenas os segmentos de nível superior e retornam listas reindexadas. contentSegments() seleciona os tipos onde SegmentType::isContent() é true: heading, sub_heading, paragraph, table, list, code.
• Consultas de formulário. FormData::dataFields() e toKeyValueMap() excluem os tipos de campo que não são de dados (button, signature). filledCount() conta os campos cujo valor é uma string não vazia.
• Bloqueio de esquema. SchemaLock::verify() lê o schema.json V1 fornecido com o pacote, normaliza CRLF para LF, faz o hash com SHA-256 e compara com a constante bloqueada em tempo constante. A CI o usa para bloquear o desvio silencioso de esquema; o valor do bloqueio muda apenas com uma alteração de esquema deliberada e versionada.
• Política de versionamento. A superfície V1 é um contrato público explícito. Alterações aditivas incrementam a versão do esquema; alterações incompatíveis exigem uma nova versão major.

Casos extremos & modos de falha

• O único membro que lança exceção nesta superfície é toJson(): JsonException quando o array não é codificável, por exemplo UTF-8 inválido no conteúdo extraído.
• SchemaLock::verify() retorna false — nunca lança — quando o arquivo de esquema está ausente, ilegível ou modificado. Compare expectedHash() com actualHash() para distinguir desvio de falha de I/O.
• Os fallbacks de fromArray() são silenciosos por design. Um page_number com tipo incorreto vira 1; um confidence com tipo incorreto vira o padrão. Valide a montante quando padrões fabricados forem inaceitáveis.
• A coerção de strings numéricas é assimétrica. PageInfo::fromArray() aceita strings numéricas para seus campos int e float; Segment e TextBlock aceitam apenas int ou float para confidence e font_size.
• BoundingBox::fromArray() exige as quatro chaves conforme seu formato de array documentado. Os DTOs que o incorporam substituem por uma caixa zero (ou null para FormField) quando a chave envolvente está ausente.
• ExtractedPage::fromArray() substitui por um page_info de fallback da página 1 a 595 × 842 pontos quando a chave está ausente ou com tipo incorreto.
• FormField::fromArray() aceita apenas booleanos estritos para required e read_only; strings e inteiros truthy mapeiam para false.
• Os filhos de Segment recursam sem limite de profundidade. Um aninhamento extremamente profundo é limitado apenas pelos limites de memória e de pilha do PHP.
• Nenhuma operação de chave criptográfica ou de assinatura ocorre neste módulo. SchemaLock usa SHA-256 exclusivamente como um checksum de integridade de arquivo, portanto não há comportamento específico do modo FIPS.

Conformidade

O Interop V1 é um contrato de transmissão versionado de propriedade do NextPDF. Ele não implementa nenhum padrão externo, portanto não há tabela de citação normativa. A semântica de BoundingBox alinha-se com o modelo de coordenadas do espaço de usuário do PDF que os subsistemas Core produtores usam; essa é uma afirmação de alinhamento estrutural, não um resultado de teste de conformidade. O NextPDF não detém nenhuma certificação e não concede nenhuma.

Notas de desenvolvimento

• Ramifique com base em schema_version nos consumidores. Trate as chaves aditivas como compatíveis; rejeite versões major desconhecidas de forma explícita.
• Execute SchemaLock::verify() na CI. Em caso de falha, registre expectedHash() e actualHash() e exija uma alteração de esquema deliberada e versionada, nunca uma edição in-place.
• Para idas e voltas entre processos, decodifique com arrays associativos (json_decode($json, true)) e alimente o resultado ao fromArray() correspondente.
• Todos os DTOs são final e readonly. Estenda por composição; derive novas visões a partir dos campos públicos.
• toKeyValueMap() achata apenas os campos que carregam dados. Leia os campos signature diretamente de FormData::$fields quando sua presença for relevante.
• A reutilização é segura: os DTOs não mantêm estado mutável nem recursos, portanto podem ser cacheados, compartilhados entre requisições e serializados repetidamente.

Fronteira de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície da API pública com suporte. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de tíquetes estão fora de escopo.

Veja também

• Interop — página de capacidade
• MCP — Referência Profunda (Pro)
• Extraction — Referência Profunda (Pro)
• Form — Referência Profunda (Pro)