Pro phiên bản

Interop — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tài liệu tham chiếu cấp hợp đồng cho NextPDF\Pro\Interop\V1. Module chứa mười bốn ký hiệu công khai: một hợp đồng tuần tự hóa (InteropResultInterface), một bộ bảo vệ toàn vẹn CI (SchemaLock), ba DTO kết quả cấp cao nhất (ExtractedText, DocumentSegmentation, FormData), và chín value object và enum hỗ trợ. Mỗi DTO là một view bất biến, tuần tự hóa được sang JSON của một kết quả phân tích. Hình dạng wire có phiên bản và bị khóa; không có gì trên bề mặt này chạy lại phân tích. View hướng tác vụ nằm trên trang năng lực.

Khả dụng & cấp phép

Năng lực này đi kèm trong NextPDF Pro (nextpdf/pro) và kích hoạt với một envelope giấy phép hạng Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực. So sánh các phiên bản và lấy giấy phép.

Không có cờ năng lực runtime nào chặn module này. Các lớp có sẵn bất cứ khi nào nextpdf/pro được cài đặt và cấp phép.

Bề mặt API công khai

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`InteropResultInterface`	—	Hợp đồng cho các DTO kết quả cấp cao nhất; mở rộng `JsonSerializable`	—	Không ném	`SCHEMA_VERSION` là chuỗi `'1.0'`.
`InteropResultInterface::toArray()`	không	Tuần tự hóa thành mảng an toàn JSON luôn mang `schema_version`	`array<string, mixed>`	Không ném	Các hiện thực cũng phát ra một bộ phân biệt `type`.
`InteropResultInterface::toJson()`	`int $flags = 0`	Mã hóa đầu ra của `toArray()`; `JSON_THROW_ON_ERROR` luôn được OR vào	`string`	`JsonException` khi dữ liệu không thể mã hóa	Truyền các cờ như `JSON_PRETTY_PRINT`.
`SchemaLock::verify()`	không	Băm `schema.json` V1 trên đĩa và so sánh với SHA-256 đã khóa	`bool`	Không ném	`false` khi tệp schema bị thiếu, không đọc được, hoặc bị sửa đổi.
`SchemaLock::expectedHash()`	không	Trả về hash đã khóa	`string`	Không ném	Đầu ra chẩn đoán để phân loại lỗi CI.
`SchemaLock::actualHash()`	không	Trả về hash của tệp schema hiện tại	`string`	Không ném	Các chuỗi sentinel `FILE_NOT_FOUND` / `READ_FAILED` thay thế hash khi lỗi I/O.
`BoundingBox`	`float $x`, `float $y`, `float $width`, `float $height`	Hộp bất biến theo điểm không gian người dùng PDF, gốc ở góc dưới bên trái	—	Không ném	`area()`, `overlaps()`, `toArray()`, `fromArray()`.
`DocumentInfo`	`int $pageCount` cùng sáu trường metadata tùy chọn	Metadata tài liệu bất biến	—	Không ném	`fromArray()` bảo vệ kiểu cho mọi trường; các trường vắng mặt dùng giá trị mặc định.
`PageInfo`	`int $pageNumber`, `float $width`, `float $height`, `int $rotation = 0`	Metadata trang bất biến	—	Không ném	`isLandscape()`; `fromArray()` ép các chuỗi số và số thực.
`ExtractedText`	`list<ExtractedPage> $pages`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Kết quả trích xuất văn bản toàn tài liệu	—	`JsonException` chỉ từ `toJson()`	`page()`, `totalBlockCount()`, `plainText()`, `fromArray()`.
`ExtractedPage`	`PageInfo $pageInfo`, `list<TextBlock> $textBlocks`	Bộ chứa theo từng trang các khối văn bản theo thứ tự đọc	—	Không ném	`plainText()` nối nội dung khối bằng dấu cách đơn.
`TextBlock`	`string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `string $fontName = ''`, `float $fontSize = 0.0`	Đoạn văn bản liền kề có định vị	—	Không ném	Tên và cỡ font là nỗ lực tốt nhất (font chiếm ưu thế trong khối).
`DocumentSegmentation`	`list<Segment> $segments`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Kết quả phân đoạn nhận biết bố cục	—	`JsonException` chỉ từ `toJson()`	`segmentCount()`, `ofType()`, `onPage()`, `contentSegments()`, `fromArray()`.
`Segment`	`SegmentType $type`, `string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `float $confidence = 1.0`, `list<Segment> $children = []`	Vùng trang đã phân loại; các con lồng nhau đệ quy	—	Không ném	Ngưỡng `isHighConfidence()` là 0.8; `descendantCount()` có tính đệ quy.
`SegmentType`	enum nền chuỗi	Mười hai trường hợp, từ `heading` đến `unknown`	—	Không ném	`isContent()` và `isStructural()` phân hoạch các trường hợp.
`FormData`	`list<FormField> $fields`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Kết quả trích xuất biểu mẫu toàn tài liệu	—	`JsonException` chỉ từ `toJson()`	`field()`, `dataFields()`, `filledCount()`, `toKeyValueMap()`, `fromArray()`.
`FormField`	`string $name`, `FormFieldType $type`, cùng sáu trường tùy chọn	Một trường biểu mẫu đã trích xuất	—	Không ném	`isFilled()` là `value !== ''`.
`FormFieldType`	enum nền chuỗi	Tám trường hợp, từ `text` đến `button`	—	Không ném	`isDataField()` là `false` cho `button` và `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

Hợp đồng hành vi

Bao bì có phiên bản. Mọi DTO cấp cao nhất (ExtractedText, DocumentSegmentation, FormData) hiện thực InteropResultInterface. Đầu ra toArray() của nó luôn mang schema_version ('1.0') và một bộ phân biệt type: extracted_text, document_segmentation, hoặc form_data.
Mã hóa JSON. toJson() ủy thác cho json_encode với JSON_THROW_ON_ERROR được OR vào các cờ của bên gọi. jsonSerialize() ủy thác cho toArray(), nên json_encode($dto) tạo ra cùng hình dạng.
Tuần tự hóa tất định. Thứ tự khóa và hình dạng do DTO cố định. Segment::toArray() bỏ qua khóa children khi rỗng; FormField::toArray() bỏ qua bounding_box khi nó là null. Bên tiêu thụ phải coi cả hai khóa là tùy chọn.
Khứ hồi. Mỗi DTO phơi bày một fromArray() tĩnh nhận một đối tượng JSON đã giải mã. Các trường được bảo vệ kiểu tại ranh giới liên tiến trình này: các giá trị vắng mặt hoặc sai kiểu dùng về giá trị mặc định đã ghi tài liệu thay vì ném lỗi.
Giá trị dự phòng enum. Một chuỗi type không nhận diện được ánh xạ tới SegmentType::Unknown trong Segment::fromArray() và tới FormFieldType::Text trong FormField::fromArray().
Tọa độ. Tọa độ BoundingBox là đơn vị không gian người dùng PDF (điểm, 1/72 inch) với gốc ở góc dưới bên trái của trang. Số trang bắt đầu từ một xuyên suốt.
Nối văn bản thuần. ExtractedPage::plainText() nối nội dung khối bằng dấu cách đơn. ExtractedText::plainText() nối các trang bằng dòng trống ("\n\n").
Truy vấn phân đoạn. ofType(), onPage(), và contentSegments() chỉ lọc các phân đoạn cấp cao nhất và trả về các danh sách được đánh chỉ số lại. contentSegments() chọn các kiểu mà SegmentType::isContent() là true: heading, sub_heading, paragraph, table, list, code.
Truy vấn biểu mẫu. FormData::dataFields() và toKeyValueMap() loại trừ các kiểu trường phi dữ liệu (button, signature). filledCount() đếm các trường có giá trị là chuỗi không rỗng.
Khóa schema. SchemaLock::verify() đọc schema.json V1 đi kèm gói, chuẩn hóa CRLF thành LF, băm bằng SHA-256, và so sánh với hằng số đã khóa trong thời gian hằng định. CI dùng nó để chặn việc schema trôi dạt âm thầm; giá trị khóa chỉ thay đổi khi có một thay đổi schema có phiên bản và có chủ ý.
Chính sách phiên bản. Bề mặt V1 là một hợp đồng công khai tường minh. Các thay đổi bổ sung sẽ nâng phiên bản schema; các thay đổi phá vỡ tương thích đòi hỏi một phiên bản major mới.

Trường hợp ngoại lệ & chế độ lỗi

Thành viên duy nhất ném lỗi trên bề mặt này là toJson(): JsonException khi mảng không thể mã hóa, ví dụ UTF-8 không hợp lệ trong nội dung đã trích xuất.
SchemaLock::verify() trả về false — không bao giờ ném — khi tệp schema bị thiếu, không đọc được, hoặc bị sửa đổi. So sánh expectedHash() với actualHash() để phân biệt trôi dạt với lỗi I/O.
Các giá trị dự phòng của fromArray() là âm thầm theo thiết kế. Một page_number sai kiểu trở thành 1; một confidence sai kiểu trở thành giá trị mặc định. Hãy kiểm tra ở phía trước khi các giá trị mặc định bịa ra là không chấp nhận được.
Ép chuỗi số là bất đối xứng. PageInfo::fromArray() chấp nhận các chuỗi số cho các trường int và float của nó; Segment và TextBlock chỉ chấp nhận int hoặc float cho confidence và font_size.
BoundingBox::fromArray() yêu cầu đủ cả bốn khóa theo hình dạng mảng đã ghi tài liệu của nó. Các DTO nhúng nó thay bằng một hộp không (hoặc null cho FormField) khi khóa bao bọc vắng mặt.
ExtractedPage::fromArray() thay bằng một page_info dự phòng là trang 1 ở 595 × 842 điểm khi khóa bị thiếu hoặc sai kiểu.
FormField::fromArray() chỉ chấp nhận boolean nghiêm ngặt cho required và read_only; các chuỗi và số nguyên truthy ánh xạ thành false.
Các con của Segment đệ quy không giới hạn độ sâu. Việc lồng cực sâu chỉ bị giới hạn bởi giới hạn bộ nhớ và stack của PHP.
Không có thao tác khóa mật mã hay chữ ký nào xảy ra trong module này. SchemaLock chỉ dùng SHA-256 như một checksum toàn vẹn tệp, nên không có hành vi đặc thù chế độ FIPS.

Tính phù hợp

Interop V1 là một hợp đồng wire có phiên bản do NextPDF sở hữu. Nó không hiện thực một tiêu chuẩn bên ngoài, nên không có bảng trích dẫn quy phạm. Ngữ nghĩa của BoundingBox phù hợp với mô hình tọa độ không gian người dùng PDF mà các hệ thống con Core sản xuất sử dụng; đó là một phát biểu về sự tương thích cấu trúc, không phải kết quả kiểm thử tính phù hợp. NextPDF không nắm giữ chứng nhận nào và không cấp chứng nhận nào.

Ghi chú phát triển

Rẽ nhánh theo schema_version ở bên tiêu thụ. Coi các khóa bổ sung là tương thích; từ chối các phiên bản major không xác định một cách tường minh.
Chạy SchemaLock::verify() trong CI. Khi thất bại, ghi log expectedHash() và actualHash() và yêu cầu một thay đổi schema có phiên bản và có chủ ý, không bao giờ là một sửa đổi tại chỗ.
Đối với các chuyến khứ hồi liên tiến trình, hãy giải mã bằng mảng kết hợp (json_decode($json, true)) và đưa kết quả vào fromArray() tương ứng.
Tất cả DTO đều final và readonly. Mở rộng bằng cách kết hợp; suy ra các view mới từ các trường công khai.
toKeyValueMap() chỉ làm phẳng các trường mang dữ liệu. Hãy đọc các trường signature trực tiếp từ FormData::$fields khi sự hiện diện của chúng có ý nghĩa.
Tái sử dụng là an toàn: các DTO không giữ trạng thái khả biến và không giữ tài nguyên, nên chúng có thể được cache, chia sẻ giữa các yêu cầu, và tuần tự hóa lặp lại.

Ranh giới công bố

Trang này chỉ ghi tài liệu về hành vi quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp trợ giúp, các bảng cơ chế, các tên tệp runbook, và các tiền tố ticket đều nằm ngoài phạm vi.