Enterprise редакция

Common — глубокий справочник

Кратко

Эта страница — глубокий справочник по пространству имён NextPDF\Enterprise\Common. Пространство имён предоставляет один публичный символ: объект-значение BoundingBox. Это неизменяемый нормализованный прямоугольник для независимого от разрешения пространственного позиционирования на странице. Поверхности Enterprise Intelligence и Privacy используют его для геометрии ячеек таблиц, расположения сущностей и зон редактирования. Модуль не выполняет ввода-вывода, не хранит содержимого документа и не затрагивает криптографию. Для рекомендаций по рабочим процессам сначала прочитайте страницу возможности Common.

Доступность и лицензирование

Эта возможность поставляется в составе NextPDF Enterprise (nextpdf/enterprise) и активируется лицензионным конвертом уровня Enterprise. Развёртывание без этого права не загружает классы возможности. Сравнить редакции и получить лицензию.

Сам примитив не выполняет лицензионного гейтинга; гейтинг происходит на поверхностях Enterprise, которые его используют. Эквивалента этого класса уровня Core или Pro не существует. Он поставляется только в пакете nextpdf/enterprise и не дублирует и не заменяет геометрические типы Core.

Публичная поверхность API

Символ	Параметры	Поведение по умолчанию	Возвращает	Возбуждает или завершается с	Примечания
`BoundingBox::__construct`	`float $x`, `float $y`, `float $width`, `float $height`	Проверяет каждое значение по `[0.0, 1.0]`, затем проверяет обе суммы краёв	`BoundingBox`	`InvalidArgumentException`, когда значение вне диапазона или сумма краёв превышает `1.0 + 1e-9`	Все четыре значения становятся свойствами `public readonly`
`BoundingBox::area`	нет	Умножает `width` на `height`	`float`	Ничего не объявлено	Возвращает `0.0` для вырожденных рамок
`BoundingBox::contains`	`self $other`	Проверяет, полностью ли `$other` лежит внутри этой рамки	`bool`	Ничего не объявлено	Правый и нижний края допускают `+1e-9`; левый и верхний сравниваются точно
`BoundingBox::overlaps`	`self $other`	Проверяет строгое пересечение прямоугольников	`bool`	Ничего не объявлено	Операнд нулевой площади с любой стороны даёт `false`

Сигнатура точки входа

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
}

Контракт поведения

Координатная модель

Все четыре значения — доли размеров страницы, нормализованные к диапазону [0.0, 1.0].
x задаёт левый край, а y — верхний край рамки. x + width и y + height ограничивают правый и нижний края.
Нормализация делает каждую операцию независимой от разрешения. Одна и та же рамка адресует один и тот же участок страницы при любом размере отрисовки или DPI.

Построение

Конструктор — единственная точка проверки. Координата вне [0.0, 1.0] возбуждает InvalidArgumentException; сообщение называет нарушающий компонент и полученное значение.
Сумма краёв выше 1.0 + 1e-9 возбуждает InvalidArgumentException; сообщение сообщает оба операнда и их сумму. Допуск 1e-9 поглощает округление с плавающей точкой от вышестоящей арифметики нормализации.
Построенный экземпляр неизменяем. Класс final readonly, поэтому запись в свойства завершается PHP-ошибкой Error, а класс нельзя расширить.

Предикаты

area() возвращает width * height. Это чистое вычисление без побочных эффектов.
contains() возвращает true, когда другая рамка полностью лежит внутри этой. Сравнения правого и нижнего краёв несут допуск +1e-9; сравнения левого и верхнего краёв точны. Каждая рамка содержит саму себя, и рамка нулевой площади может быть содержащейся.
overlaps() возвращает true при строгом пересечении прямоугольников. Все четыре сравнения краёв строгие, без допуска. Если у любого из операндов нулевая площадь, результат — false.
Поэтому вложенность не подразумевает пересечения: вырожденная рамка внутри другой рамки содержится, но никогда не пересекается.
Ни один метод не выполняет ввода-вывода, хранения, сетевого доступа или логирования, и ни один не содержит содержимого документа или персональных данных. Для этой поверхности нет ресурсов, принадлежащих оператору.

Потребители

Модули Enterprise используют этот примитив совместно вместо определения геометрии в каждом модуле. В Intelligence вывод TableExtractor несёт его в значениях TableCell и KeyValuePair. В Privacy PiiEntity, RedactionFinding и ZoneRedaction локализуют содержимое с его помощью, а RedactionEngine потребляет эти расположения. Контракты этих поверхностей задокументированы на их собственных справочных страницах.

Граничные случаи и режимы отказа

Компонент вне диапазона. Любое из четырёх значений ниже 0.0 или выше 1.0 возбуждает InvalidArgumentException при построении. INF и -INF отклоняются той же защитой.
Переполнение суммы краёв. x + width или y + height выше 1.0 + 1e-9 возбуждает InvalidArgumentException. Сумма в пределах допуска 1e-9 строится успешно.
Ввод NAN. Защита диапазона использует упорядоченные сравнения, а каждое упорядоченное сравнение с NAN ложно, поэтому компонент NAN не отклоняется. Такой экземпляр сообщает площадь NAN и возвращает false из обоих предикатов. Очищайте вышестоящие источники чисел с плавающей точкой перед построением.
Рамки нулевой площади. Рамка с нулевой шириной или нулевой высотой никогда ни с чем не пересекается, включая саму себя. Она всё же может содержаться в невырожденной рамке. Учитывайте эту асимметрию в логике пересечения.
Рамки, касающиеся краями. Две рамки, разделяющие только край или угол, не пересекаются; проверка пересечения строгая.
Асимметрия допуска вложенности. Внутренняя рамка, у которой левый или верхний край выходит за внешнюю рамку на любую величину, не проходит проверку вложенности; только правый и нижний края получают допуск 1e-9.
Режим FIPS. Этот модуль не выполняет криптографических операций; режим FIPS не изменяет его поведения.

Соответствие

Этот модуль не реализует никакого нормативного стандарта и не делает заявлений о соответствии. Это проверенный геометрический примитив. Семантика координатного пространства PDF для функций, которые его используют, задокументирована на страницах этих функций. NextPDF не имеет сертификации и не предоставляет её; поддержка — это не соответствие, а соответствие — это не сертификация. К этой поверхности не применяются ограничения экспортного контроля, и этот справочник не является юридическим заключением.

Заметки по разработке

Класс доступен начиная с nextpdf/enterprise 2.2.0; его публичная поверхность не изменилась в 3.1.0.
Преобразуйте абсолютные координаты пространства страницы в доли относительно страницы перед построением. Класс проверяет диапазон, а не семантику; он не может обнаружить правдоподобный, но неверный участок.
Экземпляры — обычные объекты-значения, их дёшево создавать. Не пулируйте и не кэшируйте их.
Два экземпляра с идентичными координатами равны при нестрогом сравнении (==); строгое тождество (===) их различает. В тестах предпочитайте сравнение координат.
Для геометрии за пределами булевых предикатов выводите края из публичных свойств: правый край x + width, нижний край y + height.
При тестировании границ допуска проверяйте обе стороны 1e-9 на защите суммы краёв и на сравнениях правого/нижнего краёв при вложенности.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов руководств по эксплуатации и префиксы тикетов вне области рассмотрения.