Common — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die ausführliche Referenz für den Namensraum NextPDF\Enterprise\Common. Der Namensraum liefert genau ein öffentliches Symbol: das Wertobjekt BoundingBox. Es ist ein unveränderliches, normalisiertes Rechteck für auflösungsunabhängige räumliche Positionierung auf einer Seite. Die Enterprise-Oberflächen Intelligence und Privacy nutzen es für die Geometrie von Tabellenzellen, für Entitätspositionen und für Schwärzungszonen. Das Modul führt keine I/O aus, hält keine Dokumentinhalte und berührt keine Kryptografie. Für Anleitungen zum Arbeitsablauf lesen Sie zunächst die Common-Funktionsseite.

Verfügbarkeit & Lizenzierung

Diese Funktion ist Bestandteil von NextPDF Enterprise (nextpdf/enterprise) und wird mit einem Lizenz-Envelope der Enterprise-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und eine Lizenz erwerben.

Das Primitiv selbst führt keine Lizenzgatterung durch; die Gatterung erfolgt auf den Enterprise-Oberflächen, die es nutzen. Es gibt kein Äquivalent dieser Klasse auf der Core- oder Pro-Stufe. Sie wird ausschließlich im Paket nextpdf/enterprise ausgeliefert und dupliziert oder ersetzt keine Core-Geometrietypen.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
BoundingBox::__construct	float $x, float $y, float $width, float $height	Validiert jeden Wert gegen [0.0, 1.0] und validiert anschließend beide Kantensummen	BoundingBox	InvalidArgumentException, wenn ein Wert außerhalb des Bereichs liegt oder eine Kantensumme 1.0 + 1e-9 überschreitet	Alle vier Werte werden zu public readonly-Eigenschaften
BoundingBox::area	keine	Multipliziert width mit height	float	Nichts deklariert	Gibt 0.0 für entartete Boxen zurück
BoundingBox::contains	self $other	Prüft, ob $other vollständig innerhalb dieser Box liegt	bool	Nichts deklariert	Rechte und untere Kante tolerieren +1e-9; linke und obere Kante werden exakt verglichen
BoundingBox::overlaps	self $other	Prüft auf eine strikte Rechteck-Überschneidung	bool	Nichts deklariert	Ein Operand mit null Fläche auf einer der beiden Seiten liefert false

Einstiegspunkt-Signatur

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
}

Verhaltensvertrag

Koordinatenmodell

• Alle vier Werte sind Bruchteile der Seitenabmessungen, normalisiert auf den Bereich [0.0, 1.0].
• x bezeichnet die linke Kante und y bezeichnet die obere Kante der Box. x + width und y + height begrenzen die rechte und die untere Kante.
• Die Normalisierung macht jede Operation auflösungsunabhängig. Dieselbe Box adressiert bei jeder Rendergröße oder DPI dieselbe Seitenregion.

Konstruktion

• Der Konstruktor ist der einzige Validierungspunkt. Eine Koordinate außerhalb von [0.0, 1.0] löst InvalidArgumentException aus; die Meldung nennt die betroffene Komponente und den empfangenen Wert.
• Eine Kantensumme über 1.0 + 1e-9 löst InvalidArgumentException aus; die Meldung nennt beide Operanden und ihre Summe. Die Toleranz von 1e-9 fängt Fließkomma-Rundungen aus der vorgelagerten Normalisierungsarithmetik ab.
• Eine konstruierte Instanz ist unveränderlich. Die Klasse ist final readonly, sodass Schreibzugriffe auf Eigenschaften mit einem PHP-Error scheitern und die Klasse nicht erweitert werden kann.

Prädikate

• area() gibt width * height zurück. Es ist eine reine Berechnung ohne Nebenwirkungen.
• contains() gibt true zurück, wenn die andere Box vollständig innerhalb dieser Box liegt. Die Vergleiche der rechten und unteren Kante tragen eine Toleranz von +1e-9; die Vergleiche der linken und oberen Kante sind exakt. Jede Box enthält sich selbst, und eine Box mit null Fläche kann enthalten sein.
• overlaps() gibt true bei einer strikten Rechteck-Überschneidung zurück. Alle vier Kantenvergleiche sind strikt, ohne Toleranz. Wenn einer der Operanden null Fläche hat, ist das Ergebnis false.
• Enthaltensein impliziert daher keine Überlappung: Eine entartete Box innerhalb einer anderen Box ist enthalten, überlappt jedoch nie.
• Keine Methode führt I/O, Persistierung, Netzwerkzugriff oder Protokollierung aus, und keine hält Dokumentinhalte oder personenbezogene Daten. Für diese Oberfläche gibt es keine betreiberseitig verwaltete Ressource.

Konsumenten

Enterprise-Module teilen sich dieses Primitiv, statt eine modulspezifische Geometrie zu definieren. In Intelligence trägt die Ausgabe von TableExtractor es auf den Werten TableCell und KeyValuePair. In Privacy verorten PiiEntity, RedactionFinding und ZoneRedaction Inhalte damit, und RedactionEngine nutzt diese Positionen. Die Verträge dieser Oberflächen sind auf ihren eigenen Referenzseiten dokumentiert.

Grenzfälle & Fehlermodi

• Komponente außerhalb des Bereichs. Jeder der vier Werte unter 0.0 oder über 1.0 löst bei der Konstruktion InvalidArgumentException aus. INF und -INF werden von demselben Schutzmechanismus abgewiesen.
• Kantensummen-Überlauf. x + width oder y + height über 1.0 + 1e-9 löst InvalidArgumentException aus. Eine Summe innerhalb der Toleranz von 1e-9 wird erfolgreich konstruiert.
• NAN-Eingabe. Der Bereichs-Schutzmechanismus verwendet geordnete Vergleiche, und jeder geordnete Vergleich mit NAN ist falsch, sodass eine NAN-Komponente nicht abgewiesen wird. Eine solche Instanz meldet eine NAN-Fläche und liefert bei beiden Prädikaten false. Bereinigen Sie vorgelagerte Fließkommaquellen vor der Konstruktion.
• Boxen mit null Fläche. Eine Box mit null Breite oder null Höhe überlappt nie etwas, auch nicht sich selbst. Sie kann dennoch von einer nicht entarteten Box enthalten sein. Berücksichtigen Sie diese Asymmetrie in der Überschneidungslogik.
• Kantenberührende Boxen. Zwei Boxen, die nur eine Kante oder eine Ecke teilen, überlappen nicht; der Überschneidungstest ist strikt.
• Toleranz-Asymmetrie beim Enthaltensein. Eine innere Box, deren linke oder obere Kante um irgendeinen Betrag außerhalb der äußeren Box liegt, scheitert am Enthaltensein; nur die rechte und die untere Kante erhalten die Toleranz von 1e-9.
• FIPS-Modus. Dieses Modul führt keine kryptografischen Operationen aus; der FIPS-Modus ändert sein Verhalten nicht.

Konformität

Dieses Modul implementiert keinen normativen Standard und erhebt keinen Konformitätsanspruch. Es ist ein validiertes Geometrie-Primitiv. Die PDF-Koordinatenraum-Semantik für die Funktionen, die es nutzen, ist auf den Seiten dieser Funktionen dokumentiert. NextPDF hält keine Zertifizierung und gewährt keine; Support ist keine Konformität, und Konformität ist keine Zertifizierung. Auf diese Oberfläche findet keine Exportkontrollbeschränkung Anwendung, und diese Referenz ist keine Rechtsauskunft.

Entwicklungshinweise

• Die Klasse ist seit nextpdf/enterprise 2.2.0 verfügbar; ihre öffentliche Oberfläche ist in 3.1.0 unverändert.
• Konvertieren Sie absolute seitenraumbezogene Koordinaten vor der Konstruktion in seitenrelative Bruchteile. Die Klasse validiert den Bereich, nicht die Semantik; sie kann eine plausible, aber falsche Region nicht erkennen.
• Instanzen sind einfache Wertobjekte und günstig zu konstruieren. Poolen oder cachen Sie sie nicht.
• Zwei Instanzen mit identischen Koordinaten sind unter lockerer Gleichheit (==) gleich; strikte Identität (===) unterscheidet sie. Bevorzugen Sie in Tests den Koordinatenvergleich.
• Für Geometrie jenseits der booleschen Prädikate leiten Sie die Kanten aus den öffentlichen Eigenschaften ab: rechte Kante x + width, untere Kante y + height.
• Beim Testen von Toleranzgrenzen prüfen Sie beide Seiten von 1e-9 am Kantensummen-Schutzmechanismus sowie an den Vergleichen der rechten/unteren Kante beim Enthaltensein.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich das von außen beobachtbare Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namensraumpfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.

Siehe auch

• Common-Funktionsseite
• Intelligence — Ausführliche Referenz
• Privacy — Ausführliche Referenz
• Validation — Ausführliche Referenz
• Evidence — Ausführliche Referenz