Enterprise edisi

Common — Referensi Mendalam

Sekilas

Halaman ini adalah referensi mendalam untuk namespace NextPDF\Enterprise\Common. Namespace ini mengirimkan satu simbol publik: value object BoundingBox. Ini adalah persegi panjang yang imutabel dan ternormalisasi untuk pemosisian spasial yang independen terhadap resolusi pada sebuah halaman. Surface Enterprise Intelligence dan Privacy memakainya untuk geometri sel tabel, lokasi entitas, dan zona redaksi. Modul ini tidak melakukan I/O, tidak menyimpan konten dokumen, dan tidak menyentuh kriptografi. Untuk panduan alur kerja, baca halaman kapabilitas Common terlebih dahulu.

Ketersediaan & lisensi

Kapabilitas ini dikirimkan dalam NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan envelope lisensi tier Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Primitif itu sendiri tidak melakukan gating lisensi; gating terjadi pada surface Enterprise yang memakainya. Tidak ada padanan kelas ini di tier Core maupun tier Pro. Kelas ini hanya dikirimkan dalam paket nextpdf/enterprise dan tidak menduplikasi atau menggantikan tipe geometri Core.

Permukaan API publik

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
`BoundingBox::__construct`	`float $x`, `float $y`, `float $width`, `float $height`	Memvalidasi setiap nilai terhadap `[0.0, 1.0]`, lalu memvalidasi kedua jumlah tepi	`BoundingBox`	`InvalidArgumentException` ketika sebuah nilai di luar rentang atau jumlah tepi melebihi `1.0 + 1e-9`	Keempat nilai menjadi properti `public readonly`
`BoundingBox::area`	tidak ada	Mengalikan `width` dengan `height`	`float`	Tidak ada yang dideklarasikan	Mengembalikan `0.0` untuk box degenerasi
`BoundingBox::contains`	`self $other`	Menguji apakah `$other` sepenuhnya berada di dalam box ini	`bool`	Tidak ada yang dideklarasikan	Tepi kanan dan bawah mentoleransi `+1e-9`; tepi kiri dan atas dibandingkan secara persis
`BoundingBox::overlaps`	`self $other`	Menguji perpotongan persegi panjang yang strict	`bool`	Tidak ada yang dideklarasikan	Operan berarea nol di salah satu sisi mengembalikan `false`

Tanda tangan entry-point

final readonly class BoundingBox
{
    public function __construct(
        public float $x,
        public float $y,
        public float $width,
        public float $height,
    )

    public function area(): float

    public function contains(self $other): bool

    public function overlaps(self $other): bool
}

Kontrak perilaku

Model koordinat

Keempat nilai adalah pecahan dari dimensi halaman, ternormalisasi ke rentang [0.0, 1.0].
x menempatkan tepi kiri dan y menempatkan tepi atas box. x + width dan y + height membatasi tepi kanan dan bawah.
Normalisasi membuat setiap operasi independen terhadap resolusi. Box yang sama menunjuk region halaman yang sama pada ukuran render atau DPI berapa pun.

Konstruksi

Konstruktor adalah satu-satunya titik validasi. Sebuah koordinat di luar [0.0, 1.0] memunculkan InvalidArgumentException; pesannya menyebutkan komponen yang bermasalah dan nilai yang diterima.
Jumlah tepi di atas 1.0 + 1e-9 memunculkan InvalidArgumentException; pesannya melaporkan kedua operan dan jumlahnya. Toleransi 1e-9 menyerap pembulatan floating-point dari aritmetika normalisasi di hulu.
Instance yang dikonstruksi bersifat imutabel. Kelas ini final readonly, sehingga penulisan properti gagal dengan Error PHP dan kelas tidak dapat diperluas.

Predikat

area() mengembalikan width * height. Ini adalah komputasi murni tanpa efek samping.
contains() mengembalikan true ketika box lain sepenuhnya berada di dalam box ini. Perbandingan tepi kanan dan bawah membawa toleransi +1e-9; perbandingan tepi kiri dan atas bersifat persis. Setiap box memuat dirinya sendiri, dan box berarea nol dapat dimuat.
overlaps() mengembalikan true pada perpotongan persegi panjang yang strict. Keempat perbandingan tepi bersifat strict, tanpa toleransi. Jika salah satu operan berarea nol, hasilnya false.
Oleh karena itu containment tidak menyiratkan overlap: box degenerasi di dalam box lain dimuat tetapi tidak pernah overlap.
Tidak ada metode yang melakukan I/O, persistensi, akses jaringan, atau logging, dan tidak ada yang menyimpan konten dokumen atau data pribadi. Tidak ada resource milik operator untuk surface ini.

Konsumen

Modul Enterprise berbagi primitif ini alih-alih mendefinisikan geometri per-modul. Pada Intelligence, output TableExtractor membawanya pada nilai TableCell dan KeyValuePair. Pada Privacy, PiiEntity, RedactionFinding, dan ZoneRedaction menempatkan konten dengannya, dan RedactionEngine memakai lokasi-lokasi tersebut. Kontrak surface-surface itu didokumentasikan pada halaman referensinya sendiri.

Kasus tepi & mode kegagalan

Komponen di luar rentang. Salah satu dari keempat nilai di bawah 0.0 atau di atas 1.0 memunculkan InvalidArgumentException saat konstruksi. INF dan -INF ditolak oleh guard yang sama.
Overflow jumlah tepi. x + width atau y + height di atas 1.0 + 1e-9 memunculkan InvalidArgumentException. Jumlah dalam toleransi 1e-9 dikonstruksi dengan sukses.
Input NAN. Guard rentang menggunakan perbandingan terurut, dan setiap perbandingan terurut dengan NAN bernilai false, sehingga komponen NAN tidak ditolak. Instance semacam itu melaporkan area NAN dan mengembalikan false dari kedua predikat. Sanitasi sumber float di hulu sebelum konstruksi.
Box berarea nol. Box dengan lebar nol atau tinggi nol tidak pernah overlap dengan apa pun, termasuk dirinya sendiri. Box ini tetap dapat dimuat oleh box yang tidak degenerasi. Perhitungkan asimetri ini dalam logika perpotongan.
Box yang bersentuhan tepi. Dua box yang hanya berbagi tepi atau sudut tidak overlap; uji perpotongan bersifat strict.
Asimetri toleransi containment. Box dalam yang tepi kiri atau atasnya berada di luar box luar sebesar berapa pun gagal containment; hanya tepi kanan dan bawah yang menerima kelonggaran 1e-9.
Mode FIPS. Modul ini tidak melakukan operasi kriptografis; mode FIPS tidak mengubah perilakunya.

Konformansi

Modul ini tidak mengimplementasikan standar normatif apa pun dan tidak membuat klaim konformansi. Ini adalah primitif geometri yang tervalidasi. Semantik ruang koordinat PDF untuk fitur-fitur yang memakainya didokumentasikan pada halaman fitur-fitur tersebut. NextPDF tidak memegang sertifikasi apa pun dan tidak memberikan sertifikasi apa pun; dukungan bukanlah konformansi, dan konformansi bukanlah sertifikasi. Tidak ada pembatasan kontrol ekspor yang berlaku pada surface ini, dan referensi ini bukan opini hukum.

Catatan pengembangan

Kelas ini tersedia sejak nextpdf/enterprise 2.2.0; permukaan publiknya tidak berubah pada 3.1.0.
Konversikan koordinat ruang-halaman absolut menjadi pecahan relatif-halaman sebelum konstruksi. Kelas ini memvalidasi rentang, bukan semantik; ia tidak dapat mendeteksi region yang tampak-masuk-akal-tetapi-salah.
Instance adalah value object biasa dan murah untuk dikonstruksi. Jangan pool atau cache mereka.
Dua instance dengan koordinat identik dianggap sama di bawah loose equality (==); strict identity (===) membedakan keduanya. Utamakan perbandingan koordinat dalam pengujian.
Untuk geometri di luar predikat boolean, turunkan tepi dari properti publik: tepi kanan x + width, tepi bawah y + height.
Saat menguji batas toleransi, periksa kedua sisi 1e-9 pada guard jumlah tepi dan pada perbandingan kanan/bawah containment.

Batas publikasi

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