Enterprise edizione

Common — Riferimento approfondito

In breve

Questa pagina è il riferimento approfondito per il namespace NextPDF\Enterprise\Common. Il namespace espone un unico simbolo pubblico: il value object BoundingBox. È un rettangolo immutabile e normalizzato per il posizionamento spaziale indipendente dalla risoluzione su una pagina. Le superfici Enterprise Intelligence e Privacy lo utilizzano per la geometria delle celle di tabella, la posizione delle entità e le zone di redazione. Il modulo non esegue alcun I/O, non detiene alcun contenuto del documento e non fa uso di crittografia. Per indicazioni sul flusso di lavoro, leggere prima la pagina della funzionalità Common.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di tier Enterprise. Un deployment privo di tale abilitazione non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

La primitiva stessa non esegue alcun gating di licenza; il gating avviene sulle superfici Enterprise che la utilizzano. Non esiste alcun equivalente di tier Core o Pro di questa classe. È inclusa esclusivamente nel pacchetto nextpdf/enterprise e non duplica né sostituisce i tipi geometrici di Core.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`BoundingBox::__construct`	`float $x`, `float $y`, `float $width`, `float $height`	Convalida ciascun valore rispetto a `[0.0, 1.0]`, poi convalida entrambe le somme dei bordi	`BoundingBox`	`InvalidArgumentException` quando un valore è fuori intervallo o una somma dei bordi supera `1.0 + 1e-9`	Tutti e quattro i valori diventano proprietà `public readonly`
`BoundingBox::area`	nessuno	Moltiplica `width` per `height`	`float`	Nulla di dichiarato	Restituisce `0.0` per i box degeneri
`BoundingBox::contains`	`self $other`	Verifica se `$other` si trova interamente all’interno di questo box	`bool`	Nulla di dichiarato	I bordi destro e inferiore tollerano `+1e-9`; i bordi sinistro e superiore vengono confrontati in modo esatto
`BoundingBox::overlaps`	`self $other`	Verifica una stretta intersezione tra rettangoli	`bool`	Nulla di dichiarato	Un operando ad area nulla su uno dei due lati restituisce `false`

Firma del punto d’ingresso

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
}

Contratto di comportamento

Modello di coordinate

Tutti e quattro i valori sono frazioni delle dimensioni della pagina, normalizzate all’intervallo [0.0, 1.0].
x individua il bordo sinistro e y individua il bordo superiore del box. x + width e y + height delimitano i bordi destro e inferiore.
La normalizzazione rende ogni operazione indipendente dalla risoluzione. Lo stesso box indirizza la stessa regione della pagina a qualsiasi dimensione di rendering o DPI.

Costruzione

Il costruttore è l’unico punto di convalida. Una coordinata al di fuori di [0.0, 1.0] solleva InvalidArgumentException; il messaggio indica il componente errato e il valore ricevuto.
Una somma dei bordi superiore a 1.0 + 1e-9 solleva InvalidArgumentException; il messaggio riporta entrambi gli operandi e la loro somma. La tolleranza 1e-9 assorbe l’arrotondamento in virgola mobile derivante dall’aritmetica di normalizzazione a monte.
Un’istanza costruita è immutabile. La classe è final readonly, quindi le scritture sulle proprietà falliscono con un Error di PHP e la classe non può essere estesa.

Predicati

area() restituisce width * height. È un calcolo puro senza effetti collaterali.
contains() restituisce true quando l’altro box si trova interamente all’interno di questo box. I confronti sui bordi destro e inferiore applicano una tolleranza +1e-9; i confronti sui bordi sinistro e superiore sono esatti. Ogni box contiene se stesso e un box ad area nulla può essere contenuto.
overlaps() restituisce true in caso di stretta intersezione tra rettangoli. Tutti e quattro i confronti sui bordi sono stretti, senza tolleranza. Se uno dei due operandi ha area nulla, il risultato è false.
Il contenimento non implica quindi la sovrapposizione: un box degenere all’interno di un altro box è contenuto ma non si sovrappone mai.
Nessun metodo esegue I/O, persistenza, accesso di rete o logging, e nessuno detiene contenuto del documento o dati personali. Non esiste alcuna risorsa di competenza dell’operatore per questa superficie.

Consumatori

I moduli Enterprise condividono questa primitiva anziché definire una geometria per singolo modulo. In Intelligence, l’output di TableExtractor la trasporta sui valori TableCell e KeyValuePair. In Privacy, PiiEntity, RedactionFinding e ZoneRedaction individuano il contenuto tramite essa, e RedactionEngine utilizza tali posizioni. I contratti di tali superfici sono documentati nelle rispettive pagine di riferimento.

Casi limite e modalità di errore

Componente fuori intervallo. Uno qualsiasi dei quattro valori inferiore a 0.0 o superiore a 1.0 solleva InvalidArgumentException in fase di costruzione. INF e -INF vengono rifiutati dalla stessa guardia.
Overflow della somma dei bordi. x + width o y + height superiore a 1.0 + 1e-9 solleva InvalidArgumentException. Una somma entro la tolleranza 1e-9 viene costruita correttamente.
Input NAN. La guardia di intervallo usa confronti ordinati, e ogni confronto ordinato con NAN è falso, quindi un componente NAN non viene rifiutato. Un’istanza di questo tipo riporta un’area NAN e restituisce false da entrambi i predicati. Sanificare le sorgenti float a monte prima della costruzione.
Box ad area nulla. Un box con larghezza o altezza nulla non si sovrappone mai a nulla, incluso se stesso. Può comunque essere contenuto da un box non degenere. Tenere conto di questa asimmetria nella logica di intersezione.
Box a contatto sui bordi. Due box che condividono solo un bordo o un angolo non si sovrappongono; il test di intersezione è stretto.
Asimmetria della tolleranza di contenimento. Un box interno il cui bordo sinistro o superiore si trova al di fuori del box esterno di una qualsiasi entità non supera il contenimento; solo i bordi destro e inferiore ricevono la tolleranza 1e-9.
Modalità FIPS. Questo modulo non esegue alcuna operazione crittografica; la modalità FIPS non ne altera il comportamento.

Conformità

Questo modulo non implementa alcuno standard normativo e non avanza alcuna rivendicazione di conformità. È una primitiva geometrica convalidata. La semantica dello spazio di coordinate PDF per le funzionalità che la utilizzano è documentata nelle pagine di tali funzionalità. NextPDF non detiene alcuna certificazione e non ne concede alcuna; il supporto non è conformità e la conformità non è certificazione. Nessuna restrizione per il controllo delle esportazioni si applica a questa superficie, e questo riferimento non è un parere legale.

Note di sviluppo

La classe è disponibile a partire da nextpdf/enterprise 2.2.0; la sua superficie pubblica è invariata in 3.1.0.
Convertire le coordinate assolute nello spazio della pagina in frazioni relative alla pagina prima della costruzione. La classe convalida l’intervallo, non la semantica; non può rilevare una regione plausibile ma errata.
Le istanze sono semplici value object e sono poco costose da costruire. Non raggrupparle in pool né memorizzarle in cache.
Due istanze con coordinate identiche risultano uguali con l’uguaglianza debole (==); l’identità stretta (===) le distingue. Preferire il confronto delle coordinate nei test.
Per una geometria oltre i predicati booleani, derivare i bordi dalle proprietà pubbliche: bordo destro x + width, bordo inferiore y + height.
Quando si testano i limiti di tolleranza, sondare entrambi i lati di 1e-9 sulla guardia della somma dei bordi e sui confronti destro/inferiore del contenimento.

Confine di pubblicazione

Questa pagina documenta esclusivamente il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi di supporto, le tabelle dei meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.