ValueObjects: ドメインプリミティブと単位

概要

ValueObjects モジュールは、エンジン内で受け渡されるイミュータブルなジオメトリプリミティブを保持します。対象は PageSize、Dimension、Position、Margin、および Unit 列挙型です。いずれも final readonly クラスであるため、インスタンスを安全に共有でき、変換は新しいインスタンスを返します。

インストール

composer require nextpdf/core:^3

概念の概要

4 つの値オブジェクトはいずれも final readonly です。これらは float 座標を保持し、ミューテーターは公開しません。変換メソッドは名前付き引数を使って新しいインスタンスを再構築します。これにより、防御的コピーなしでキャッシュしたり、ドキュメント間で受け渡したり、ワーカー間で共有したりしても安全です。

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() はサイズ変更済みのコピーを返します。変換には厳密な係数を使用します。1 ミリメートルあたり 72/25.4 ポイント、1 センチメートルあたり 72/2.54、1 インチあたり 72 です。

Position は、PDF ユーザー空間における 2D の点（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`	文字列ベースの enum	`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）を使用します。再現可能な出力を安定させるため、丸めは表示の境界でのみ行ってください。

パフォーマンス

いずれの値オブジェクトも、float のフラットな readonly 構造体です。ネストされたミュータブルな状態がないため、構築と各変換はディープコピーを伴わない O(1) の単一割り当てです。ドキュメント間でインスタンスを共有してもコストはかかりません。このリファレンスページのデフォルトの performance_budget は wall_ms: 1500、peak_mb: 64 です。

セキュリティに関する注意

これらの値オブジェクトは、I/O を持たず、ページサイズ名以外のユーザー指定文字列を持たず、外部リソースハンドルも持たないため、直接的な攻撃対象領域にはなりません。PageSize::fromName() は、不明な入力を暗黙のうちにフォールバックするのではなく例外で拒否します。これにより、予期しないページジオメトリを生成する代わりに、不正な構成を明示的に顕在化させます。

準拠

仕様	条項	トピック
ISO 216:2007	A / B シリーズ	仕上がり用紙サイズの寸法。対象は `A` / `B` ファクトリ（言い換え。ISO の文言は引用せず、チャンクは固定していません）

A および B のファクトリの寸法は、ポイントで表現された ISO 216 の仕上がりサイズに対応します。北米サイズ（Letter、Legal、Tabloid）は、ISO に基づかない事実上の業界標準サイズです。ISO への参照は、サイトの引用ポリシーに従って言い換えています。逐語的なチャンクは固定していません。