Common

De un vistazo

NextPDF Enterprise distribuye un pequeño conjunto de primitivas compartidas reutilizadas en los módulos de Enterprise. La primera es un cuadro delimitador normalizado para el posicionamiento espacial independiente de la resolución. Son objetos de valor sin comportamiento de cumplimiento, de conformidad ni criptográfico.

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. Comparar ediciones y obtener una licencia.

El paquete Enterprise se instala junto al paquete Core; estas primitivas compartidas las consumen internamente los demás módulos de Enterprise y se resuelven con el paquete. No tienen equivalente en el nivel Core ni en el nivel Pro.

Instalación

composer require nextpdf/enterprise:^3

Descripción conceptual

BoundingBox es un objeto de valor inmutable cuyas cuatro coordenadas —x, y, ancho, alto— están normalizadas al rango [0.0, 1.0] en relación con las dimensiones de la página. Como las coordenadas están normalizadas, el cuadro es independiente de la resolución y puede reutilizarse en los módulos de Enterprise que razonan sobre la geometría de la página. El constructor valida que cada coordenada esté dentro del rango y que x + width e y + height no superen 1.0 (dentro de una pequeña tolerancia de coma flotante), generando un error de argumento en caso contrario.

Expone area(), contains(self $other) y overlaps(self $other). Los cuadros de área cero (puntos o líneas degenerados) no pueden solaparse por definición.

Qué afirma este módulo

Este módulo proporciona primitivas de geometría validadas. No hace ninguna declaración de cumplimiento ni de conformidad y no realiza E/S.

Frontera entre niveles

Common es una superficie de soporte exclusiva de Enterprise que consumen otros módulos de Enterprise. No duplica ni reemplaza la geometría de Core; proporciona las pequeñas primitivas validadas que comparten los módulos de Enterprise.

Por qué funciona así

La decisión determinante es normalizar cada coordenada al rango [0.0, 1.0] y validarla en el constructor. Las coordenadas normalizadas hacen que el cuadro sea independiente de la resolución, de modo que una región descrita una sola vez permanece correcta a cualquier tamaño de página o escala de representación. La construcción fail-closed significa que un cuadro no válido o desbordado no puede existir: el constructor lo rechaza en lugar de recortarlo o adivinar. Por eso los módulos de Enterprise consumidores nunca vuelven a comprobar la geometría que reciben, porque un cuadro construido ya se sabe válido. La inmutabilidad hace que un cuadro compartido sea seguro de pasar entre módulos sin copias defensivas. Trasfondo de diseño: Una API que se niega a adivinar.

Superficie de la API

Clase	Responsabilidad
BoundingBox	Cuadro normalizado inmutable; area(), contains(), overlaps().

Ejemplo de código — Inicio rápido

use NextPDF\Enterprise\Common\BoundingBox;

$box = new BoundingBox(0.1, 0.1, 0.5, 0.2);
$inside = $box->contains(new BoundingBox(0.2, 0.15, 0.1, 0.02));

Ejemplo de código — Producción

$region = new BoundingBox($x, $y, $w, $h); // throws on out-of-range input

if ($region->overlaps($redactionZone)) {
    $logger->info('common.overlap', ['area' => $region->area()]);
}

Casos límite y trampas

• Construir con cualquier coordenada fuera de [0.0, 1.0], o con x + width / y + height por encima de 1.0, genera un error de argumento — valide las entradas aguas arriba.
• Los cuadros de área cero nunca se solapan; téngalo en cuenta al calcular intersecciones.
• Las coordenadas están normalizadas, no en píxeles; conviértalas en el límite de representación.

Rendimiento

Todas las operaciones son aritmética de tiempo constante sobre cuatro flotantes.

Notas de seguridad

BoundingBox no realiza E/S y no contiene contenido del documento. El constructor rechaza la geometría fuera de rango, lo que impide que los valores degenerados se propaguen a los módulos consumidores.

Residencia de datos y mitigaciones de PII

Este módulo no contiene datos personales y no realiza persistencia ni E/S de red. Las consideraciones de residencia no se aplican.

Telemetría segura y depuración de registros

Las coordenadas y las áreas de los cuadros son geometría no sensible y son seguras de registrar.

Conformidad

Este módulo no implementa ningún estándar normativo y no hace ninguna declaración de conformidad. Es una primitiva de geometría.

Comportamiento en modo FIPS

Este módulo no realiza operaciones criptográficas; el modo FIPS no se aplica.

Modelo de amenazas

La única entrada son cuatro flotantes. La validación de rango y de límites del constructor es la mitigación: no se puede construir geometría no válida.

Contrato de comportamiento

• BoundingBox es un objeto de valor inmutable cuyas cuatro coordenadas están normalizadas al rango [0.0, 1.0] en relación con las dimensiones de la página, lo que lo hace independiente de la resolución.
• El constructor valida que cada coordenada esté dentro del rango y que x + width e y + height no superen 1.0 (dentro de una pequeña tolerancia de coma flotante), generando un error de argumento en caso contrario.
• Expone area(), contains() y overlaps(); los cuadros de área cero nunca se solapan por definición.
• El módulo no realiza E/S, no contiene contenido del documento y no hace ninguna declaración de cumplimiento ni de conformidad.

Frontera de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de la API compatible. Las rutas internas de espacio de nombres, las clases auxiliares, las tablas de mecanismos, los nombres de archivos de runbook y los prefijos de tickets quedan fuera de alcance.

Alternativa de Core

Alternativa de Core — ninguna; esta es una primitiva de soporte compartida exclusiva de Enterprise. No duplica ni reemplaza la geometría de Core y no tiene equivalente en el nivel Core.

Alternativa de Pro

Alternativa de Pro — ninguna; esta capacidad no tiene equivalente en el nivel Pro. La primitiva compartida BoundingBox se distribuye únicamente en el paquete nextpdf/enterprise.

Nota sobre el límite de Enterprise

La primitiva de geometría validada se describe a nivel de comportamiento. Es una superficie de soporte exclusiva de Enterprise que consumen otros módulos de Enterprise; no hay submecanismos internos más allá del contrato documentado.

Límite de despliegue

Límite de despliegue — ninguno aplicable; este módulo no realiza persistencia, ni E/S de red, y no contiene contenido del documento ni datos personales. No hay ningún recurso propiedad del operador para esta superficie.

Límite de cumplimiento legal

No se aplica ninguna restricción de control de exportación a esta superficie. El módulo no implementa ningún estándar normativo y no hace ninguna declaración de conformidad, certificación ni regulatoria. Esta documentación no es una opinión legal.

Consulte también

• Validation — consume primitivas compartidas.
• Evidence — consume primitivas compartidas.
• Common — Referencia detallada — referencia detallada para las primitivas compartidas.