Enterprise edición

Common — Referencia detallada

De un vistazo

Esta página es la referencia detallada del espacio de nombres NextPDF\Enterprise\Common. El espacio de nombres expone un único símbolo público: el objeto de valor BoundingBox. Es un rectángulo inmutable y normalizado para el posicionamiento espacial independiente de la resolución en una página. Las superficies de Enterprise Intelligence y Privacy lo consumen para la geometría de celdas de tabla, las ubicaciones de entidades y las zonas de redacción. El módulo no realiza E/S, no conserva contenido de documentos y no toca criptografía. Para orientación sobre flujos de trabajo, lea primero la página de capacidad de Common.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Una implementación sin ese derecho no carga las clases de la capacidad. Compare ediciones y obtenga una licencia.

La primitiva en sí no realiza ningún control de licencia; el control ocurre en las superficies de Enterprise que la consumen. No existe un equivalente de esta clase en el nivel Core ni Pro. Se distribuye únicamente en el paquete nextpdf/enterprise y no duplica ni reemplaza los tipos de geometría de Core.

Superficie de la API pública

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`BoundingBox::__construct`	`float $x`, `float $y`, `float $width`, `float $height`	Valida cada valor frente a `[0.0, 1.0]`, luego valida ambas sumas de borde	`BoundingBox`	`InvalidArgumentException` cuando un valor está fuera de rango o una suma de borde supera `1.0 + 1e-9`	Los cuatro valores se convierten en propiedades `public readonly`
`BoundingBox::area`	ninguno	Multiplica `width` por `height`	`float`	Nada declarado	Devuelve `0.0` para cajas degeneradas
`BoundingBox::contains`	`self $other`	Comprueba si `$other` queda completamente dentro de esta caja	`bool`	Nada declarado	Los bordes derecho e inferior toleran `+1e-9`; los bordes izquierdo y superior comparan de forma exacta
`BoundingBox::overlaps`	`self $other`	Comprueba una intersección estricta de rectángulos	`bool`	Nada declarado	Un operando de área cero en cualquiera de los lados devuelve `false`

Firma del punto de entrada

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
}

Contrato de comportamiento

Modelo de coordenadas

Los cuatro valores son fracciones de las dimensiones de la página, normalizadas al rango [0.0, 1.0].
x localiza el borde izquierdo e y localiza el borde superior de la caja. x + width e y + height delimitan los bordes derecho e inferior.
La normalización hace que cada operación sea independiente de la resolución. La misma caja direcciona la misma región de la página a cualquier tamaño de renderizado o DPI.

Construcción

El constructor es el único punto de validación. Una coordenada fuera de [0.0, 1.0] lanza InvalidArgumentException; el mensaje nombra el componente infractor y el valor recibido.
Una suma de borde por encima de 1.0 + 1e-9 lanza InvalidArgumentException; el mensaje informa de ambos operandos y de su suma. La tolerancia de 1e-9 absorbe el redondeo de coma flotante de la aritmética de normalización previa.
Una instancia construida es inmutable. La clase es final readonly, por lo que las escrituras de propiedades fallan con un Error de PHP y la clase no puede extenderse.

Predicados

area() devuelve width * height. Es un cálculo puro sin efectos secundarios.
contains() devuelve true cuando la otra caja queda completamente dentro de esta caja. Las comparaciones de los bordes derecho e inferior llevan una tolerancia de +1e-9; las comparaciones de los bordes izquierdo y superior son exactas. Toda caja se contiene a sí misma, y una caja de área cero puede estar contenida.
overlaps() devuelve true ante una intersección estricta de rectángulos. Las cuatro comparaciones de borde son estrictas, sin tolerancia. Si cualquiera de los operandos tiene área cero, el resultado es false.
Por lo tanto, la contención no implica solapamiento: una caja degenerada dentro de otra caja está contenida, pero nunca se solapa.
Ningún método realiza E/S, persistencia, acceso a red o registro, y ninguno conserva contenido de documentos ni datos personales. No existe ningún recurso propiedad del operador para esta superficie.

Consumidores

Los módulos de Enterprise comparten esta primitiva en lugar de definir geometría por módulo. En Intelligence, la salida de TableExtractor la lleva en los valores TableCell y KeyValuePair. En Privacy, PiiEntity, RedactionFinding y ZoneRedaction localizan contenido con ella, y RedactionEngine consume esas ubicaciones. Los contratos de esas superficies se documentan en sus propias páginas de referencia.

Casos límite y modos de fallo

Componente fuera de rango. Cualquiera de los cuatro valores por debajo de 0.0 o por encima de 1.0 lanza InvalidArgumentException en la construcción. INF y -INF son rechazados por la misma guarda.
Desbordamiento de suma de borde. x + width o y + height por encima de 1.0 + 1e-9 lanza InvalidArgumentException. Una suma dentro de la tolerancia de 1e-9 se construye correctamente.
Entrada NAN. La guarda de rango usa comparaciones ordenadas, y toda comparación ordenada con NAN es falsa, por lo que un componente NAN no se rechaza. Tal instancia informa de un área NAN y devuelve false en ambos predicados. Sanee las fuentes de coma flotante previas antes de construir.
Cajas de área cero. Una caja con anchura cero o altura cero nunca se solapa con nada, ni siquiera consigo misma. Aun así, puede estar contenida por una caja no degenerada. Tenga en cuenta esta asimetría en la lógica de intersección.
Cajas que se tocan por el borde. Dos cajas que comparten solo un borde o una esquina no se solapan; la prueba de intersección es estricta.
Asimetría de la tolerancia de contención. Una caja interior cuyo borde izquierdo o superior queda fuera de la caja exterior por cualquier cantidad falla la contención; solo los bordes derecho e inferior reciben el margen de 1e-9.
Modo FIPS. Este módulo no realiza operaciones criptográficas; el modo FIPS no altera su comportamiento.

Conformidad

Este módulo no implementa ninguna norma normativa y no formula ninguna declaración de conformidad. Es una primitiva de geometría validada. La semántica del espacio de coordenadas PDF para las funciones que la consumen se documenta en las páginas de esas funciones. NextPDF no posee ninguna certificación y no otorga ninguna; el soporte no es conformidad, y la conformidad no es certificación. Ninguna restricción de control de exportación se aplica a esta superficie, y esta referencia no es una opinión jurídica.

Notas de desarrollo

La clase está disponible desde nextpdf/enterprise 2.2.0; su superficie pública no cambia en 3.1.0.
Convierta las coordenadas absolutas del espacio de la página a fracciones relativas a la página antes de construir. La clase valida el rango, no la semántica; no puede detectar una región plausible pero errónea.
Las instancias son objetos de valor simples y baratos de construir. No las agrupe ni las almacene en caché.
Dos instancias con coordenadas idénticas comparan como iguales bajo igualdad laxa (==); la identidad estricta (===) las distingue. Prefiera la comparación de coordenadas en las pruebas.
Para geometría más allá de los predicados booleanos, derive los bordes de las propiedades públicas: borde derecho x + width, borde inferior y + height.
Al probar los límites de tolerancia, sondee ambos lados de 1e-9 en la guarda de suma de borde y en las comparaciones de contención de los bordes derecho/inferior.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de la API pública admitida. Las rutas internas de espacios de nombres, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbooks y los prefijos de tickets quedan fuera del alcance.