Interop

Visão geral

O NextPDF Pro fornece um conjunto versionado de objetos de transferência de dados (DTOs) de resultado que serializam a saída de análise de PDF — informações do documento, páginas, blocos de texto, segmentação e dados de formulário — para um formato JSON estável e bloqueado por esquema, para consumo por sistemas e ferramentas externos.

Disponibilidade e licenciamento

Este recurso vem no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem essa habilitação não carrega as classes do recurso. O Interop faz parte da edição Pro; não há sinalizador de licença separado por recurso. Compare as edições e obtenha uma licença.

Instalação

composer require nextpdf/pro:^3

Visão conceitual

Quando a saída de processamento de PDF cruza um limite de processo ou serviço, o receptor precisa de um contrato estável. A superfície Interop V1 fornece isso:

• InteropResultInterface — todo DTO de resultado implementa isto. Cada um serializa para um array seguro para JSON que sempre carrega uma chave schema_version, e para uma string JSON.
• DTOs de resultado — DocumentInfo, PageInfo, BoundingBox, ExtractedText / ExtractedPage / TextBlock, DocumentSegmentation / Segment e FormData / FormField. Cada um é uma visão imutável de um resultado de análise.
• SchemaLock — uma proteção de CI. Ela mantém o SHA-256 do esquema congelado e faz o build falhar se o arquivo do esquema mudar sem um incremento de versão correspondente, de modo que o contrato de fio (wire contract) não possa derivar silenciosamente.

A superfície Interop é explicitamente versionada (SCHEMA_VERSION). Trate-a como um contrato de API pública: alterações aditivas incrementam o esquema; alterações que quebram a compatibilidade exigem uma nova versão principal.

Por que funciona assim

O formato de serialização é tratado como um contrato de API pública, não como um detalhe de implementação. Todo DTO carrega uma chave schema_version, para que os consumidores ramifiquem com base no formato que recebem em vez de adivinhar. O SchemaLock fixa o SHA-256 do esquema congelado na CI, de modo que o formato não possa derivar sem um incremento de versão. É isso que permite que sistemas externos construam com base no JSON com segurança: o contrato só muda quando a versão muda. A saída permanece portável — dados documentados e versionados que pertencem a você, não um formato que muda sob os seus pés.

Contexto de design: Open core, sem aprisionamento.

Superfície da API

Classe	Responsabilidade
InteropResultInterface	Contrato comum de serialização.
DocumentInfo, PageInfo, BoundingBox	DTOs comuns de documento/página.
ExtractedText, ExtractedPage, TextBlock	DTOs de extração de texto.
DocumentSegmentation, Segment	DTOs de segmentação de documento.
FormData, FormField	DTOs de dados de formulário.
SchemaLock	Proteção de CI contra deriva de esquema.

Exemplo de código — Início rápido

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

Exemplo de código — Produção

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);

Casos extremos e armadilhas

• toArray() sempre inclui schema_version; os consumidores a jusante devem ramificar com base nele.
• SchemaLock::verify() retorna false se o arquivo do esquema estiver ausente ou modificado.
• Os DTOs são visões somente leitura; eles não reexecutam a análise.

Desempenho

A serialização é linear no tamanho do grafo de resultado.

Notas de segurança

Os DTOs carregam apenas a saída de análise que você popula. Nenhuma E/S de sistema de arquivos ou de rede ocorre durante a serialização.

Conformidade

O Interop define um esquema versionado de propriedade do NextPDF; ele não implementa nenhum padrão externo.

Contrato de comportamento

• Todo DTO de resultado implementa InteropResultInterface e serializa para um array seguro para JSON que sempre carrega uma chave schema_version, e para uma string JSON.
• Os DTOs de resultado (DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField) são visões imutáveis somente leitura; eles não reexecutam a análise.
• SchemaLock::verify() mantém o SHA-256 do esquema congelado e retorna false se o arquivo do esquema estiver ausente ou modificado, de modo que o contrato de fio não possa derivar silenciosamente.
• A superfície é explicitamente versionada (SCHEMA_VERSION): alterações aditivas incrementam o esquema; alterações que quebram a compatibilidade exigem uma nova versão principal.
• Nenhuma E/S de sistema de arquivos ou de rede ocorre durante a serialização.

Nota sobre o limite do Enterprise

O Enterprise não altera o comportamento do Interop. O Enterprise acrescenta recursos de nível superior documentados separadamente; eles não são necessários para usar os DTOs de resultado versionados.

Fallback / alternativa do Core

Não há equivalente no Core para DTOs de resultado versionados e bloqueados por esquema. Este é um acréscimo do Pro.

Limite de publicação

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

Veja também

• Extraction — produz resultados de texto e segmento.
• Form — produz resultados de dados de formulário.
• Interop — Referência aprofundada — referência completa dos campos dos DTOs.