ValueObjects: primitivos de domínio + unidades

Visão geral

O módulo ValueObjects fornece os primitivos imutáveis de geometria usados em todo o mecanismo: PageSize, Dimension, Position, Margin e o enum Unit. Cada um é uma classe final readonly. Você pode compartilhar qualquer instância livremente; cada transformação retorna uma nova instância.

Instalação

composer require nextpdf/core:^3

Visão conceitual

Todos os quatro objetos de valor são final readonly. Eles armazenam coordenadas float e não expõem mutadores; os métodos de transformação criam uma nova instância com argumentos nomeados. Você pode armazená-los em cache, passá-los entre documentos e compartilhá-los entre workers sem precisar de cópia defensiva.

PageSize armazena largura, altura (em pontos; 1 pt = 1/72 de polegada) e um nome. As factories estáticas cobrem a série A da International Organization for Standardization (ISO) 216 (A0–A6), a série B da ISO 216 (B0–B5) e os tamanhos norte-americanos (Letter, Legal, Tabloid). As dimensões A/B seguem a série de tamanhos de papel aparados definida pela ISO 216. fromName() resolve nomes sem diferenciar maiúsculas de minúsculas e lança PageLayoutException quando recebe um nome desconhecido. landscape() e portrait() retornam a variante de orientação, ou self quando a página já está nessa orientação. toDimension() converte o tamanho da página em uma Dimension em pontos.

Dimension armazena largura, altura e uma Unit. As factories (fromMillimeters(), fromPoints(), fromInches()) criam uma dimensão na unidade selecionada. toPoints() e toMillimeters() convertem unidades; toPoints() retorna self quando a dimensão já está em pontos. withWidth() e withHeight() retornam uma cópia com o tamanho ajustado. A conversão usa fatores exatos: 72/25.4 pontos por milímetro, 72/2.54 por centímetro e 72 por polegada.

Position representa um ponto 2D no espaço de usuário do Portable Document Format (PDF) (x, y). origin() retorna (0, 0). translate(dx, dy) retorna uma cópia deslocada. withX() / withY() retornam uma cópia com um eixo substituído.

Margin contém top, right, bottom e left. As factories são uniform() (mesmo valor em todos os lados), symmetric(vertical, horizontal) e zero().

Unit é um enum baseado em string: Point (pt), Millimeter (mm), Centimeter (cm) e Inch (in). toPointFactor() retorna o multiplicador para pontos.

Superfície da API

Símbolo	Tipo	Membros principais
NextPDF\ValueObjects\PageSize	classe final readonly	$width, $height, $name; factories 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 de string	Point, Millimeter, Centimeter, Inch; toPointFactor()

Exemplo de código — Início rápido

Use as factories para criar primitivos de geometria.

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

Exemplo de código — Produção

Converta unidades, derive a orientação e passe margens para uma configuração.

<?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 extremos e pegadinhas

• Todas as dimensões usam pontos, a menos que você forneça uma Dimension com uma Unit explícita. As margens de Config usam pontos por padrão.
• PageSize::landscape() / portrait() retornam a mesma instância quando a orientação já corresponde; não há alocação, e a identidade é preservada.
• PageSize::fromName() ignora maiúsculas e minúsculas, mas reconhece apenas as factories nomeadas. Um nome desconhecido lança PageLayoutException, não um tamanho padrão.
• Dimension::toPoints() retorna self quando a unidade já é Point; não presuma um novo objeto.
• Esses objetos armazenam valores float brutos e não aplicam nenhuma validação de intervalo. Eles aceitam dimensões negativas ou zero na construção. As camadas de layout e de writer são responsáveis pela validade da geometria, não esses objetos.
• A conversão de ponto flutuante usa fatores racionais exatos (72/25.4, 72/2.54); arredonde apenas no limite de apresentação para manter estável a saída reproduzível.

Desempenho

Cada objeto de valor é uma struct readonly plana de floats. A construção e cada transformação fazem uma única alocação O(1), sem cópia profunda, porque não há estado mutável aninhado. Você pode compartilhar uma instância entre documentos sem custo extra. O performance_budget padrão para esta página de referência é wall_ms: 1500, peak_mb: 64.

Notas de segurança

Esses objetos de valor não realizam input/output (I/O), não carregam strings fornecidas pelo usuário além de um nome de tamanho de página e não retêm handles de recursos externos; por isso, não apresentam superfície de ataque direta. PageSize::fromName() rejeita entradas desconhecidas com uma exceção em vez de recorrer silenciosamente a um valor padrão, de modo que uma configuração malformada falha explicitamente em vez de produzir uma geometria de página inesperada.

Conformidade

Especificação	Cláusula	Tópico
ISO 216:2007	Série A / B	Dimensões de tamanhos de papel aparados para as factories A* / B* (parafraseado; texto da ISO não citado, nenhum chunk fixado)

As dimensões das factories A e B correspondem aos tamanhos aparados da ISO 216, expressos em pontos. Os tamanhos norte-americanos (Letter, Legal, Tabloid) são tamanhos de fato do setor, sem base na ISO. A referência à ISO é parafraseada conforme a política de citação do site. Nenhum chunk literal é fixado.

Veja também

• /modules/core/config/ — Config usa PageSize e Margin
• /modules/core/layout/ — consumidores de layout para esses primitivos
• /modules/core/graphics/ — Position no espaço de coordenadas de desenho
• /modules/core/contracts/ — Orientation com PageSize
• /modules/core/exception/ — PageLayoutException de fromName()