Pro edisi

Interop — Referensi Mendalam

Sekilas

Halaman ini adalah referensi tingkat kontrak untuk NextPDF\Pro\Interop\V1. Modul ini berisi empat belas simbol publik: satu kontrak serialisasi (InteropResultInterface), satu penjaga integritas CI (SchemaLock), tiga DTO hasil tingkat atas (ExtractedText, DocumentSegmentation, FormData), serta sembilan value object dan enum pendukung. Setiap DTO adalah tampilan imutabel dan JSON-serializable dari satu hasil analisis. Bentuk wire-nya berversi dan terkunci; tidak ada satu pun pada permukaan ini yang menjalankan ulang analisis. Tampilan berorientasi-tugas tersedia di halaman kapabilitas.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan amplop lisensi tingkat Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag kapabilitas runtime yang menggerbang modul ini. Kelas-kelas tersedia setiap kali nextpdf/pro terpasang dan berlisensi.

Permukaan API publik

Symbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
`InteropResultInterface`	—	Kontrak untuk DTO hasil tingkat atas; memperluas `JsonSerializable`	—	Tidak melempar	`SCHEMA_VERSION` adalah string `'1.0'`.
`InteropResultInterface::toArray()`	none	Menserialisasi ke array JSON-safe yang selalu membawa `schema_version`	`array<string, mixed>`	Tidak melempar	Implementasi juga memancarkan discriminator `type`.
`InteropResultInterface::toJson()`	`int $flags = 0`	Mengenkode keluaran `toArray()`; `JSON_THROW_ON_ERROR` selalu di-OR-kan	`string`	`JsonException` pada data yang tidak dapat dienkode	Berikan flag seperti `JSON_PRETTY_PRINT`.
`SchemaLock::verify()`	none	Meng-hash `schema.json` V1 di disk dan membandingkannya dengan SHA-256 terkunci	`bool`	Tidak melempar	`false` ketika berkas skema hilang, tidak terbaca, atau dimodifikasi.
`SchemaLock::expectedHash()`	none	Mengembalikan hash terkunci	`string`	Tidak melempar	Keluaran diagnostik untuk triase kegagalan CI.
`SchemaLock::actualHash()`	none	Mengembalikan hash dari berkas skema saat ini	`string`	Tidak melempar	String sentinel `FILE_NOT_FOUND` / `READ_FAILED` menggantikan hash pada kegagalan I/O.
`BoundingBox`	`float $x`, `float $y`, `float $width`, `float $height`	Box imutabel dalam titik user-space PDF, origin di kiri-bawah	—	Tidak melempar	`area()`, `overlaps()`, `toArray()`, `fromArray()`.
`DocumentInfo`	`int $pageCount` plus enam field metadata opsional	Metadata dokumen imutabel	—	Tidak melempar	`fromArray()` menjaga tipe setiap field; field yang absen jatuh ke default.
`PageInfo`	`int $pageNumber`, `float $width`, `float $height`, `int $rotation = 0`	Metadata halaman imutabel	—	Tidak melempar	`isLandscape()`; `fromArray()` mengoersi string numerik dan float.
`ExtractedText`	`list<ExtractedPage> $pages`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Hasil ekstraksi teks seluruh dokumen	—	`JsonException` dari `toJson()` saja	`page()`, `totalBlockCount()`, `plainText()`, `fromArray()`.
`ExtractedPage`	`PageInfo $pageInfo`, `list<TextBlock> $textBlocks`	Kontainer per-halaman berisi blok teks dalam urutan baca	—	Tidak melempar	`plainText()` menggabungkan konten blok dengan spasi tunggal.
`TextBlock`	`string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `string $fontName = ''`, `float $fontSize = 0.0`	Runtun teks kontigu yang terposisi	—	Tidak melempar	Nama dan ukuran font bersifat best-effort (font dominan dalam blok).
`DocumentSegmentation`	`list<Segment> $segments`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Hasil segmentasi yang sadar-tata-letak	—	`JsonException` dari `toJson()` saja	`segmentCount()`, `ofType()`, `onPage()`, `contentSegments()`, `fromArray()`.
`Segment`	`SegmentType $type`, `string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `float $confidence = 1.0`, `list<Segment> $children = []`	Region halaman terklasifikasi; anak bersarang secara rekursif	—	Tidak melempar	Ambang `isHighConfidence()` adalah 0.8; `descendantCount()` bersifat rekursif.
`SegmentType`	enum berbasis string	Dua belas kasus, `heading` hingga `unknown`	—	Tidak melempar	`isContent()` dan `isStructural()` mempartisi kasus-kasusnya.
`FormData`	`list<FormField> $fields`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Hasil ekstraksi formulir seluruh dokumen	—	`JsonException` dari `toJson()` saja	`field()`, `dataFields()`, `filledCount()`, `toKeyValueMap()`, `fromArray()`.
`FormField`	`string $name`, `FormFieldType $type`, plus enam field opsional	Satu field formulir terekstraksi	—	Tidak melempar	`isFilled()` adalah `value !== ''`.
`FormFieldType`	enum berbasis string	Delapan kasus, `text` hingga `button`	—	Tidak melempar	`isDataField()` adalah `false` untuk `button` dan `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

Kontrak perilaku

Amplop berversi. Setiap DTO tingkat atas (ExtractedText, DocumentSegmentation, FormData) mengimplementasikan InteropResultInterface. Keluaran toArray()-nya selalu membawa schema_version ('1.0') dan discriminator type: extracted_text, document_segmentation, atau form_data.
Enkoding JSON. toJson() mendelegasikan ke json_encode dengan JSON_THROW_ON_ERROR di-OR-kan ke flag pemanggil. jsonSerialize() mendelegasikan ke toArray(), sehingga json_encode($dto) menghasilkan bentuk yang sama.
Serialisasi deterministik. Urutan dan bentuk kunci ditetapkan oleh DTO. Segment::toArray() menghilangkan kunci children ketika kosong; FormField::toArray() menghilangkan bounding_box ketika bernilai null. Konsumen harus memperlakukan kedua kunci sebagai opsional.
Round trip. Setiap DTO memaparkan fromArray() statis yang menerima objek JSON terdekode. Field dijaga-tipe pada batas antar-proses ini: nilai yang absen atau salah-tipe jatuh ke default terdokumentasi alih-alih melempar.
Fallback enum. String type yang tidak dikenali dipetakan ke SegmentType::Unknown di Segment::fromArray() dan ke FormFieldType::Text di FormField::fromArray().
Koordinat. Koordinat BoundingBox adalah unit user-space PDF (titik, 1/72 inci) dengan origin di sudut kiri-bawah halaman. Nomor halaman berbasis-satu di seluruhnya.
Penggabungan teks polos. ExtractedPage::plainText() menggabungkan konten blok dengan spasi tunggal. ExtractedText::plainText() menggabungkan halaman dengan baris kosong ("\n\n").
Kueri segmentasi. ofType(), onPage(), dan contentSegments() memfilter hanya segmen tingkat atas dan mengembalikan list yang diindeks-ulang. contentSegments() memilih tipe di mana SegmentType::isContent() bernilai true: heading, sub_heading, paragraph, table, list, code.
Kueri formulir. FormData::dataFields() dan toKeyValueMap() mengecualikan tipe field non-data (button, signature). filledCount() menghitung field yang nilainya berupa string non-kosong.
Kunci skema. SchemaLock::verify() membaca schema.json V1 yang disertakan dengan paket, menormalisasi CRLF ke LF, meng-hash dengan SHA-256, dan membandingkannya dengan konstanta terkunci dalam waktu konstan. CI menggunakannya untuk memblokir pergeseran skema diam-diam; nilai kunci hanya berubah dengan perubahan skema berversi yang disengaja.
Kebijakan versi. Permukaan V1 adalah kontrak publik eksplisit. Perubahan aditif menaikkan versi skema; perubahan yang memutus memerlukan versi mayor baru.

Kasus tepi & mode kegagalan

Satu-satunya anggota yang melempar pada permukaan ini adalah toJson(): JsonException ketika array tidak dapat dienkode, misalnya UTF-8 tidak valid dalam konten terekstraksi.
SchemaLock::verify() mengembalikan false — tidak pernah melempar — ketika berkas skema hilang, tidak terbaca, atau dimodifikasi. Bandingkan expectedHash() dengan actualHash() untuk membedakan pergeseran dari kegagalan I/O.
Fallback fromArray() bersifat diam-diam secara desain. page_number yang salah-tipe menjadi 1; confidence yang salah-tipe menjadi default. Validasi di hulu ketika default yang dibuat-buat tidak dapat diterima.
Koersi string numerik bersifat asimetris. PageInfo::fromArray() menerima string numerik untuk field int dan float-nya; Segment dan TextBlock hanya menerima int atau float untuk confidence dan font_size.
BoundingBox::fromArray() mensyaratkan keempat kunci sesuai bentuk array terdokumentasinya. DTO yang menyematkannya menggantikan box nol (atau null untuk FormField) ketika kunci pembungkusnya absen.
ExtractedPage::fromArray() menggantikan page_info fallback berupa halaman 1 pada 595 × 842 titik ketika kuncinya hilang atau salah-tipe.
FormField::fromArray() hanya menerima boolean ketat untuk required dan read_only; string truthy dan integer dipetakan ke false.
Anak Segment berekursi tanpa batas kedalaman. Penyarangan yang sangat dalam hanya dibatasi oleh batas memori dan stack PHP.
Tidak ada operasi kunci kriptografis atau tanda tangan yang terjadi dalam modul ini. SchemaLock menggunakan SHA-256 semata sebagai checksum integritas berkas, sehingga tidak ada perilaku khusus mode FIPS.

Kesesuaian

Interop V1 adalah kontrak wire berversi milik NextPDF. Ia tidak mengimplementasikan standar eksternal, sehingga tidak ada tabel sitasi normatif. Semantik BoundingBox selaras dengan model koordinat user-space PDF yang digunakan subsistem Core penghasil; itu adalah pernyataan keselarasan struktural, bukan hasil uji kesesuaian. NextPDF tidak memegang sertifikasi apa pun dan tidak memberikan apa pun.

Catatan pengembangan

Bercabang pada schema_version di konsumen. Perlakukan kunci aditif sebagai kompatibel; tolak versi mayor tak dikenal secara eksplisit.
Jalankan SchemaLock::verify() di CI. Pada kegagalan, catat expectedHash() dan actualHash() serta wajibkan perubahan skema berversi yang disengaja, tidak pernah suntingan di tempat.
Untuk round trip antar-proses, dekode dengan array asosiatif (json_decode($json, true)) dan umpankan hasilnya ke fromArray() yang cocok.
Semua DTO bersifat final dan readonly. Perluas melalui komposisi; turunkan tampilan baru dari field publik.
toKeyValueMap() meratakan hanya field pembawa-data. Baca field signature langsung dari FormData::$fields ketika keberadaannya penting.
Penggunaan-ulang aman: DTO tidak menyimpan state mutabel maupun resource, sehingga dapat di-cache, dibagi antar-permintaan, dan diserialisasi berulang kali.

Batas publikasi

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