Общее

Кратко

NextPDF Enterprise поставляет небольшой набор общих примитивов, переиспользуемых в модулях Enterprise. Первый из них — нормализованный ограничивающий прямоугольник для независимого от разрешения пространственного позиционирования. Это объекты-значения без поведения соответствия, конформности или криптографии.

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

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

Пакет Enterprise устанавливается рядом с пакетом Core; эти общие примитивы потребляются внутренне другими модулями Enterprise и разрешаются вместе с пакетом. У них нет эквивалента уровня Core или Pro.

Установка

composer require nextpdf/enterprise:^3

Концептуальный обзор

BoundingBox — это неизменяемый объект-значение, четыре координаты которого — x, y, ширина, высота — нормализованы к диапазону [0.0, 1.0] относительно размеров страницы. Поскольку координаты нормализованы, прямоугольник не зависит от разрешения и может переиспользоваться в модулях Enterprise, оперирующих геометрией страницы. Конструктор проверяет, что каждая координата находится в диапазоне и что x + width и y + height не превышают 1.0 (в пределах небольшого допуска с плавающей точкой), иначе вызывает ошибку аргумента.

Он предоставляет area(), contains(self $other) и overlaps(self $other). Прямоугольники с нулевой площадью (вырожденные точки или линии) по определению не могут пересекаться.

Что утверждает этот модуль

Этот модуль предоставляет проверенные геометрические примитивы. Он не делает заявления о соответствии или конформности и не выполняет ввода-вывода.

Граница уровня

Common — это вспомогательная поверхность только для Enterprise, которую потребляют другие модули Enterprise. Она не дублирует и не заменяет геометрию Core; она предоставляет небольшие проверенные примитивы, которые модули Enterprise разделяют.

Почему это работает именно так

Ключевое решение — нормализовать каждую координату к диапазону [0.0, 1.0] и проверить её в конструкторе. Нормализованные координаты делают прямоугольник независимым от разрешения, поэтому область, описанная однажды, остаётся корректной при любом размере страницы или масштабе отрисовки. Конструирование по принципу fail-closed означает, что некорректный или переполненный прямоугольник существовать не может: конструктор отклоняет его, а не обрезает и не угадывает. Поэтому потребляющие модули Enterprise никогда не перепроверяют полученную геометрию, ведь сконструированный прямоугольник уже заведомо валиден. Неизменяемость делает общий прямоугольник безопасным для передачи между модулями без защитных копий. Предыстория проектирования: API, который отказывается угадывать.

Программный интерфейс

Класс	Ответственность
BoundingBox	Неизменяемый нормализованный прямоугольник; area(), contains(), overlaps().

Пример кода — быстрый старт

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));

Пример кода — продакшн

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

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

Граничные случаи и подводные камни

• Конструирование с любой координатой вне [0.0, 1.0] или с x + width / y + height свыше 1.0 вызывает ошибку аргумента — проверяйте входные данные выше по потоку.
• Прямоугольники с нулевой площадью никогда не пересекаются; учитывайте это при вычислении пересечений.
• Координаты нормализованы, а не в пикселях; преобразуйте на границе отрисовки.

Производительность

Все операции — это арифметика с постоянным временем над четырьмя числами с плавающей точкой.

Примечания по безопасности

BoundingBox не выполняет ввода-вывода и не хранит содержимого документа. Конструктор отклоняет геометрию вне диапазона, не давая вырожденным значениям распространиться в потребляющие модули.

Резидентность данных и меры по защите PII

Этот модуль не хранит персональных данных и не выполняет сохранения или сетевого ввода-вывода. Соображения резидентности не применяются.

Безопасная телеметрия и очистка журналов

Координаты и площади прямоугольников — это неконфиденциальная геометрия, их безопасно логировать.

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

Этот модуль не реализует никакого нормативного стандарта и не делает заявления о конформности. Это геометрический примитив.

Поведение в режиме FIPS

Этот модуль не выполняет криптографических операций; режим FIPS не применяется.

Модель угроз

Единственный ввод — это четыре числа с плавающей точкой. Проверка диапазона и границ в конструкторе — это мера защиты: некорректную геометрию сконструировать нельзя.

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

• BoundingBox — это неизменяемый объект-значение, четыре координаты которого нормализованы к диапазону [0.0, 1.0] относительно размеров страницы, что делает его независимым от разрешения.
• Конструктор проверяет, что каждая координата в диапазоне и что x + width и y + height не превышают 1.0 (в пределах небольшого допуска с плавающей точкой), иначе вызывает ошибку аргумента.
• Он предоставляет area(), contains() и overlaps(); прямоугольники с нулевой площадью по определению никогда не пересекаются.
• Модуль не выполняет ввода-вывода, не хранит содержимого документа и не делает заявления о соответствии или конформности.

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

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

Резервный вариант Core

Резервный вариант Core — отсутствует; это вспомогательный примитив только для Enterprise. Он не дублирует и не заменяет геометрию Core и не имеет эквивалента уровня Core.

Резервный вариант Pro

Резервный вариант Pro — отсутствует; у этой возможности нет эквивалента уровня Pro. Общий примитив BoundingBox поставляется только в пакете nextpdf/enterprise.

Примечание о границе Enterprise

Проверенный геометрический примитив описан на уровне поведения. Это вспомогательная поверхность только для Enterprise, которую потребляют другие модули Enterprise; внутренних подмеханизмов сверх задокументированного контракта нет.

Граница развёртывания

Граница развёртывания — неприменима; этот модуль не выполняет сохранения, сетевого ввода-вывода и не хранит содержимого документа или персональных данных. Для этой поверхности нет ресурса, которым владеет оператор.

Граница юридического соответствия

К этой поверхности не применяется никакого ограничения экспортного контроля. Модуль не реализует никакого нормативного стандарта и не делает заявления о конформности, сертификации или регуляторного заявления. Эта документация не является юридическим заключением.

См. также

• Validation — потребляет общие примитивы.
• Evidence — потребляет общие примитивы.
• Common — подробный справочник — подробный справочник по общим примитивам.