ValueObjects: Domain-Primitives + Einheiten

Auf einen Blick

Das ValueObjects-Modul enthält die unveränderlichen Geometrie-Primitive, die von der Engine weitergereicht werden: PageSize, Dimension, Position, Margin und das Unit-Enum. Jede davon ist eine final readonly-Klasse, sodass sich Instanzen problemlos teilen lassen und jede Transformation eine neue Instanz zurückgibt.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

Alle vier Value-Objects sind final readonly. Sie speichern float-Koordinaten und stellen keine Mutatoren bereit — Transformationsmethoden bauen mit benannten Argumenten eine neue Instanz auf. Dadurch lassen sie sich gefahrlos cachen, zwischen Dokumenten weitergeben und ohne defensives Kopieren über Worker hinweg teilen.

PageSize speichert Breite, Höhe (in Punkt; 1 pt = 1/72 Zoll) und einen Namen. Statische Fabriken decken die A-Reihe nach ISO 216 (A0–A6), die B-Reihe nach ISO 216 (B0–B5) und die nordamerikanischen Größen (Letter, Legal, Tabloid) ab. Die A-/B-Maße folgen den von ISO 216 definierten Reihen beschnittener Papierformate. fromName() löst einen Namen unabhängig von Groß-/Kleinschreibung auf und wirft bei einem unbekannten Namen PageLayoutException. landscape() und portrait() geben die Variante in der jeweiligen Ausrichtung zurück (und geben self unverändert zurück, wenn die Ausrichtung bereits vorliegt). toDimension() konvertiert in eine Dimension in Punkt.

Dimension speichert Breite, Höhe und eine Unit. Fabriken (fromMillimeters(), fromPoints(), fromInches()) konstruieren in der angegebenen Einheit. toPoints() und toMillimeters() konvertieren (und geben self zurück, wenn die Einheit bereits Punkt ist). withWidth() und withHeight() geben eine Kopie mit angepasster Größe zurück. Die Konvertierung verwendet exakte Faktoren: 72/25.4 Punkt pro Millimeter, 72/2.54 pro Zentimeter, 72 pro Zoll.

Position ist ein 2D-Punkt im PDF-Benutzerkoordinatensystem (x, y). origin() gibt (0, 0) zurück. translate(dx, dy) gibt eine verschobene Kopie zurück. withX() / withY() geben eine Kopie mit geändertem Achsenwert zurück.

Margin enthält top, right, bottom, left. Fabriken sind uniform() (gleicher Wert auf allen Seiten), symmetric(vertical, horizontal) und zero().

Unit ist ein String-basiertes Enum — Point (pt), Millimeter (mm), Centimeter (cm), Inch (in) — mit toPointFactor(), das den Multiplikator für die Umrechnung in Punkt zurückgibt.

API-Oberfläche

Symbol	Art	Wichtige Mitglieder
NextPDF\ValueObjects\PageSize	final readonly-Klasse	$width, $height, $name; Fabriken A0–A6, B0–B5, Letter, Legal, Tabloid; fromName(), landscape(), portrait(), toDimension()
NextPDF\ValueObjects\Dimension	final readonly-Klasse	$width, $height, $unit; fromMillimeters(), fromPoints(), fromInches(), toPoints(), toMillimeters(), withWidth(), withHeight()
NextPDF\ValueObjects\Position	final readonly-Klasse	$x, $y; origin(), translate(), withX(), withY()
NextPDF\ValueObjects\Margin	final readonly-Klasse	$top, $right, $bottom, $left; uniform(), symmetric(), zero()
NextPDF\ValueObjects\Unit	String-Enum	Point, Millimeter, Centimeter, Inch; toPointFactor()

Codebeispiel — Schnellstart

Erstellen Sie Geometrie-Primitive mit Fabriken.

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

Codebeispiel — Produktion

Konvertieren Sie Einheiten, leiten Sie die Ausrichtung ab und übergeben Sie Ränder an eine Konfiguration.

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

Randfälle & Fallstricke

• Alle Maße sind in Punkt angegeben, sofern sie nicht in eine Dimension mit einer expliziten Unit eingebettet sind. Config-Ränder sind standardmäßig Punkt.
• PageSize::landscape() / portrait() geben dieselbe Instanz zurück, wenn die Ausrichtung bereits übereinstimmt — keine Allokation, Identität bleibt erhalten.
• PageSize::fromName() ignoriert Groß-/Kleinschreibung, löst aber nur die benannten Fabriken auf. Ein unbekannter Name wirft PageLayoutException und liefert keine Standardgröße.
• Dimension::toPoints() gibt self zurück, wenn die Einheit bereits Point ist; gehen Sie nicht von einem neuen Objekt aus.
• Diese Objekte speichern rohe float-Werte und führen keine Bereichsvalidierung durch. Negative Maße oder Maße der Größe null werden bei der Konstruktion akzeptiert. Die geometrische Gültigkeit wird von den Layout- und Writer-Schichten erzwungen, nicht hier.
• Die Float-Konvertierung verwendet exakte rationale Faktoren (72/25.4, 72/2.54); runden Sie erst an der Darstellungsgrenze, um die reproduzierbare Ausgabe stabil zu halten.

Performance

Jedes Value-Object ist eine flache readonly-Struktur aus Floats. Die Konstruktion und jede Transformation sind einzelne O(1)-Allokationen ohne tiefe Kopie, da es keinen verschachtelten veränderlichen Zustand gibt. Das Teilen einer Instanz über Dokumente hinweg verursacht keinen zusätzlichen Aufwand. Das Standard-performance_budget für diese Referenzseite ist wall_ms: 1500, peak_mb: 64.

Sicherheitshinweise

Diese Value-Objects führen keine E/A aus, enthalten außer einem Seitengrößennamen keine benutzergelieferten Strings und keine externen Ressourcen-Handles, sodass sie keine direkte Angriffsfläche bieten. PageSize::fromName() weist unbekannte Eingaben per Exception zurück, anstatt stillschweigend auf einen Standard zurückzufallen; dadurch wird eine fehlerhafte Konfiguration sichtbar, statt eine unerwartete Seitengeometrie zu erzeugen.

Konformität

Spezifikation	Abschnitt	Thema
ISO 216:2007	A-/B-Reihe	Maße der beschnittenen Papierformate für die A*-/B*-Fabriken (paraphrasiert; ISO-Text nicht zitiert, kein Chunk angeheftet)

Die Maße der A- und B-Fabriken entsprechen den in Punkt ausgedrückten, nach ISO 216 beschnittenen Größen. Nordamerikanische Größen (Letter, Legal, Tabloid) sind De-facto-Industriegrößen ohne ISO-Grundlage. Die ISO-Referenz wird gemäß der Zitationsrichtlinie der Website paraphrasiert. Es ist kein wörtlicher Chunk angeheftet.

Siehe auch

• /modules/core/config/ — Config nutzt PageSize und Margin
• /modules/core/layout/ — Konsumenten dieser Geometrie-Primitive
• /modules/core/graphics/ — Position im Zeichenkoordinatenraum
• /modules/core/contracts/ — Orientation in Kombination mit PageSize
• /modules/core/exception/ — PageLayoutException aus fromName()