Interop

한눈에 보기

NextPDF Pro는 PDF 분석 출력 — 문서 정보, 페이지, 텍스트 블록, 세그먼테이션, 양식 데이터 —을 외부 시스템 및 도구가 소비할 수 있도록 안정적이고 스키마가 고정된 JSON 형태로 직렬화하는 버전 관리된 결과 데이터 전송 객체(DTO) 집합을 제공합니다.

가용성 및 라이선스

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되며 Pro 등급 라이선스 엔벨로프로 활성화됩니다. 해당 권한이 없는 배포 환경은 이 기능의 클래스를 로드하지 않습니다. Interop은 Pro 에디션의 일부이며, 기능별 별도의 라이선스 플래그는 없습니다. 에디션 비교 및 라이선스 받기.

설치

composer require nextpdf/pro:^3

개념 개요

PDF 처리 출력이 프로세스 또는 서비스 경계를 넘을 때, 수신자에게는 안정적인 계약이 필요합니다. Interop V1 표면이 그것을 제공합니다.

• InteropResultInterface — 모든 결과 DTO가 이를 구현합니다. 각각은 항상 schema_version 키를 담는 JSON 안전 배열로, 그리고 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은 CI에서 고정된 스키마의 SHA-256을 고정하므로, 버전 증가 없이는 형식이 표류할 수 없습니다. 이것이 외부 시스템이 JSON을 안전하게 빌드할 수 있게 하는 것입니다. 계약은 버전이 움직일 때만 움직입니다. 출력은 이식 가능한 상태를 유지합니다 — 여러분 아래에서 바뀌는 형태가 아니라, 문서화되고 버전 관리되며 여러분이 소유하는 데이터입니다.

설계 배경: 오픈 코어, 종속 없음.

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는 채워 넣은 분석 출력만 담습니다. 직렬화 중에 파일 시스템이나 네트워크 I/O는 발생하지 않습니다.

적합성

Interop은 NextPDF가 소유한 버전 관리된 스키마를 정의합니다. 외부 표준을 구현하지 않습니다.

동작 계약

• 모든 결과 DTO는 InteropResultInterface를 구현하며 항상 schema_version 키를 담는 JSON 안전 배열로, 그리고 JSON 문자열로 직렬화됩니다.
• 결과 DTO(DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField)는 불변 읽기 전용 뷰입니다. 분석을 다시 실행하지 않습니다.
• SchemaLock::verify()는 고정된 스키마의 SHA-256을 보유하며 스키마 파일이 없거나 수정되면 false를 반환하므로, 와이어 계약이 조용히 표류할 수 없습니다.
• 표면은 명시적으로 버전 관리됩니다(SCHEMA_VERSION). 추가적 변경은 스키마를 증가시키고, 호환성을 깨는 변경은 새 메이저 버전을 요구합니다.
• 직렬화 중에 파일 시스템이나 네트워크 I/O는 발생하지 않습니다.

Enterprise 경계 참고

Enterprise는 Interop 동작을 변경하지 않습니다. Enterprise는 별도로 문서화된 상위 등급 기능을 더합니다. 그것들은 버전 관리된 결과 DTO를 사용하는 데 필요하지 않습니다.

Core 폴백 / 대안

스키마 고정, 버전 관리된 결과 DTO에 대한 Core 등가물은 없습니다. 이는 Pro 추가 기능입니다.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일 이름, 티켓 접두사는 범위 밖입니다.

함께 보기

• 추출 — 텍스트 및 세그먼트 결과를 생성합니다.
• 양식 — 양식 데이터 결과를 생성합니다.
• Interop — 심층 참조 — 전체 DTO 필드 참조입니다.