Common — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF\Enterprise\Common ad alanının derinlemesine başvurusudur. Ad alanı tek bir genel simge sunar: BoundingBox değer nesnesi. Bu, bir sayfada çözünürlükten bağımsız uzamsal konumlandırma için değişmez, normalize edilmiş bir dikdörtgendir. Enterprise Intelligence ve Privacy yüzeyleri bunu tablo hücresi geometrisi, varlık konumları ve redaksiyon bölgeleri için kullanır. Modül hiçbir giriş/çıkış işlemi yapmaz, hiçbir belge içeriği tutmaz ve kriptografiye dokunmaz. İş akışı rehberliği için önce Common yetenek sayfası’nı okuyun.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) ile sunulur ve Enterprise katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve lisans edinin.

İlkelin kendisi hiçbir lisans kapılaması yapmaz; kapılama, onu kullanan Enterprise yüzeylerinde gerçekleşir. Bu sınıfın hiçbir Core katmanı veya Pro katmanı eşdeğeri yoktur. Yalnızca nextpdf/enterprise paketinde sunulur ve Core geometri türlerini çoğaltmaz ya da değiştirmez.

Genel API yüzeyi

Simge	Parametreler	Varsayılan davranış	Döndürür	Fırlatır / başarısız olur	Notlar
BoundingBox::__construct	float $x, float $y, float $width, float $height	Her değeri [0.0, 1.0] aralığına göre doğrular, ardından her iki kenar toplamını doğrular	BoundingBox	Bir değer aralık dışı olduğunda veya bir kenar toplamı 1.0 + 1e-9 değerini aştığında InvalidArgumentException	Dört değerin tümü public readonly özelliği olur
BoundingBox::area	yok	width değerini height ile çarpar	float	Bildirilmiş bir şey yok	Yozlaşmış kutular için 0.0 döndürür
BoundingBox::contains	self $other	$other değerinin tamamen bu kutunun içinde olup olmadığını test eder	bool	Bildirilmiş bir şey yok	Sağ ve alt kenarlar +1e-9 tolerans tanır; sol ve üst kenarlar tam olarak karşılaştırılır
BoundingBox::overlaps	self $other	Kesin bir dikdörtgen kesişimini test eder	bool	Bildirilmiş bir şey yok	Herhangi bir taraftaki sıfır alanlı bir işlenen false döndürür

Giriş noktası imzası

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
}

Davranış sözleşmesi

Koordinat modeli

• Dört değerin tümü, sayfa boyutlarının kesirleridir ve [0.0, 1.0] aralığına normalize edilmiştir.
• x, kutunun sol kenarını; y ise üst kenarını konumlandırır. x + width ve y + height, sağ ve alt kenarları sınırlar.
• Normalizasyon, her işlemi çözünürlükten bağımsız kılar. Aynı kutu, herhangi bir işleme boyutu veya DPI’da aynı sayfa bölgesini adresler.

Yapım

• Yapıcı, tek doğrulama noktasıdır. [0.0, 1.0] aralığı dışındaki bir koordinat InvalidArgumentException fırlatır; mesaj, sorunlu bileşeni ve alınan değeri belirtir.
• 1.0 + 1e-9 değerinin üzerindeki bir kenar toplamı InvalidArgumentException fırlatır; mesaj, her iki işleneni ve toplamlarını bildirir. 1e-9 toleransı, önceki normalizasyon aritmetiğinden gelen kayan noktalı yuvarlamayı soğurur.
• Oluşturulan bir örnek değişmezdir. Sınıf final readonly olduğundan, özellik yazma işlemleri bir PHP Error ile başarısız olur ve sınıf genişletilemez.

Yüklemler

• area(), width * height değerini döndürür. Yan etkisi olmayan saf bir hesaplamadır.
• contains(), diğer kutu tamamen bu kutunun içinde olduğunda true döndürür. Sağ ve alt kenar karşılaştırmaları +1e-9 tolerans taşır; sol ve üst kenar karşılaştırmaları tamdır. Her kutu kendisini kapsar ve sıfır alanlı bir kutu kapsanabilir.
• overlaps(), kesin bir dikdörtgen kesişiminde true döndürür. Dört kenar karşılaştırmasının tümü kesindir, tolerans yoktur. İşlenenlerden herhangi biri sıfır alana sahipse sonuç false olur.
• Bu nedenle kapsama, örtüşme anlamına gelmez: başka bir kutunun içindeki yozlaşmış bir kutu kapsanır ama asla örtüşmez.
• Hiçbir yöntem giriş/çıkış, kalıcılık, ağ erişimi veya günlükleme yapmaz ve hiçbiri belge içeriği ya da kişisel veri tutmaz. Bu yüzey için operatöre ait bir kaynak yoktur.

Kullananlar

Enterprise modülleri, modül başına geometri tanımlamak yerine bu ilkeli paylaşır. Intelligence’ta, TableExtractor çıktısı bunu TableCell ve KeyValuePair değerlerinde taşır. Privacy’de, PiiEntity, RedactionFinding ve ZoneRedaction içeriği bununla konumlandırır ve RedactionEngine bu konumları kullanır. Bu yüzeylerin sözleşmeleri kendi başvuru sayfalarında belgelenmiştir.

Uç durumlar ve hata modları

• Aralık dışı bileşen. Dört değerden herhangi biri 0.0 altında veya 1.0 üzerinde ise yapım sırasında InvalidArgumentException fırlatır. INF ve -INF aynı koruma tarafından reddedilir.
• Kenar toplamı taşması. 1.0 + 1e-9 üzerindeki x + width veya y + height InvalidArgumentException fırlatır. 1e-9 toleransı içindeki bir toplam başarıyla oluşturulur.
• NAN girişi. Aralık koruması sıralı karşılaştırmalar kullanır ve NAN ile yapılan her sıralı karşılaştırma yanlış olduğundan, bir NAN bileşen reddedilmez. Böyle bir örnek NAN alan bildirir ve her iki yüklemden de false döndürür. Yapımdan önce önceki kayan nokta kaynaklarını temizleyin.
• Sıfır alanlı kutular. Sıfır genişlikli veya sıfır yükseklikli bir kutu, kendisi dâhil hiçbir şeyle asla örtüşmez. Yine de yozlaşmamış bir kutu tarafından kapsanabilir. Kesişim mantığında bu asimetriyi hesaba katın.
• Kenarı temas eden kutular. Yalnızca bir kenarı veya köşeyi paylaşan iki kutu örtüşmez; kesişim testi kesindir.
• Kapsama toleransı asimetrisi. Sol veya üst kenarı dış kutunun dışında herhangi bir miktarda kalan bir iç kutu kapsanamaz; yalnızca sağ ve alt kenarlar 1e-9 payını alır.
• FIPS modu. Bu modül hiçbir kriptografik işlem gerçekleştirmez; FIPS modu davranışını değiştirmez.

Uygunluk

Bu modül hiçbir normatif standart uygulamaz ve hiçbir uygunluk iddiasında bulunmaz. Doğrulanmış bir geometri ilkelidir. Onu kullanan özelliklere ilişkin PDF koordinat uzayı anlamları, o özelliklerin sayfalarında belgelenmiştir. NextPDF hiçbir sertifikaya sahip değildir ve hiçbir sertifika vermez; destek uygunluk değildir, uygunluk da sertifikasyon değildir. Bu yüzeye hiçbir ihracat denetimi kısıtlaması uygulanmaz ve bu başvuru bir hukuki görüş değildir.

Geliştirme notları

• Sınıf nextpdf/enterprise 2.2.0’dan beri kullanılabilir; genel yüzeyi 3.1.0’da değişmemiştir.
• Yapımdan önce mutlak sayfa uzayı koordinatlarını sayfaya göreli kesirlere dönüştürün. Sınıf, anlamı değil aralığı doğrular; makul ama yanlış bir bölgeyi tespit edemez.
• Örnekler düz değer nesneleridir ve oluşturulması ucuzdur. Onları havuzlamayın veya önbelleğe almayın.
• Aynı koordinatlara sahip iki örnek, gevşek eşitlik (==) altında eşit karşılaştırılır; kesin özdeşlik (===) onları ayırt eder. Testlerde koordinat karşılaştırmasını tercih edin.
• Boole yüklemlerinin ötesindeki geometri için kenarları genel özelliklerden türetin: sağ kenar x + width, alt kenar y + height.
• Tolerans sınırlarını test ederken, kenar toplamı koruması ile kapsama sağ/alt karşılaştırmalarında 1e-9 değerinin her iki tarafını da yoklayın.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilen davranışı ve desteklenen genel API yüzeyini belgeler. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Common yetenek sayfası
• Intelligence — Derinlemesine başvuru
• Privacy — Derinlemesine başvuru
• Validation — Derinlemesine başvuru
• Evidence — Derinlemesine başvuru