Common — Deep Reference

At a glance

This page is the deep reference for the NextPDF\Enterprise\Common namespace. The namespace ships one public symbol: the BoundingBox value object. It is an immutable, normalized rectangle for resolution-independent spatial positioning on a page. Enterprise Intelligence and Privacy surfaces consume it for table-cell geometry, entity locations, and redaction zones. The module performs no I/O, holds no document content, and touches no cryptography. For workflow guidance, read the Common capability page first.

Availability & licensing

This capability ships in NextPDF Enterprise (nextpdf/enterprise) and activates with an Enterprise-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

The primitive itself performs no license gating; gating happens on the Enterprise surfaces that consume it. There is no Core-tier or Pro-tier equivalent of this class. It ships in the nextpdf/enterprise package only and does not duplicate or replace Core geometry types.

Public API surface

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
BoundingBox::__construct	float $x, float $y, float $width, float $height	Validates each value against [0.0, 1.0], then validates both edge sums	BoundingBox	InvalidArgumentException when a value is out of range or an edge sum exceeds 1.0 + 1e-9	All four values become public readonly properties
BoundingBox::area	none	Multiplies width by height	float	Nothing declared	Returns 0.0 for degenerate boxes
BoundingBox::contains	self $other	Tests whether $other lies fully inside this box	bool	Nothing declared	Right and bottom edges tolerate +1e-9; left and top edges compare exactly
BoundingBox::overlaps	self $other	Tests for a strict rectangle intersection	bool	Nothing declared	A zero-area operand on either side returns false

Entry-point signature

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
}

Behavior contract

Coordinate model

• All four values are fractions of the page dimensions, normalized to the [0.0, 1.0] range.
• x locates the left edge and y locates the top edge of the box. x + width and y + height bound the right and bottom edges.
• Normalization makes every operation resolution independent. The same box addresses the same page region at any render size or DPI.

Construction

• The constructor is the single validation point. A coordinate outside [0.0, 1.0] raises InvalidArgumentException; the message names the offending component and the received value.
• An edge sum above 1.0 + 1e-9 raises InvalidArgumentException; the message reports both operands and their sum. The 1e-9 tolerance absorbs floating-point rounding from upstream normalization arithmetic.
• A constructed instance is immutable. The class is final readonly, so property writes fail with a PHP Error and the class cannot be extended.

Predicates

• area() returns width * height. It is a pure computation with no side effects.
• contains() returns true when the other box lies fully inside this box. The right- and bottom-edge comparisons carry a +1e-9 tolerance; the left- and top-edge comparisons are exact. Every box contains itself, and a zero-area box can be contained.
• overlaps() returns true on a strict rectangle intersection. All four edge comparisons are strict, with no tolerance. If either operand has zero area, the result is false.
• Containment therefore does not imply overlap: a degenerate box inside another box is contained but never overlaps.
• No method performs I/O, persistence, network access, or logging, and none holds document content or personal data. There is no operator-owned resource for this surface.

Consumers

Enterprise modules share this primitive rather than defining per-module geometry. In Intelligence, TableExtractor output carries it on TableCell and KeyValuePair values. In Privacy, PiiEntity, RedactionFinding, and ZoneRedaction locate content with it, and RedactionEngine consumes those locations. The contracts of those surfaces are documented on their own reference pages.

Edge cases & failure modes

• Out-of-range component. Any of the four values below 0.0 or above 1.0 raises InvalidArgumentException at construction. INF and -INF are rejected by the same guard.
• Edge-sum overflow. x + width or y + height above 1.0 + 1e-9 raises InvalidArgumentException. A sum within the 1e-9 tolerance constructs successfully.
• NAN input. The range guard uses ordered comparisons, and every ordered comparison with NAN is false, so a NAN component is not rejected. Such an instance reports a NAN area and returns false from both predicates. Sanitize upstream float sources before construction.
• Zero-area boxes. A box with zero width or zero height never overlaps anything, including itself. It can still be contained by a non-degenerate box. Account for this asymmetry in intersection logic.
• Edge-touching boxes. Two boxes that share only an edge or a corner do not overlap; the intersection test is strict.
• Containment tolerance asymmetry. An inner box whose left or top edge lies outside the outer box by any amount fails containment; only the right and bottom edges receive the 1e-9 allowance.
• FIPS mode. This module performs no cryptographic operations; FIPS mode does not alter its behavior.

Conformance

This module implements no normative standard. It is a validated geometry primitive. PDF coordinate-space semantics for the features that consume it are documented on those features’ pages. No export-control restriction applies to this surface, and this reference is not a legal opinion.

Development notes

• The class is available since nextpdf/enterprise 2.2.0; its public surface is unchanged in 3.1.0.
• Convert absolute page-space coordinates to page-relative fractions before construction. The class validates range, not semantics; it cannot detect a plausible-but-wrong region.
• Instances are plain value objects and are cheap to construct. Do not pool or cache them.
• Two instances with identical coordinates compare equal under loose equality (==); strict identity (===) distinguishes them. Prefer coordinate comparison in tests.
• For geometry beyond the boolean predicates, derive edges from the public properties: right edge x + width, bottom edge y + height.
• When testing tolerance boundaries, probe both sides of 1e-9 on the edge-sum guard and on the containment right/bottom comparisons.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

See also

• Common capability page
• Intelligence — Deep Reference
• Privacy — Deep Reference
• Validation — Deep Reference
• Evidence — Deep Reference