Interop

Sekilas pandang

NextPDF Pro menyediakan satu set berversi dari objek transfer-data hasil (DTO) yang menserialisasi keluaran analisis PDF — info dokumen, halaman, blok teks, segmentasi, dan data formulir — ke bentuk JSON yang stabil dan terkunci-skema untuk dikonsumsi oleh sistem dan perkakas eksternal.

Ketersediaan & lisensi

Kemampuan ini hadir dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tingkat-Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kemampuan ini. Interop merupakan bagian dari edisi Pro; tidak ada penanda lisensi per-fitur terpisah. Bandingkan edisi dan dapatkan lisensi.

Pemasangan

composer require nextpdf/pro:^3

Tinjauan konseptual

Ketika keluaran pemrosesan PDF melintasi batas proses atau layanan, penerima membutuhkan kontrak yang stabil. Permukaan Interop V1 menyediakannya:

• InteropResultInterface — setiap DTO hasil mengimplementasikan ini. Masing-masing menserialisasi ke array aman-JSON yang selalu membawa kunci schema_version, dan ke string JSON.
• DTO hasil — DocumentInfo, PageInfo, BoundingBox, ExtractedText / ExtractedPage / TextBlock, DocumentSegmentation / Segment, dan FormData / FormField. Masing-masing adalah tampilan imutabel dari satu hasil analisis.
• SchemaLock — sebuah penjaga CI. Ia menyimpan SHA-256 dari skema yang dibekukan dan menggagalkan build jika berkas skema berubah tanpa version bump yang sesuai, sehingga kontrak wire tidak dapat melenceng secara diam-diam.

Permukaan Interop diberi versi secara eksplisit (SCHEMA_VERSION). Perlakukan ia sebagai kontrak API publik: perubahan aditif menaikkan skema; perubahan yang memutus membutuhkan versi mayor baru.

Mengapa bekerja seperti ini

Bentuk serialisasi diperlakukan sebagai kontrak API publik, bukan detail implementasi. Setiap DTO membawa kunci schema_version, sehingga konsumen bercabang berdasarkan bentuk yang mereka terima alih-alih menebak. SchemaLock menyematkan SHA-256 dari skema yang dibekukan di CI, sehingga format tidak dapat melenceng tanpa version bump. Itulah yang memungkinkan sistem eksternal membangun terhadap JSON dengan aman: kontrak bergerak hanya ketika versinya bergerak. Keluarannya tetap portabel — data yang terdokumentasi, berversi, dan Anda miliki, bukan bentuk yang berubah di bawah Anda.

Latar belakang desain: Open core, tanpa lock-in.

Permukaan API

Class	Responsibility
InteropResultInterface	Kontrak serialisasi bersama.
DocumentInfo, PageInfo, BoundingBox	DTO dokumen/halaman umum.
ExtractedText, ExtractedPage, TextBlock	DTO ekstraksi-teks.
DocumentSegmentation, Segment	DTO segmentasi-dokumen.
FormData, FormField	DTO data-formulir.
SchemaLock	Penjaga drift-skema CI.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

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

Kasus tepi & jebakan

• toArray() selalu menyertakan schema_version; konsumen hilir sebaiknya bercabang padanya.
• SchemaLock::verify() mengembalikan false jika berkas skema hilang atau dimodifikasi.
• DTO adalah tampilan read-only; ia tidak menjalankan ulang analisis.

Performa

Serialisasi bersifat linear terhadap ukuran graf hasil.

Catatan keamanan

DTO hanya membawa keluaran analisis yang Anda isi. Tidak ada I/O sistem berkas atau jaringan yang terjadi selama serialisasi.

Konformansi

Interop mendefinisikan skema berversi milik-NextPDF; ia tidak mengimplementasikan standar eksternal.

Kontrak perilaku

• Setiap DTO hasil mengimplementasikan InteropResultInterface dan menserialisasi ke array aman-JSON yang selalu membawa kunci schema_version, dan ke string JSON.
• DTO hasil (DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField) adalah tampilan read-only yang imutabel; ia tidak menjalankan ulang analisis.
• SchemaLock::verify() menyimpan SHA-256 dari skema yang dibekukan dan mengembalikan false jika berkas skema hilang atau dimodifikasi, sehingga kontrak wire tidak dapat melenceng secara diam-diam.
• Permukaan diberi versi secara eksplisit (SCHEMA_VERSION): perubahan aditif menaikkan skema; perubahan yang memutus membutuhkan versi mayor baru.
• Tidak ada I/O sistem berkas atau jaringan yang terjadi selama serialisasi.

Catatan batas Enterprise

Enterprise tidak mengubah perilaku Interop. Enterprise menambahkan fitur tingkat-lebih-tinggi yang didokumentasikan terpisah; fitur tersebut tidak diwajibkan untuk menggunakan DTO hasil berversi.

Fallback / alternatif Core

Tidak ada padanan Core untuk DTO hasil yang terkunci-skema dan berversi. Ini adalah tambahan Pro.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Extraction — menghasilkan hasil teks dan segmen.
• Form — menghasilkan hasil data-formulir.
• Interop — Deep Reference — referensi field DTO lengkap.