值物件

TCPDF-Next 對所有幾何與色彩資料使用不可變值物件。每個值物件皆宣告為 final readonly — 一旦建立就無法修改。需要變更時，請建立新的實例。

PageSize

表示頁面尺寸，單位為點（1 pt = 1/72 英吋）。

use Yeeefang\TcpdfNext\ValueObjects\PageSize;

// ISO 216 A 系列
$a4 = PageSize::A4();             // 595.28 x 841.89 pt

// 方向切換（回傳新實例）
$landscape = PageSize::A4()->landscape();   // 841.89 x 595.28 pt
$portrait = PageSize::A4()->portrait();     // 595.28 x 841.89 pt

// 從名稱字串建立
$letter = PageSize::fromName('Letter');

// 自訂尺寸（單位為點）
$custom = new PageSize(400.0, 600.0, 'custom');

工廠方法

系列	方法
ISO A	A0(), A1(), A2(), A3(), A4(), A5(), A6()
ISO B	B0(), B1(), B2(), B3(), B4(), B5()
北美	Letter(), Legal(), Tabloid()

Margin

定義頁面邊界，單位為毫米。

use Yeeefang\TcpdfNext\ValueObjects\Margin;

// 四邊相同
$uniform = Margin::uniform(10.0);               // 四邊皆 10mm

// 對稱：垂直與水平
$symmetric = Margin::symmetric(15.0, 10.0);     // 上下 15mm、左右 10mm

// 無邊界
$zero = Margin::zero();

// 明確指定：上、右、下、左
$explicit = new Margin(20.0, 15.0, 25.0, 15.0);

透過公開唯讀屬性存取各邊值：$margin->top、$margin->right、$margin->bottom、$margin->left。

Position 與 Dimension

簡潔的座標與尺寸配對，提供公開唯讀屬性。

use Yeeefang\TcpdfNext\ValueObjects\{Position, Dimension};

$pos = new Position(50.0, 100.0);   // $pos->x, $pos->y
$dim = new Dimension(210.0, 297.0); // $dim->width, $dim->height

Position 代表文件中的一個 (x, y) 座標點，Dimension 代表一個寬高尺寸。兩者皆為 final readonly，適合在不同頁面或方法間安全傳遞。

Unit

處理單位定義與點、毫米、公分、英吋之間的轉換。

use Yeeefang\TcpdfNext\ValueObjects\Unit;

$mm = Unit::mm();  // 另有：Unit::pt(), Unit::cm(), Unit::in()

// 單位轉換
$points = Unit::convert(25.4, Unit::mm(), Unit::pt());   // 25.4mm = 72pt
$inches = Unit::convert(72.0, Unit::pt(), Unit::in());   // 72pt = 1in

轉換參考

來源	等於多少點
1 pt	1.0
1 mm	2.8346
1 cm	28.3465
1 in	72.0

Color

Color 類別位於 Graphics 命名空間，支援 RGB、CMYK、灰階與特別色模型。如同所有值物件，它是不可變的。

use Yeeefang\TcpdfNext\Graphics\Color;

// RGB (0-255)
$red = Color::rgb(255, 0, 0);
$orange = Color::rgb(255, 102, 0);

// CMYK (0-100)
$processBlack = Color::cmyk(0, 0, 0, 100);
$cyan = Color::cmyk(100, 0, 0, 0);

// 灰階 (0-255，0 = 黑色，255 = 白色)
$gray = Color::gray(128);

// 特別色（名稱 + CMYK 備援）
$pantone = Color::spot('Pantone 151 C', 0, 60, 100, 0);

RGB 適用於螢幕顯示場景，CMYK 適用於專業印刷需求，特別色則用於品牌色彩需要精確重現的情況。

綜合範例

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\ValueObjects\{PageSize, Margin, Unit};
use Yeeefang\TcpdfNext\Graphics\Color;

$landscape = PageSize::A4()->landscape();
$margins = Margin::symmetric(15.0, 10.0);
$orange = Color::rgb(255, 102, 0);

$pdf = Document::create()
    ->addPage($landscape, margin: $margins)
    ->setFont('Helvetica', '', 12)
    ->setTextColor($orange)
    ->cell(0, 10, '使用值物件設定樣式')
    ->save('styled.pdf');

所有值物件皆為 final readonly。landscape() 和 portrait() 等方法回傳新實例 — 永遠不會修改原始物件。這讓值物件可以安全地在頁面、執行緒與函式邊界間共用，無需防禦性複製。