Interop

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

NextPDF Pro มีชุด result data-transfer object (DTO) ที่มีเวอร์ชัน ซึ่งทำให้เอาต์พุตการวิเคราะห์ PDF ได้แก่ ข้อมูลเอกสาร หน้า บล็อกข้อความ การแบ่งส่วน และข้อมูลฟอร์ม เป็นอนุกรมสู่รูปทรง JSON ที่เสถียรและล็อก schema ไว้ เพื่อให้ระบบและเครื่องมือภายนอกนำไปใช้

การมีให้ใช้งานและการอนุญาต

ความสามารถนี้จัดส่งใน NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วยซองใบอนุญาตระดับ Pro การนำไปติดตั้งที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ Interop เป็นส่วนหนึ่งของรุ่น Pro โดยไม่มีแฟล็กใบอนุญาตแยกต่อฟีเจอร์ เปรียบเทียบรุ่นและขอใบอนุญาต

การติดตั้ง

composer require nextpdf/pro:^3

ภาพรวมเชิงแนวคิด

เมื่อเอาต์พุตการประมวลผล PDF ข้ามขอบเขตของกระบวนการหรือบริการ ผู้รับต้องการสัญญาที่เสถียร พื้นผิว Interop V1 มอบสิ่งนั้น:

• InteropResultInterface DTO ผลลัพธ์ทุกตัวนำสิ่งนี้ไปใช้ แต่ละตัวทำให้เป็นอนุกรมสู่อาร์เรย์ที่ปลอดภัยต่อ JSON ซึ่งนำพาคีย์ schema_version เสมอ และสู่สตริง JSON
• DTO ผลลัพธ์ DocumentInfo, PageInfo, BoundingBox, ExtractedText / ExtractedPage / TextBlock, DocumentSegmentation / Segment และ FormData / FormField แต่ละตัวเป็นมุมมองที่ไม่เปลี่ยนแปลงของผลการวิเคราะห์หนึ่งรายการ
• SchemaLock การ์ดของ CI ที่เก็บ SHA-256 ของ schema ที่ตรึงไว้ และทำให้บิลด์ล้มเหลวหาก schema file เปลี่ยนแปลงโดยไม่มีการเพิ่มเวอร์ชันที่สอดคล้องกัน เพื่อให้สัญญาบนสายไม่เลื่อนไหลอย่างเงียบ ๆ

พื้นผิว Interop มีเวอร์ชันอย่างชัดเจน (SCHEMA_VERSION) จงปฏิบัติต่อมันเสมือนสัญญา API สาธารณะ การเปลี่ยนแปลงแบบเพิ่มเข้าจะเพิ่มเวอร์ชันของ schema การเปลี่ยนแปลงที่ทำลายความเข้ากันได้ต้องใช้เวอร์ชันเมเจอร์ใหม่

เหตุใดจึงทำงานเช่นนี้

รูปทรงการทำให้เป็นอนุกรมถูกปฏิบัติเสมือนสัญญา API สาธารณะ ไม่ใช่รายละเอียดการนำไปใช้ DTO ทุกตัวนำพาคีย์ schema_version ผู้บริโภคจึงแยกสาขาตามรูปทรงที่ได้รับแทนที่จะคาดเดา SchemaLock ตรึง SHA-256 ของ schema ที่ตรึงไว้ใน CI รูปแบบจึงไม่อาจเลื่อนไหลได้โดยไม่มีการเพิ่มเวอร์ชัน นั่นคือสิ่งที่ทำให้ระบบภายนอกสร้างบน JSON ได้อย่างปลอดภัย สัญญาจะขยับก็ต่อเมื่อเวอร์ชันขยับเท่านั้น เอาต์พุตยังคงพกพาได้ เป็นข้อมูลที่มีเอกสารกำกับ มีเวอร์ชัน และเป็นของคุณ ไม่ใช่รูปทรงที่แปรเปลี่ยนใต้เท้าคุณ

เบื้องหลังการออกแบบ: Open core ไม่ผูกมัด

พื้นผิว API

คลาส	ความรับผิดชอบ
InteropResultInterface	สัญญาการทำให้เป็นอนุกรมร่วม
DocumentInfo, PageInfo, BoundingBox	DTO เอกสาร/หน้าร่วม
ExtractedText, ExtractedPage, TextBlock	DTO การสกัดข้อความ
DocumentSegmentation, Segment	DTO การแบ่งส่วนเอกสาร
FormData, FormField	DTO ข้อมูลฟอร์ม
SchemaLock	การ์ดป้องกันการเลื่อนไหลของ schema ใน 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 หาก schema file หายไปหรือถูกแก้ไข
• DTO เป็นมุมมองแบบอ่านอย่างเดียว โดยไม่รันการวิเคราะห์ซ้ำ

ประสิทธิภาพ

การทำให้เป็นอนุกรมเป็นเชิงเส้นตามขนาดของกราฟผลลัพธ์

บันทึกด้านความปลอดภัย

DTO นำพาเฉพาะเอาต์พุตการวิเคราะห์ที่คุณเติมเข้าไป ไม่มี I/O ระบบไฟล์หรือเครือข่ายเกิดขึ้นระหว่างการทำให้เป็นอนุกรม

ความสอดคล้องกับมาตรฐาน

Interop กำหนด schema ที่มีเวอร์ชันซึ่งเป็นของ NextPDF เอง โดยไม่นำมาตรฐานภายนอกไปใช้

สัญญาพฤติกรรม

• DTO ผลลัพธ์ทุกตัวนำ InteropResultInterface ไปใช้และทำให้เป็นอนุกรมสู่อาร์เรย์ที่ปลอดภัยต่อ JSON ซึ่งนำพาคีย์ schema_version เสมอ และสู่สตริง JSON
• DTO ผลลัพธ์ (DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField) เป็นมุมมองแบบอ่านอย่างเดียวที่ไม่เปลี่ยนแปลง โดยไม่รันการวิเคราะห์ซ้ำ
• SchemaLock::verify() เก็บ SHA-256 ของ schema ที่ตรึงไว้และคืนค่า false หาก schema file หายไปหรือถูกแก้ไข เพื่อให้สัญญาบนสายไม่เลื่อนไหลอย่างเงียบ ๆ
• พื้นผิวมีเวอร์ชันอย่างชัดเจน (SCHEMA_VERSION) การเปลี่ยนแปลงแบบเพิ่มเข้าจะเพิ่มเวอร์ชันของ schema การเปลี่ยนแปลงที่ทำลายความเข้ากันได้ต้องใช้เวอร์ชันเมเจอร์ใหม่
• ไม่มี I/O ระบบไฟล์หรือเครือข่ายเกิดขึ้นระหว่างการทำให้เป็นอนุกรม

บันทึกขอบเขตของ Enterprise

Enterprise ไม่เปลี่ยนพฤติกรรมของ Interop Enterprise เพิ่มฟีเจอร์ระดับสูงขึ้นที่บันทึกแยกต่างหาก ซึ่งไม่จำเป็นต่อการใช้ DTO ผลลัพธ์ที่มีเวอร์ชัน

ทางสำรอง / ทางเลือกของ Core

ไม่มีสิ่งเทียบเท่าใน Core สำหรับ DTO ผลลัพธ์ที่ล็อก schema และมีเวอร์ชัน นี่เป็นการเพิ่มเติมของ Pro

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

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

ดูเพิ่มเติม

• Extraction — ผลิตผลลัพธ์ข้อความและส่วน
• Form — ผลิตผลลัพธ์ข้อมูลฟอร์ม
• Interop — Deep Reference — การอ้างอิงฟิลด์ DTO แบบเต็ม