ValueObjects: prymitywy domenowe i jednostki

W skrócie

Moduł ValueObjects udostępnia niezmienne prymitywy geometryczne używane w całym silniku: PageSize, Dimension, Position, Margin oraz wyliczenie Unit. Każdy z nich jest klasą final readonly. Instancje można swobodnie współdzielić, a każda transformacja zwraca nową instancję.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Wszystkie cztery obiekty wartości są final readonly. Przechowują współrzędne typu float i nie udostępniają mutatorów; metody transformujące tworzą nową instancję z argumentami nazwanymi. Można je buforować, przekazywać między dokumentami i współdzielić między procesami roboczymi bez kopiowania defensywnego.

PageSize przechowuje szerokość, wysokość (w punktach; 1 pt = 1/72 cala) oraz nazwę. Fabryki statyczne obejmują serię A normy International Organization for Standardization (ISO) 216 (A0–A6), serię B normy ISO 216 (B0–B5) oraz rozmiary północnoamerykańskie (Letter, Legal, Tabloid). Wymiary A/B odpowiadają serii przyciętych rozmiarów papieru zdefiniowanej przez normę ISO 216. fromName() rozpoznaje nazwy bez rozróżniania wielkości liter i zgłasza PageLayoutException w przypadku nieznanej nazwy. landscape() i portrait() zwracają wariant w danej orientacji albo self, gdy strona ma już tę orientację. toDimension() konwertuje rozmiar strony na Dimension w punktach.

Dimension przechowuje szerokość, wysokość oraz Unit. Fabryki (fromMillimeters(), fromPoints(), fromInches()) tworzą wymiar w wybranej jednostce. toPoints() i toMillimeters() konwertują jednostki; toPoints() zwraca self, gdy wymiar jest już w punktach. withWidth() i withHeight() zwracają kopię z odpowiednio zmienioną szerokością albo wysokością. Konwersje korzystają z dokładnych współczynników: 72/25.4 punktu na milimetr, 72/2.54 na centymetr i 72 na cal.

Position to punkt 2D w przestrzeni użytkownika formatu Portable Document Format (PDF) (x, y). origin() zwraca (0, 0). translate(dx, dy) zwraca przesuniętą kopię. withX() / withY() zwracają kopię ze zmienioną wartością jednej osi.

Margin przechowuje top, right, bottom oraz left. Fabryki to uniform() (ta sama wartość dla wszystkich stron), symmetric(vertical, horizontal) oraz zero().

Unit to wyliczenie o wartościach tekstowych: Point (pt), Millimeter (mm), Centimeter (cm) oraz Inch (in). toPointFactor() zwraca mnożnik przeliczania na punkty.

Powierzchnia API

Symbol	Rodzaj	Kluczowe składowe
NextPDF\ValueObjects\PageSize	klasa final readonly	$width, $height, $name; fabryki A0–A6, B0–B5, Letter, Legal, Tabloid; fromName(), landscape(), portrait(), toDimension()
NextPDF\ValueObjects\Dimension	klasa final readonly	$width, $height, $unit; fromMillimeters(), fromPoints(), fromInches(), toPoints(), toMillimeters(), withWidth(), withHeight()
NextPDF\ValueObjects\Position	klasa final readonly	$x, $y; origin(), translate(), withX(), withY()
NextPDF\ValueObjects\Margin	klasa final readonly	$top, $right, $bottom, $left; uniform(), symmetric(), zero()
NextPDF\ValueObjects\Unit	wyliczenie tekstowe	Point, Millimeter, Centimeter, Inch; toPointFactor()

Przykład kodu — szybki start

Do tworzenia prymitywów geometrycznych używaj fabryk.

<?php

declare(strict_types=1);

use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;
use NextPDF\ValueObjects\Position;

$page = PageSize::A4();                       // 595.276 x 841.890 pt
$margin = Margin::uniform(18.0);              // 18 pt all sides
$origin = Position::origin()->translate(72.0, 72.0); // 1 inch in from corner

Przykład kodu — produkcja

Przeliczaj jednostki, wyznaczaj orientację i przekazuj marginesy do konfiguracji.

<?php

declare(strict_types=1);

use NextPDF\Core\Config;
use NextPDF\ValueObjects\Dimension;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

// A label sized in millimeters, resolved to points for the engine.
$label = Dimension::fromMillimeters(width: 100.0, height: 150.0)->toPoints();

$page = PageSize::A4()->landscape();   // swap to width >= height
$margin = Margin::symmetric(vertical: 20.0, horizontal: 15.0);

$config = (new Config())
    ->withPageSize($page)
    ->withMargins($margin);

// $label->width / $label->height are now in points for downstream layout.

Przypadki brzegowe i pułapki

• Wszystkie wymiary używają punktów, chyba że podasz Dimension z jawną Unit. Marginesy w Config domyślnie używają punktów.
• PageSize::landscape() / portrait() zwracają tę samą instancję, gdy orientacja już się zgadza; nie dochodzi do alokacji, a tożsamość zostaje zachowana.
• PageSize::fromName() ignoruje wielkość liter, ale rozpoznaje tylko nazwane fabryki. Nieznana nazwa zgłasza PageLayoutException, a nie zwraca rozmiaru domyślnego.
• Dimension::toPoints() zwraca self, gdy jednostką jest już Point; nie zakładaj nowego obiektu.
• Te obiekty przechowują surowe wartości float i nie stosują żadnej walidacji zakresu. Akceptują ujemne lub zerowe wymiary podczas konstruowania. Poprawność geometrii wymuszają warstwy układu i zapisu, a nie te obiekty.
• Konwersja zmiennoprzecinkowa korzysta z dokładnych współczynników wymiernych (72/25.4, 72/2.54); zaokrąglaj dopiero na granicy prezentacji, aby zachować stabilność powtarzalnego wyniku.

Wydajność

Każdy obiekt wartości to płaska struktura readonly złożona z wartości float. Konstruowanie i każda transformacja oznaczają pojedynczą alokację O(1) bez głębokiego kopiowania, ponieważ nie istnieje zagnieżdżony stan zmienny. Instancje można współdzielić między dokumentami bez dodatkowego kosztu. Domyślny performance_budget dla tej strony referencyjnej to wall_ms: 1500, peak_mb: 64.

Uwagi dotyczące bezpieczeństwa

Te obiekty wartości nie wykonują żadnych operacji input/output (I/O), nie propagują łańcuchów znaków dostarczonych przez użytkownika poza nazwą rozmiaru strony i nie przechowują uchwytów do zasobów zewnętrznych, więc nie stanowią bezpośredniej powierzchni ataku. PageSize::fromName() odrzuca nieznane dane wejściowe przez zgłoszenie wyjątku zamiast po cichu sięgać po wartość zastępczą, więc błędna konfiguracja kończy się jawnym błędem, a nie generuje nieoczekiwanej geometrii strony.

Zgodność

Specyfikacja	Klauzula	Temat
ISO 216:2007	serie A / B	Wymiary przyciętych rozmiarów papieru dla fabryk A* / B* (parafraza; tekst ISO nie jest cytowany, nie przypięto żadnego fragmentu)

Wymiary fabryk A i B odpowiadają przyciętym rozmiarom ISO 216, wyrażonym w punktach. Rozmiary północnoamerykańskie (Letter, Legal, Tabloid) to de facto rozmiary branżowe bez podstawy w ISO. Odniesienie do ISO jest parafrazowane zgodnie z zasadami cytowania obowiązującymi w witrynie. Nie powiązano go z żadnym dosłownym fragmentem.

Zobacz także

• /modules/core/config/ — Config korzysta z PageSize i Margin
• /modules/core/layout/ — odbiorcy warstwy układu dla tych prymitywów
• /modules/core/graphics/ — Position w przestrzeni współrzędnych rysowania
• /modules/core/contracts/ — Orientation z PageSize
• /modules/core/exception/ — PageLayoutException z fromName()