ValueObjects: primitive di dominio + unità

In breve

Il modulo ValueObjects contiene le primitive geometriche immutabili che il motore passa tra i vari componenti: PageSize, Dimension, Position, Margin e l’enum Unit. Ciascuna è una classe final readonly: un’istanza può quindi essere condivisa liberamente e ogni trasformazione restituisce una nuova istanza.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

Tutti e quattro gli oggetti valore sono final readonly. Contengono valori float e non espongono alcun mutatore: i metodi di trasformazione ricostruiscono una nuova istanza con argomenti denominati. Questo consente di memorizzarli nella cache, passarli tra documenti e condividerli tra worker in sicurezza, senza copie difensive.

PageSize memorizza larghezza, altezza (in punti; 1 pt = 1/72 di pollice) e un nome. I factory statici coprono la serie A di ISO 216 (A0–A6), la serie B di ISO 216 (B0–B5) e i formati nordamericani (Letter, Legal, Tabloid). Le dimensioni A/B seguono le serie di formati carta rifilati definite da ISO 216. fromName() risolve un nome senza distinguere tra maiuscole e minuscole e genera PageLayoutException se il nome è sconosciuto. landscape() e portrait() restituiscono la variante con l’orientamento richiesto (e restituiscono self invariato quando è già in tale orientamento). toDimension() converte in un Dimension in punti.

Dimension memorizza larghezza, altezza e una Unit. I factory (fromMillimeters(), fromPoints(), fromInches()) costruiscono valori nell’unità indicata. toPoints() e toMillimeters() eseguono la conversione (restituendo self quando il valore è già in punti). withWidth() e withHeight() restituiscono una copia ridimensionata. La conversione utilizza fattori esatti: 72/25.4 punti per millimetro, 72/2.54 per centimetro, 72 per pollice.

Position è un punto 2D nello spazio utente PDF (x, y). origin() restituisce (0, 0). translate(dx, dy) restituisce una copia traslata. withX() / withY() restituiscono una copia con il valore di un asse sostituito.

Margin contiene top, right, bottom, left. Factory: uniform() (stesso valore su tutti i lati), symmetric(vertical, horizontal) e zero().

Unit è un enum con backing di tipo stringa — Point (pt), Millimeter (mm), Centimeter (cm), Inch (in) — con toPointFactor() che restituisce il moltiplicatore in punti.

Superficie API

Simbolo	Tipo	Membri principali
NextPDF\ValueObjects\PageSize	classe final readonly	$width, $height, $name; factory A0–A6, B0–B5, Letter, Legal, Tabloid; fromName(), landscape(), portrait(), toDimension()
NextPDF\ValueObjects\Dimension	classe final readonly	$width, $height, $unit; fromMillimeters(), fromPoints(), fromInches(), toPoints(), toMillimeters(), withWidth(), withHeight()
NextPDF\ValueObjects\Position	classe final readonly	$x, $y; origin(), translate(), withX(), withY()
NextPDF\ValueObjects\Margin	classe final readonly	$top, $right, $bottom, $left; uniform(), symmetric(), zero()
NextPDF\ValueObjects\Unit	enum di tipo stringa	Point, Millimeter, Centimeter, Inch; toPointFactor()

Esempio di codice — Avvio rapido

Costruire le primitive geometriche con i factory.

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

Esempio di codice — Produzione

Convertire le unità, ricavare l’orientamento e passare i margini a una configurazione.

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

Casi limite e insidie

• Tutte le dimensioni sono espresse in punti, a meno che non siano racchiuse in un Dimension con una Unit esplicita. I margini di Config sono espressi in punti per impostazione predefinita.
• PageSize::landscape() / portrait() restituiscono la stessa istanza quando l’orientamento è già quello richiesto — nessuna allocazione, identità preservata.
• PageSize::fromName() non fa distinzione tra maiuscole e minuscole, ma risolve soltanto i factory con nome. Un nome sconosciuto genera PageLayoutException, non un formato predefinito.
• Dimension::toPoints() restituisce self quando l’unità è già Point; non presupporre la creazione di un nuovo oggetto.
• Questi oggetti contengono valori float grezzi e non applicano alcuna convalida dell’intervallo. Dimensioni negative o pari a zero vengono accettate in fase di costruzione. La validità della geometria viene imposta dai livelli di impaginazione e scrittura, non qui.
• Le conversioni in virgola mobile utilizzano fattori razionali esatti (72/25.4, 72/2.54); arrotondare solo al confine di presentazione per mantenere stabile l’output riproducibile.

Prestazioni

Ogni oggetto valore è una struttura piatta readonly composta da float. La costruzione e ogni trasformazione richiedono una singola allocazione O(1), senza copie profonde, poiché non esiste alcuno stato mutabile annidato. La condivisione di un’istanza tra documenti non introduce overhead. Il performance_budget predefinito per questa pagina di riferimento è wall_ms: 1500, peak_mb: 64.

Note sulla sicurezza

Questi oggetti valore non eseguono alcun I/O, non accettano stringhe fornite dall’utente se non un nome di formato pagina e non gestiscono handle di risorse esterne; pertanto non presentano alcuna superficie di attacco diretta. PageSize::fromName() rifiuta l’input sconosciuto tramite eccezione anziché ricorrere silenziosamente a un ripiego, facendo emergere una configurazione malformata invece di produrre una geometria di pagina inattesa.

Conformità

Specifica	Clausola	Argomento
ISO 216:2007	Serie A / B	Dimensioni dei formati carta rifilati per i factory A* / B* (parafrasato; prosa ISO non citata, nessun chunk fissato)

Le dimensioni dei factory A e B corrispondono ai formati rifilati ISO 216 espressi in punti. I formati nordamericani (Letter, Legal, Tabloid) sono formati di fatto del settore, privi di base ISO. Il riferimento ISO è parafrasato secondo la politica di citazione del sito. Non è fissato alcun chunk verbatim.

Vedere anche

• /modules/core/config/ — Config utilizza PageSize e Margin
• /modules/core/layout/ — componenti che consumano queste primitive geometriche
• /modules/core/graphics/ — Position nello spazio delle coordinate di disegno
• /modules/core/contracts/ — Orientation abbinato a PageSize
• /modules/core/exception/ — PageLayoutException da fromName()