ValueObjects: primitivos del dominio y unidades

De un vistazo

El módulo ValueObjects contiene los primitivos geométricos inmutables que el motor mueve internamente: PageSize, Dimension, Position, Margin y el enum Unit. Cada uno es una clase final readonly, por lo que una instancia puede compartirse con libertad y cada transformación devuelve una instancia nueva.

Instalación

composer require nextpdf/core:^3

Panorama conceptual

Los cuatro objetos de valor son final readonly. Almacenan valores geométricos float y no exponen ningún mutador: los métodos de transformación crean una instancia nueva usando argumentos con nombre. Por eso es seguro almacenarlos en caché, pasarlos entre documentos y compartirlos entre workers sin copias defensivas.

PageSize almacena el ancho, el alto (en puntos; 1 pt = 1/72 de pulgada) y un nombre. Las factorías estáticas cubren la serie A de ISO 216 (A0–A6), la serie B de ISO 216 (B0–B5) y los tamaños norteamericanos (Letter, Legal, Tabloid). Las dimensiones A/B siguen la serie de tamaños de papel recortado que define ISO 216. fromName() resuelve un nombre sin distinguir mayúsculas y minúsculas, y lanza PageLayoutException si recibe un nombre desconocido. landscape() y portrait() devuelven la variante con esa orientación (o self sin cambios cuando ya están en esa orientación). toDimension() lo convierte en una Dimension en puntos.

Dimension almacena el ancho, el alto y una Unit. Las factorías (fromMillimeters(), fromPoints(), fromInches()) construyen instancias en una unidad determinada. toPoints() y toMillimeters() realizan la conversión; toPoints() devuelve self cuando la instancia ya está en puntos. withWidth() y withHeight() devuelven una copia redimensionada. Las conversiones usan factores exactos: 72/25.4 puntos por milímetro, 72/2.54 por centímetro, 72 por pulgada.

Position es un punto 2D en el espacio de usuario de PDF (x, y). origin() devuelve (0, 0). translate(dx, dy) devuelve una copia desplazada. withX() / withY() devuelven una copia con un eje sustituido.

Margin contiene top, right, bottom, left. Sus factorías son uniform() (mismo valor en todos los lados), symmetric(vertical, horizontal) y zero().

Unit es un enum respaldado por cadenas: Point (pt), Millimeter (mm), Centimeter (cm), Inch (in); incluye toPointFactor(), que devuelve el multiplicador a puntos.

Superficie de la API

Símbolo	Tipo	Miembros clave
NextPDF\ValueObjects\PageSize	clase final readonly	$width, $height, $name; factorías A0–A6, B0–B5, Letter, Legal, Tabloid; fromName(), landscape(), portrait(), toDimension()
NextPDF\ValueObjects\Dimension	clase final readonly	$width, $height, $unit; fromMillimeters(), fromPoints(), fromInches(), toPoints(), toMillimeters(), withWidth(), withHeight()
NextPDF\ValueObjects\Position	clase final readonly	$x, $y; origin(), translate(), withX(), withY()
NextPDF\ValueObjects\Margin	clase final readonly	$top, $right, $bottom, $left; uniform(), symmetric(), zero()
NextPDF\ValueObjects\Unit	enum de cadena	Point, Millimeter, Centimeter, Inch; toPointFactor()

Ejemplo de código — Inicio rápido

Construir primitivos geométricos mediante factorías.

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

Ejemplo de código — Producción

Convertir unidades, derivar la orientación y pasar los márgenes a una configuración.

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

Casos límite y trampas

• Todas las dimensiones están en puntos, salvo cuando se encapsulan en una Dimension con una Unit explícita. Los márgenes de Config están en puntos de forma predeterminada.
• PageSize::landscape() / portrait() devuelven la misma instancia cuando la orientación ya coincide: sin asignación nueva y con la identidad preservada.
• PageSize::fromName() no distingue mayúsculas y minúsculas, pero solo reconoce las factorías con nombre. Un nombre desconocido lanza PageLayoutException, no un tamaño predeterminado.
• Dimension::toPoints() devuelve self cuando la unidad ya es Point; no asumir que se obtiene un objeto nuevo.
• Estos objetos almacenan valores float en bruto y no aplican ninguna validación de rango. Se aceptan dimensiones negativas o cero en la construcción. Las capas de layout y escritura hacen cumplir la validez geométrica, no estos objetos.
• Las conversiones con float usan factores racionales exactos (72/25.4, 72/2.54); redondear solo en el límite de presentación para mantener estable la salida reproducible.

Rendimiento

Cada objeto de valor es una estructura plana readonly compuesta por floats. La construcción y cada transformación son asignaciones únicas O(1) sin copia profunda, ya que no hay estado mutable anidado. Compartir una instancia entre documentos no tiene coste práctico. El performance_budget predeterminado de esta página de referencia es wall_ms: 1500, peak_mb: 64.

Notas de seguridad

Estos objetos de valor no realizan E/S, no contienen cadenas suministradas por el usuario más allá de un nombre de tamaño de página ni mantienen handles de recursos externos, así que no presentan ninguna superficie de ataque directa. PageSize::fromName() rechaza entradas desconocidas mediante una excepción, en lugar de recurrir en silencio a un valor predeterminado. Así, una configuración malformada falla de forma visible en vez de producir una geometría de página inesperada.

Conformidad

Especificación	Cláusula	Tema
ISO 216:2007	Serie A / B	Dimensiones de tamaños de papel ya recortados para las factorías A* / B* (parafraseado; prosa de ISO no citada, sin chunk fijado)

Las dimensiones de las factorías A y B corresponden a los tamaños recortados de ISO 216 expresados en puntos. Los tamaños norteamericanos (Letter, Legal, Tabloid) son formatos de la industria de facto, sin base en ISO. La referencia a ISO se presenta parafraseada según la política de citación del sitio. No se fija ningún chunk literal.

Véase también

• /modules/core/config/ — Config consume PageSize y Margin
• /modules/core/layout/ — consumidores geométricos de estos primitivos
• /modules/core/graphics/ — Position dentro del espacio de coordenadas de dibujo
• /modules/core/contracts/ — Orientation asociado a PageSize
• /modules/core/exception/ — PageLayoutException de fromName()