Common

W skrócie

NextPDF Enterprise dostarcza niewielki zestaw współdzielonych prymitywów wykorzystywanych w modułach Enterprise. Pierwszym z nich jest znormalizowana ramka ograniczająca dla niezależnego od rozdzielczości pozycjonowania przestrzennego. Są to obiekty wartości bez żadnego zachowania w zakresie zgodności, conformance ani kryptografii.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

Pakiet Enterprise instaluje się obok pakietu Core; te współdzielone prymitywy są używane wewnętrznie przez pozostałe moduły Enterprise i rozwiązują się wraz z pakietem. Nie mają odpowiednika na poziomie Core ani Pro.

Instalacja

composer require nextpdf/enterprise:^3

Przegląd koncepcyjny

BoundingBox to niemutowalny obiekt wartości, którego cztery współrzędne — x, y, width, height — są znormalizowane do zakresu [0.0, 1.0] względem wymiarów strony. Ponieważ współrzędne są znormalizowane, ramka jest niezależna od rozdzielczości i może być wykorzystywana w modułach Enterprise, które operują na geometrii strony. Konstruktor sprawdza, czy każda współrzędna mieści się w zakresie oraz czy x + width i y + height nie przekraczają 1.0 (z niewielką tolerancją zmiennoprzecinkową), w przeciwnym razie zgłaszając błąd argumentu.

Udostępnia area(), contains(self $other) oraz overlaps(self $other). Ramki o zerowym polu (zdegenerowane punkty lub linie) z definicji nie mogą się nakładać.

Co stwierdza ten moduł

Ten moduł dostarcza zwalidowane prymitywy geometryczne. Nie formułuje żadnego twierdzenia o zgodności ani conformance i nie wykonuje żadnych operacji wejścia/wyjścia.

Granica poziomu

Common to powierzchnia pomocnicza dostępna wyłącznie w Enterprise, z której korzystają inne moduły Enterprise. Nie powiela ani nie zastępuje geometrii Core; dostarcza małe, zwalidowane prymitywy współdzielone przez moduły Enterprise.

Dlaczego działa to w ten sposób

Kluczową decyzją jest znormalizowanie każdej współrzędnej do zakresu [0.0, 1.0] i zwalidowanie jej w konstruktorze. Znormalizowane współrzędne czynią ramkę niezależną od rozdzielczości, więc raz opisany region pozostaje poprawny przy dowolnym rozmiarze strony lub skali renderowania. Konstrukcja fail-closed oznacza, że nieprawidłowa lub przekraczająca zakres ramka nie może istnieć: konstruktor ją odrzuca, zamiast przycinać lub zgadywać. Korzystające moduły Enterprise nigdy więc nie sprawdzają ponownie otrzymywanej geometrii, ponieważ skonstruowana ramka jest już znana jako poprawna. Niemutowalność sprawia, że współdzieloną ramkę można bezpiecznie przekazywać między modułami bez kopii obronnych. Kontekst projektowy: API, które odmawia zgadywania.

Powierzchnia API

Klasa	Odpowiedzialność
BoundingBox	Niemutowalna znormalizowana ramka; area(), contains(), overlaps().

Przykład kodu — szybki start

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

Przykład kodu — produkcja

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

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

Przypadki brzegowe i pułapki

• Konstrukcja z dowolną współrzędną poza zakresem [0.0, 1.0] lub z x + width / y + height powyżej 1.0 zgłasza błąd argumentu — waliduj dane wejściowe wcześniej w potoku.
• Ramki o zerowym polu nigdy się nie nakładają; uwzględnij to przy obliczaniu przecięć.
• Współrzędne są znormalizowane, a nie wyrażone w pikselach; przeliczaj je na granicy renderowania.

Wydajność

Wszystkie operacje to arytmetyka o stałym czasie na czterech liczbach zmiennoprzecinkowych.

Uwagi dotyczące bezpieczeństwa

BoundingBox nie wykonuje żadnych operacji wejścia/wyjścia i nie przechowuje treści dokumentu. Konstruktor odrzuca geometrię poza zakresem, zapobiegając propagacji zdegenerowanych wartości do modułów korzystających.

Rezydencja danych i środki ograniczające dla danych osobowych (PII)

Ten moduł nie przechowuje żadnych danych osobowych i nie wykonuje trwałego przechowywania ani operacji sieciowych. Rozważania dotyczące rezydencji nie mają zastosowania.

Bezpieczna telemetria i czyszczenie logów

Współrzędne i pola ramki to geometria niewrażliwa i można je bezpiecznie logować.

Zgodność ze standardami

Ten moduł nie implementuje żadnego standardu normatywnego i nie formułuje żadnego twierdzenia o conformance. Jest to prymityw geometryczny.

Zachowanie w trybie FIPS

Ten moduł nie wykonuje żadnych operacji kryptograficznych; tryb FIPS nie ma zastosowania.

Model zagrożeń

Jedynym wejściem są cztery liczby zmiennoprzecinkowe. Walidacja zakresu i granic w konstruktorze jest środkiem ograniczającym: nieprawidłowej geometrii nie da się skonstruować.

Kontrakt zachowania

• BoundingBox to niemutowalny obiekt wartości, którego cztery współrzędne są znormalizowane do zakresu [0.0, 1.0] względem wymiarów strony, co czyni go niezależnym od rozdzielczości.
• Konstruktor sprawdza, czy każda współrzędna mieści się w zakresie oraz czy x + width i y + height nie przekraczają 1.0 (z niewielką tolerancją zmiennoprzecinkową), w przeciwnym razie zgłaszając błąd argumentu.
• Udostępnia area(), contains() oraz overlaps(); ramki o zerowym polu z definicji nigdy się nie nakładają.
• Moduł nie wykonuje żadnych operacji wejścia/wyjścia, nie przechowuje treści dokumentu i nie formułuje żadnego twierdzenia o zgodności ani conformance.

Granica publikacji

Ta strona dokumentuje wyłącznie obserwowalne z zewnątrz zachowanie oraz wspieraną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Rozwiązanie awaryjne w Core

Rozwiązanie awaryjne w Core — brak; jest to współdzielony prymityw pomocniczy dostępny wyłącznie w Enterprise. Nie powiela ani nie zastępuje geometrii Core i nie ma odpowiednika na poziomie Core.

Rozwiązanie awaryjne w Pro

Rozwiązanie awaryjne w Pro — brak; ta możliwość nie ma odpowiednika na poziomie Pro. Współdzielony prymityw BoundingBox jest dostarczany wyłącznie w pakiecie nextpdf/enterprise.

Uwaga o granicy Enterprise

Zwalidowany prymityw geometryczny jest opisany na poziomie zachowania. Jest to powierzchnia pomocnicza dostępna wyłącznie w Enterprise, z której korzystają inne moduły Enterprise; poza udokumentowanym kontraktem nie istnieją żadne wewnętrzne podmechanizmy.

Granica wdrożenia

Granica wdrożenia — brak zastosowania; ten moduł nie wykonuje trwałego przechowywania ani operacji sieciowych i nie przechowuje treści dokumentu ani danych osobowych. Dla tej powierzchni nie istnieje żaden zasób będący w gestii operatora.

Granica zgodności prawnej

Do tej powierzchni nie ma zastosowania żadne ograniczenie kontroli eksportu. Moduł nie implementuje żadnego standardu normatywnego i nie formułuje żadnego twierdzenia o conformance, certyfikacji ani statusie regulacyjnym. Niniejsza dokumentacja nie stanowi opinii prawnej.

Zobacz także

• Validation — korzysta ze współdzielonych prymitywów.
• Evidence — korzysta ze współdzielonych prymitywów.
• Common — Deep Reference — pełna dokumentacja referencyjna współdzielonych prymitywów.