ValueObjects：領域基本型別與單位

概覽

ValueObjects 模組存放在引擎中流轉的不可變幾何基本型別：PageSize、Dimension、Position、Margin，以及 Unit 列舉。每一個都是 final readonly 類別，因此實例可以自由共用，而轉換方法則會回傳新實例。

安裝

composer require nextpdf/core:^3

概念總覽

這四個值物件都是 final readonly。它們持有 float 座標值，且不提供任何變動器——轉換方法會透過具名引數重新建構新實例。如此一來，它們可以安全快取、在文件之間傳遞，並跨 worker 共用，而無須防禦性複製。

PageSize 儲存寬度、高度（以點為單位；1 pt = 1/72 英吋）以及名稱。靜態工廠涵蓋 ISO 216 A 系列（A0–A6）、ISO 216 B 系列（B0–B5），以及北美尺寸（Letter、Legal、Tabloid）。A/B 維度依循 ISO 216 定義的修整後紙張尺寸系列。fromName() 會以不分大小寫的方式解析（resolve）名稱，並在名稱未知時擲出 PageLayoutException。landscape() 與 portrait() 會回傳對應方向的變體（若已是該方向，則直接回傳 self）。toDimension() 會轉換為以點為單位的 Dimension。

Dimension 儲存寬度、高度與一個 Unit。工廠方法（fromMillimeters()、fromPoints()、fromInches()）會依指定單位建構。toPoints() 與 toMillimeters() 會進行轉換（若已是點，則回傳 self）。withWidth() 與 withHeight() 會回傳調整尺寸後的複本。換算採用精確因數：每公釐 72/25.4 點、每公分 72/2.54 點，每英吋 72 點。

Position 是 PDF 使用者空間中的二維點（x, y）。origin() 會回傳 (0, 0)。translate(dx, dy) 會回傳位移後的複本。withX() / withY() 會回傳僅替換單一軸的複本。

Margin 持有 top、right、bottom、left。工廠方法包括：uniform()（四邊同值）、symmetric(vertical, horizontal)，以及 zero()。

Unit 是以字串為基底的列舉——Point（pt）、Millimeter（mm）、Centimeter（cm）、Inch（in）——並以 toPointFactor() 回傳換算成點的乘數。

API 介面

符號	種類	主要成員
NextPDF\ValueObjects\PageSize	final readonly 類別	$width、$height、$name；工廠方法 A0–A6、B0–B5、Letter、Legal、Tabloid；fromName()、landscape()、portrait()、toDimension()
NextPDF\ValueObjects\Dimension	final readonly 類別	$width、$height、$unit；fromMillimeters()、fromPoints()、fromInches()、toPoints()、toMillimeters()、withWidth()、withHeight()
NextPDF\ValueObjects\Position	final readonly 類別	$x、$y；origin()、translate()、withX()、withY()
NextPDF\ValueObjects\Margin	final readonly 類別	$top、$right、$bottom、$left；uniform()、symmetric()、zero()
NextPDF\ValueObjects\Unit	string 列舉	Point、Millimeter、Centimeter、Inch；toPointFactor()

程式碼範例——快速入門

使用工廠方法建構幾何基本型別。

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

程式碼範例——正式環境

換算單位、推導方向，並將邊界傳入組態。

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

邊界情況與陷阱

• 除非將維度包成 Dimension 並指定明確的 Unit，否則所有維度都以點表示。Config 的邊界預設以點為單位。
• PageSize::landscape() / portrait() 在方向已經相符時會回傳同一個實例——不會配置新記憶體，並保留識別性。
• PageSize::fromName() 不分大小寫，但只能解析具名的工廠方法。未知名稱會擲出 PageLayoutException，而非套用預設尺寸。
• Dimension::toPoints() 會回傳 self，前提是單位已經是 Point；請勿假設它一定是新物件。
• 這些物件持有原始的 float 值，且不套用任何範圍驗證。負值或零值的維度在建構時都會被接受。幾何有效性是由版面配置層與寫入層強制執行，而非在這裡。
• 浮點換算採用精確的有理因數（72/25.4、72/2.54）；只在呈現邊界處才四捨五入，以保持可重現輸出的穩定。

效能

每個值物件都是由浮點數構成的扁平 readonly 結構。建構與每一次轉換都是 O(1) 的單次配置，且不需要深層複製，因為內部沒有巢狀的可變狀態。跨文件共用一個實例是零成本的。本參考頁面的預設 performance_budget 為 wall_ms: 1500、peak_mb: 64。

安全性注意事項

這些值物件不帶任何 I/O；除了頁面尺寸名稱之外，不含任何使用者提供的字串，也沒有任何外部資源控制代碼，因此不構成直接的攻擊面。PageSize::fromName() 會以擲出例外的方式拒絕未知輸入，而非默默回退，讓格式錯誤的組態維持明顯，而不會產生非預期的頁面幾何。

符合性

規格	條款	主題
ISO 216:2007	A/B 系列	供 A* / B* 工廠方法使用的修整後紙張尺寸維度（採改寫；未引用 ISO 原文，亦未釘選任何 chunk）

A 與 B 工廠方法的維度，對應 ISO 216 以點表示的修整後尺寸。北美尺寸（Letter、Legal、Tabloid）是事實上的業界尺寸，並無 ISO 依據。此 ISO 參照依本站引用政策採改寫呈現。未釘選任何逐字 chunk。

另請參閱

• /modules/core/config/ —— Config 會使用 PageSize 與 Margin
• /modules/core/layout/ —— 這些基本型別的幾何消費端
• /modules/core/graphics/ —— Position 所在的繪圖座標空間
• /modules/core/contracts/ —— Orientation 搭配 PageSize
• /modules/core/exception/ —— PageLayoutException 來自 fromName()