Pro รุ่น

Interop — การอ้างอิงเชิงลึก

ภาพรวมโดยสังเขป

หน้านี้เป็นการอ้างอิงระดับข้อกำหนดสำหรับ NextPDF\Pro\Interop\V1 โมดูลนี้มีสัญลักษณ์สาธารณะ 14 รายการ ได้แก่ ข้อกำหนดการทำอนุกรม 1 รายการ ( InteropResultInterface ) ตัวป้องกันความสมบูรณ์ใน CI 1 รายการ ( SchemaLock ) DTO ผลลัพธ์ระดับบนสุด 3 รายการ ( ExtractedText , DocumentSegmentation , FormData ) และ value object กับ enum สนับสนุนอีก 9 รายการ ทุก DTO เป็นมุมมองแบบไม่เปลี่ยนแปลงและทำอนุกรมเป็น JSON ได้ของผลการวิเคราะห์หนึ่งรายการ รูปแบบบนสายส่งถูกกำหนดเวอร์ชันและล็อกไว้ ไม่มีสิ่งใดบนพื้นผิวนี้ที่รันการวิเคราะห์ซ้ำ มุมมองเชิงงานอยู่ที่ หน้าความสามารถ

ความพร้อมใช้งานและการอนุญาต

ความสามารถนี้มาพร้อมกับ NextPDF Pro ( nextpdf/pro ) และเปิดใช้งานด้วย license envelope ระดับ 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()` โดย OR `JSON_THROW_ON_ERROR` เข้าไปเสมอ	`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` จะแทนที่แฮชเมื่อเกิดข้อผิดพลาด I/O
`BoundingBox`	`float $x`, `float $y`, `float $width`, `float $height`	กล่องแบบไม่เปลี่ยนแปลงในหน่วยพอยต์ของ PDF user-space จุดกำเนิดอยู่มุมล่างซ้าย	—	ไม่โยนข้อยกเว้น	`area()`, `overlaps()`, `toArray()`, `fromArray()`
`DocumentInfo`	`int $pageCount` บวกฟิลด์เมทาดาทาที่เป็นทางเลือกอีกหกฟิลด์	เมทาดาทาเอกสารแบบไม่เปลี่ยนแปลง	—	ไม่โยนข้อยกเว้น	`fromArray()` ตรวจชนิดทุกฟิลด์ ฟิลด์ที่ขาดหายจะใช้ค่าเริ่มต้น
`PageInfo`	`int $pageNumber`, `float $width`, `float $height`, `int $rotation = 0`	เมทาดาทาหน้าแบบไม่เปลี่ยนแปลง	—	ไม่โยนข้อยกเว้น	`isLandscape()`; `fromArray()` แปลงสตริงตัวเลขและ float
`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`	enum แบบสตริง	สิบสองเคส ตั้งแต่ `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`	enum แบบสตริง	แปดเคส ตั้งแต่ `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 โดย OR JSON_THROW_ON_ERROR เข้ากับแฟล็กของผู้เรียก jsonSerialize() มอบหมายให้ toArray() ดังนั้น json_encode($dto) จึงให้รูปแบบเดียวกัน
การทำอนุกรมแบบกำหนดได้แน่นอน ลำดับคีย์และรูปแบบถูกกำหนดตายตัวโดย DTO Segment::toArray() ละคีย์ children เมื่อว่างเปล่า FormField::toArray() ละ bounding_box เมื่อเป็น null ผู้บริโภคต้องถือว่าคีย์ทั้งสองเป็นทางเลือก
การไป-กลับ แต่ละ DTO เปิดเผย fromArray() แบบสแตติกที่รับอ็อบเจกต์ JSON ที่ถอดรหัสแล้ว ฟิลด์ถูกตรวจชนิดที่ขอบเขตข้ามกระบวนการนี้ ค่าที่ขาดหายหรือชนิดผิดจะใช้ค่าเริ่มต้นตามที่ระบุไว้แทนการโยนข้อยกเว้น
ค่าสำรองของ enum สตริง type ที่ไม่รู้จักจะแมปไปยัง SegmentType::Unknown ใน Segment::fromArray() และไปยัง FormFieldType::Text ใน FormField::fromArray()
พิกัด พิกัดของ BoundingBox เป็นหน่วย PDF user-space (พอยต์ 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() นับฟิลด์ที่มีค่าเป็นสตริงที่ไม่ว่างเปล่า
Schema lock SchemaLock::verify() อ่านไฟล์ V1 schema.json ที่มาพร้อมแพ็กเกจ แปลง CRLF เป็น LF แฮชด้วย SHA-256 และเปรียบเทียบกับค่าคงที่ที่ล็อกไว้ในเวลาคงที่ CI ใช้มันเพื่อปิดกั้นการเลื่อนของสคีมาแบบเงียบ ค่าล็อกจะเปลี่ยนเฉพาะเมื่อมีการเปลี่ยนแปลงสคีมาที่กำหนดเวอร์ชันโดยตั้งใจ
นโยบายการกำหนดเวอร์ชัน พื้นผิว V1 เป็นข้อกำหนดสาธารณะที่ชัดเจน การเปลี่ยนแปลงแบบเพิ่มเติมจะเลื่อนเวอร์ชันสคีมา การเปลี่ยนแปลงที่ทำลายความเข้ากันได้ต้องใช้เวอร์ชันหลักใหม่

กรณีขอบและโหมดความล้มเหลว

สมาชิกเดียวบนพื้นผิวนี้ที่โยนข้อยกเว้นคือ toJson() ได้แก่ JsonException เมื่ออาร์เรย์เข้ารหัสไม่ได้ เช่น UTF-8 ที่ไม่ถูกต้องในเนื้อหาที่สกัดมา
SchemaLock::verify() คืนค่า false โดยไม่เคยโยนข้อยกเว้น เมื่อไฟล์สคีมาหายไป อ่านไม่ได้ หรือถูกแก้ไข เปรียบเทียบ expectedHash() กับ actualHash() เพื่อแยกแยะการเลื่อนของสคีมาออกจากข้อผิดพลาด I/O
ค่าสำรองของ 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 user-space ที่ระบบย่อย Core ผู้ผลิตใช้ นั่นเป็นข้อความเชิงการจัดแนวโครงสร้าง ไม่ใช่ผลการทดสอบความสอดคล้อง NextPDF ไม่ถือครองการรับรองใดและไม่มอบให้ผู้ใด

บันทึกการพัฒนา

แยกทางตาม schema_version ในผู้บริโภค ถือว่าคีย์ที่เพิ่มเข้ามาเข้ากันได้ ปฏิเสธเวอร์ชันหลักที่ไม่รู้จักอย่างชัดเจน
รัน SchemaLock::verify() ใน CI เมื่อล้มเหลว ให้บันทึก expectedHash() และ actualHash() และกำหนดให้ต้องมีการเปลี่ยนแปลงสคีมาที่กำหนดเวอร์ชันโดยตั้งใจ ไม่ใช่การแก้ไขในที่
สำหรับการไป-กลับข้ามกระบวนการ ให้ถอดรหัสด้วยอาร์เรย์เชื่อมโยง ( json_decode($json, true) ) และป้อนผลลัพธ์ให้กับ fromArray() ที่ตรงกัน
DTO ทั้งหมดเป็น final และ readonly ขยายด้วยการประกอบ สร้างมุมมองใหม่จากฟิลด์สาธารณะ
toKeyValueMap() แผ่เฉพาะฟิลด์ที่มีข้อมูลเท่านั้น อ่านฟิลด์ signature โดยตรงจาก FormData::$fields เมื่อการมีอยู่ของมันสำคัญ
การใช้ซ้ำปลอดภัย DTO ไม่ถือสถานะที่เปลี่ยนแปลงได้และไม่ถือทรัพยากร จึงสามารถแคช แบ่งใช้ข้ามคำขอ และทำอนุกรมซ้ำได้

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทาง namespace ภายใน คลาสช่วยเหลือ ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้าทิกเก็ตอยู่นอกขอบเขต