ValueObjects: primitif domain + satuan

Sekilas pandang

Modul ValueObjects menyediakan primitif geometri imutabel yang dipakai di seluruh mesin: PageSize, Dimension, Position, Margin, dan enum Unit. Masing-masing adalah kelas final readonly. Instans dapat dibagikan secara bebas, dan setiap transformasi mengembalikan instans baru.

Pemasangan

composer require nextpdf/core:^3

Tinjauan konseptual

Keempat objek nilai semuanya final readonly. Objek-objek ini menyimpan koordinat float dan tidak mengekspos mutator; metode transformasi membentuk instans baru dengan argumen bernama. Anda dapat menyimpannya di-cache, meneruskannya antardokumen, dan membagikannya di antara worker tanpa penyalinan defensif.

PageSize menyimpan lebar, tinggi (dalam poin; 1 pt = 1/72 inci), dan sebuah nama. Factory statis mencakup seri A dari International Organization for Standardization (ISO) 216 (A0–A6), seri B dari ISO 216 (B0–B5), dan ukuran Amerika Utara (Letter, Legal, Tabloid). Dimensi A/B mengikuti seri ukuran kertas terpotong yang didefinisikan oleh ISO 216. fromName() menyelesaikan nama tanpa membedakan huruf besar/kecil dan melempar PageLayoutException untuk nama yang tidak dikenal. landscape() dan portrait() mengembalikan varian orientasi, atau self jika halaman sudah berada dalam orientasi tersebut. toDimension() mengonversi ukuran halaman menjadi Dimension dalam poin.

Dimension menyimpan lebar, tinggi, dan sebuah Unit. Factory (fromMillimeters(), fromPoints(), fromInches()) membuat dimensi dalam satuan yang dipilih. toPoints() dan toMillimeters() mengonversi satuan; toPoints() mengembalikan self jika dimensi sudah dalam poin. withWidth() dan withHeight() mengembalikan salinan yang telah diubah ukurannya. Konversi menggunakan faktor eksak: 72/25.4 poin per milimeter, 72/2.54 per sentimeter, dan 72 per inci.

Position adalah titik 2D dalam ruang pengguna Portable Document Format (PDF) (x, y). origin() mengembalikan (0, 0). translate(dx, dy) mengembalikan salinan dengan offset. withX() / withY() mengembalikan salinan dengan satu sumbu diganti.

Margin menyimpan top, right, bottom, dan left. Factory yang tersedia adalah uniform() (nilai sama di semua sisi), symmetric(vertical, horizontal), dan zero().

Unit adalah enum berbasis string: Point (pt), Millimeter (mm), Centimeter (cm), dan Inch (in). toPointFactor() mengembalikan pengali ke poin.

Permukaan API

Simbol	Jenis	Anggota utama
NextPDF\ValueObjects\PageSize	kelas final readonly	$width, $height, $name; factory A0–A6, B0–B5, Letter, Legal, Tabloid; fromName(), landscape(), portrait(), toDimension()
NextPDF\ValueObjects\Dimension	kelas final readonly	$width, $height, $unit; fromMillimeters(), fromPoints(), fromInches(), toPoints(), toMillimeters(), withWidth(), withHeight()
NextPDF\ValueObjects\Position	kelas final readonly	$x, $y; origin(), translate(), withX(), withY()
NextPDF\ValueObjects\Margin	kelas final readonly	$top, $right, $bottom, $left; uniform(), symmetric(), zero()
NextPDF\ValueObjects\Unit	enum string	Point, Millimeter, Centimeter, Inch; toPointFactor()

Contoh kode — Mulai cepat

Gunakan factory untuk membuat primitif geometri.

<?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

Contoh kode — Produksi

Konversi satuan, ubah orientasi, dan teruskan margin ke dalam konfigurasi.

<?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.

Kasus tepi & jebakan

• Semua dimensi menggunakan poin, kecuali jika Anda menyediakan Dimension dengan Unit eksplisit. Margin pada Config menggunakan poin secara baku.
• PageSize::landscape() / portrait() mengembalikan instans yang sama jika orientasinya sudah cocok; tidak ada alokasi yang terjadi, dan identitas dipertahankan.
• PageSize::fromName() mengabaikan huruf besar/kecil, tetapi hanya menyelesaikan factory bernama. Nama yang tidak dikenal melempar PageLayoutException, bukan menggunakan ukuran baku.
• Dimension::toPoints() mengembalikan self jika satuannya sudah Point; jangan berasumsi ada objek baru.
• Objek-objek ini menyimpan nilai float mentah dan tidak menerapkan validasi rentang. Objek-objek ini menerima dimensi negatif atau nol saat konstruksi. Validitas geometri diberlakukan oleh lapisan layout dan writer, bukan oleh objek-objek ini.
• Konversi titik mengambang menggunakan faktor rasional eksak (72/25.4, 72/2.54); bulatkan hanya pada batas penyajian agar keluaran yang dapat direproduksi tetap stabil.

Performa

Setiap objek nilai adalah struct datar readonly yang berisi float. Konstruksi dan setiap transformasi adalah alokasi tunggal O(1) tanpa penyalinan dalam karena tidak ada keadaan mutabel bersarang. Anda dapat berbagi instans antardokumen tanpa biaya tambahan. performance_budget baku untuk halaman referensi ini adalah wall_ms: 1500, peak_mb: 64.

Catatan keamanan

Objek nilai ini tidak melakukan input/output (I/O), tidak membawa string yang dipasok pengguna selain nama ukuran halaman, dan tidak memegang handle sumber daya eksternal, sehingga tidak menghadirkan permukaan serangan langsung. PageSize::fromName() menolak input yang tidak dikenal dengan melempar eksepsi alih-alih memakai fallback diam-diam, sehingga konfigurasi yang salah bentuk gagal secara eksplisit alih-alih menghasilkan geometri halaman yang tak terduga.

Kesesuaian

Spesifikasi	Klausul	Topik
ISO 216:2007	Seri A / B	Dimensi ukuran kertas terpotong untuk factory A* / B* (diparafrasekan; prosa ISO tidak dikutip, tidak ada chunk yang dipatok)

Dimensi factory A dan B sesuai dengan ukuran terpotong ISO 216, dinyatakan dalam poin. Ukuran Amerika Utara (Letter, Legal, Tabloid) adalah ukuran industri de facto tanpa dasar ISO. Referensi ISO diparafrasekan sesuai kebijakan sitasi situs. Tidak ada chunk verbatim yang dipatok.

Lihat juga

• /modules/core/config/ — Config menggunakan PageSize dan Margin
• /modules/core/layout/ — konsumen layout bagi primitif-primitif ini
• /modules/core/graphics/ — Position dalam ruang koordinat penggambaran
• /modules/core/contracts/ — Orientation dengan PageSize
• /modules/core/exception/ — PageLayoutException dari fromName()