Value Objects（值物件）¶

use NextPDF\ValueObjects\PageSize;
use NextPDF\ValueObjects\Dimension;
use NextPDF\ValueObjects\Unit;

// 預定義標準尺寸
$a4 = PageSize::A4;           // 595.28 × 841.89 pt
$letter = PageSize::Letter;   // 612.0 × 792.0 pt
$a3 = PageSize::A3;           // 841.89 × 1190.55 pt

// 自訂尺寸
$custom = PageSize::custom(
    width: Dimension::of(value: 100.0, unit: Unit::Millimeter),
    height: Dimension::of(value: 150.0, unit: Unit::Millimeter),
);

// 交換尺寸（橫向）
$landscape = PageSize::A4->landscape(); // 841.89 × 595.28 pt

// 取得尺寸（總是以 mm 傳回）
echo $a4->widthMm();   // 210.0
echo $a4->heightMm();  // 297.0
echo $a4->widthPt();   // 595.28...
echo $a4->heightPt();  // 841.89...

// A 系列（ISO 216）
PageSize::A0  PageSize::A1  PageSize::A2  PageSize::A3
PageSize::A4  PageSize::A5  PageSize::A6  PageSize::A7
PageSize::A8  PageSize::A9  PageSize::A10

// B 系列（ISO 216）
PageSize::B0  PageSize::B1  PageSize::B2  PageSize::B3
PageSize::B4  PageSize::B5  PageSize::B6  PageSize::B7

// C 系列（信封，ISO 269）
PageSize::C4  PageSize::C5  PageSize::C6  PageSize::DL

// 北美
PageSize::Letter  PageSize::Legal  PageSize::Tabloid  PageSize::Executive
PageSize::HalfLetter  PageSize::GovernmentLetter

// 特殊
PageSize::Ledger   // Tabloid 橫向
PageSize::ANSI_C   // 17 × 22 英吋

use NextPDF\ValueObjects\Dimension;
use NextPDF\ValueObjects\Unit;

$dim = Dimension::of(value: 210.0, unit: Unit::Millimeter);
$dimPt = Dimension::of(value: 595.28, unit: Unit::Point);
$dimIn = Dimension::of(value: 8.27, unit: Unit::Inch);
$dimCm = Dimension::of(value: 21.0, unit: Unit::Centimeter);

// 單位轉換
echo $dim->toMm();     // 210.0
echo $dim->toPt();     // 595.276...
echo $dim->toInch();   // 8.2677...

// 值物件運算（傳回新實例）
$wider = $dim->add(Dimension::of(20.0, Unit::Millimeter));   // 230mm
$half = $dim->multiply(0.5);                                   // 105mm

use NextPDF\ValueObjects\Margin;

// 四邊相同
$uniform = Margin::uniform(20.0);          // top=right=bottom=left=20mm

// 垂直/水平對稱
$symmetric = Margin::symmetric(
    vertical: 25.0,
    horizontal: 20.0,
);

// 各邊獨立
$custom = Margin::of(
    top: 25.0,
    right: 20.0,
    bottom: 30.0,  // 留給頁碼
    left: 20.0,
);

// 取得各邊
echo $custom->top;     // 25.0
echo $custom->right;   // 20.0
echo $custom->bottom;  // 30.0
echo $custom->left;    // 20.0

use NextPDF\ValueObjects\Position;
use NextPDF\ValueObjects\Unit;

// 基本座標（mm，PDF 座標系：左下角原點）
$pos = Position::at(x: 20.0, y: 50.0);

// 指定單位
$posPt = Position::at(x: 56.69, y: 141.73, unit: Unit::Point);

// 特殊位置
$topLeft = Position::topLeft();      // (0, pageHeight)
$origin = Position::origin();        // (0, 0) PDF 左下角

// 加法偏移（傳回新實例）
$offset = $pos->translate(dx: 5.0, dy: -10.0);  // (25.0, 40.0)

// 取得各軸
echo $pos->x;  // 20.0
echo $pos->y;  // 50.0

use NextPDF\ValueObjects\Rectangle;

// 從 XY 座標與尺寸建立
$rect = Rectangle::fromXY(x: 20.0, y: 50.0, width: 100.0, height: 60.0);

// 從對角兩點建立
$rect = Rectangle::fromPoints(
    bottomLeft: Position::at(x: 20.0, y: 50.0),
    topRight: Position::at(x: 120.0, y: 110.0),
);

// 從 Position + Dimension
$rect = Rectangle::fromPositionAndSize(
    position: Position::at(x: 20.0, y: 50.0),
    width: Dimension::of(100.0, Unit::Millimeter),
    height: Dimension::of(60.0, Unit::Millimeter),
);

// 取得衍生位置
$bottomLeft = $rect->bottomLeft();
$topRight = $rect->topRight();
$center = $rect->center();

// 矩形運算
$inset = $rect->inset(amount: 5.0);         // 各邊縮減 5mm
$expanded = $rect->expand(amount: 3.0);     // 各邊擴展 3mm
$clipped = $rect->intersect($otherRect);    // 取交集

use NextPDF\ValueObjects\Unit;

Unit::Millimeter    // mm
Unit::Centimeter    // cm
Unit::Inch          // in
Unit::Point         // pt（1 pt = 1/72 英吋）
Unit::Pixel         // px（96dpi，= 1/96 英吋）
Unit::Pica          // pc（1 pc = 12 pt）

use NextPDF\ValueObjects\Orientation;

Orientation::Portrait    // 直向（預設）
Orientation::Landscape   // 橫向

// 以下都會拋出 InvalidArgumentException
Dimension::of(value: -5.0, unit: Unit::Millimeter);  // 負尺寸
Margin::of(top: -1.0, /* ... */);                     // 負邊距
Rectangle::fromXY(x: 0.0, y: 0.0, width: 0.0, height: 60.0); // 零寬度