ValueObjects: domeinprimitieven + eenheden

In een oogopslag

De ValueObjects-module levert de onveranderlijke geometrieprimitieven die door de hele engine heen worden gebruikt: PageSize, Dimension, Position, Margin en de enum Unit. Elk daarvan is een final readonly-klasse. U kunt instanties vrij delen; elke transformatie levert een nieuwe instantie op.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

Alle vier de waardeobjecten zijn final readonly. Ze slaan float-coördinaten op en stellen geen mutators beschikbaar; transformatiemethoden bouwen met benoemde argumenten een nieuwe instantie op. U kunt ze cachen, tussen documenten doorgeven en tussen workers delen zonder defensieve kopieën te maken.

PageSize slaat breedte, hoogte (in punten; 1 pt = 1/72 inch) en een naam op. Statische factories omvatten de A-serie van de International Organization for Standardization (ISO) 216 (A0–A6), de B-serie van ISO 216 (B0–B5) en Noord-Amerikaanse formaten (Letter, Legal, Tabloid). De A/B-afmetingen volgen de bijgesneden papierformaatreeks die ISO 216 definieert. fromName() verwerkt namen zonder onderscheid tussen hoofdletters en kleine letters en werpt PageLayoutException bij een onbekende naam. landscape() en portrait() retourneren de oriëntatievariant, of self wanneer de pagina die oriëntatie al heeft. toDimension() converteert het paginaformaat naar een Dimension in punten.

Dimension slaat breedte, hoogte en een Unit op. Factories (fromMillimeters(), fromPoints(), fromInches()) maken een afmeting in de gekozen eenheid. toPoints() en toMillimeters() zetten eenheden om; toPoints() retourneert self wanneer de afmeting al in punten is. withWidth() en withHeight() retourneren een kopie met een aangepast formaat. Voor conversie worden exacte factoren gebruikt: 72/25.4 punten per millimeter, 72/2.54 per centimeter en 72 per inch.

Position is een 2D-punt in de gebruikersruimte van Portable Document Format (PDF) (x, y). origin() retourneert (0, 0). translate(dx, dy) retourneert een verschoven kopie. withX() / withY() retourneren een kopie met één gewijzigde as.

Margin bevat top, right, bottom en left. De factories zijn uniform() (dezelfde waarde aan alle zijden), symmetric(vertical, horizontal) en zero().

Unit is een string-backed enum: Point (pt), Millimeter (mm), Centimeter (cm) en Inch (in). toPointFactor() retourneert de vermenigvuldigingsfactor voor omzetting naar punten.

API-oppervlak

Symbool	Soort	Belangrijkste leden
NextPDF\ValueObjects\PageSize	final readonly-klasse	$width, $height, $name; factories 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()

Codevoorbeeld — Snelstart

Maak geometrieprimitieven aan met factories.

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

Codevoorbeeld — Productie

Converteer eenheden, bepaal de oriëntatie en geef marges door aan een configuratie.

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

Randgevallen en valkuilen

• Alle afmetingen gebruiken punten, tenzij u een Dimension met een expliciete Unit opgeeft. Config-marges gebruiken standaard punten.
• PageSize::landscape() / portrait() retourneren dezelfde instantie wanneer de oriëntatie al overeenkomt; er vindt geen allocatie plaats en de identiteit blijft behouden.
• PageSize::fromName() maakt geen onderscheid tussen hoofdletters en kleine letters, maar zoekt alleen in de benoemde factories. Een onbekende naam werpt PageLayoutException en levert geen standaardformaat.
• Dimension::toPoints() retourneert self wanneer de eenheid al Point is; ga niet uit van een nieuw object.
• Deze objecten bevatten ruwe float-waarden en passen geen bereikvalidatie toe. Bij constructie accepteren ze negatieve afmetingen of nulafmetingen. De lay-out- en writerlagen bewaken de geometrische geldigheid, niet deze objecten.
• Floating-point-conversie gebruikt exacte rationale factoren (72/25.4, 72/2.54); rond pas aan de presentatiegrens af om reproduceerbare uitvoer stabiel te houden.

Prestaties

Elk waardeobject is een platte readonly-struct van floats. Constructie en elke transformatie zijn O(1): één allocatie zonder diepe kopie, omdat er geen geneste muteerbare toestand is. U kunt een instantie zonder extra kosten over documenten heen delen. De standaard performance_budget voor deze referentiepagina is wall_ms: 1500, peak_mb: 64.

Beveiligingsnotities

Deze waardeobjecten voeren geen input/output (I/O) uit, bevatten behalve een paginaformaatnaam geen door de gebruiker geleverde strings en houden geen externe resource-handles vast. Daardoor vormen ze geen direct aanvalsoppervlak. PageSize::fromName() wijst onbekende invoer af met een uitzondering in plaats van stilzwijgend terug te vallen, zodat een ongeldig gevormde configuratie expliciet mislukt in plaats van onverwachte paginageometrie te produceren.

Conformiteit

Specificatie	Clausule	Onderwerp
ISO 216:2007	A / B-serie	Bijgesneden papierformaatafmetingen voor de A*- / B*-factories (geparafraseerd; ISO-tekst niet geciteerd, geen chunk vastgezet)

De afmetingen van de A- en B-factories komen overeen met de bijgesneden formaten van ISO 216, uitgedrukt in punten. Noord-Amerikaanse formaten (Letter, Legal, Tabloid) zijn de-facto-industrieformaten zonder ISO-grondslag. De ISO-referentie is geparafraseerd volgens het citatiebeleid van de site. Er wordt geen letterlijke chunk vastgezet.

Zie ook

• /modules/core/config/ — Config gebruikt PageSize en Margin
• /modules/core/layout/ — lay-outconsumenten voor deze primitieven
• /modules/core/graphics/ — Position in de tekencoördinaatruimte
• /modules/core/contracts/ — Orientation met PageSize
• /modules/core/exception/ — PageLayoutException uit fromName()