API de Value Objects

Todos los value objects en TCPDF-Next son inmutables. Cada método "modificador" retorna una nueva instancia, dejando el original sin cambios. Esto elimina una categoría de bugs causados por estado mutable compartido.

PageSize

Namespace: TcpdfNext\ValueObjects\PageSize

Representa las dimensiones de una página. Internamente todas las medidas se almacenan en puntos PDF (1/72 de pulgada).

Métodos factory (Serie ISO A)

PageSize::a0(): static

841 x 1189 mm

PageSize::a1(): static

594 x 841 mm

PageSize::a2(): static

420 x 594 mm

PageSize::a3(): static

297 x 420 mm

PageSize::a4(): static

210 x 297 mm (predeterminado)

PageSize::a5(): static

148 x 210 mm

PageSize::a6(): static

105 x 148 mm

Métodos factory (Serie ISO B)

PageSize::b0(): static

1000 x 1414 mm

PageSize::b1(): static

707 x 1000 mm

PageSize::b2(): static

500 x 707 mm

PageSize::b3(): static

353 x 500 mm

PageSize::b4(): static

250 x 353 mm

PageSize::b5(): static

176 x 250 mm

Métodos factory (Norteamericanos)

PageSize::letter(): static

8.5 x 11 in (215.9 x 279.4 mm)

PageSize::legal(): static

8.5 x 14 in (215.9 x 355.6 mm)

PageSize::tabloid(): static

11 x 17 in (279.4 x 431.8 mm)

Personalizado y búsqueda

PageSize::fromMm(float $width, float $height, string $name = 'Custom'): static

Crear un tamaño de página desde dimensiones en milímetros.

PageSize::fromPoints(float $width, float $height, string $name = 'Custom'): static

Crear un tamaño de página desde dimensiones en puntos.

PageSize::fromName(string $name): static

Buscar un tamaño de página estándar por nombre (sin distinción de mayúsculas). Lanza InvalidArgumentException para nombres desconocidos.

Helpers de orientación

landscape(): static

Retornar un nuevo PageSize con ancho y alto intercambiados para que ancho > alto.

portrait(): static

Retornar un nuevo PageSize con ancho y alto intercambiados para que alto > ancho.

Propiedades

Propiedad	Tipo	Descripción
`$width`	`float`	Ancho en puntos
`$height`	`float`	Alto en puntos
`$name`	`string`	Nombre legible (ej., `'A4'`, `'Letter'`)

Métodos de conveniencia

widthMm(): float

Retornar el ancho en milímetros.

heightMm(): float

Retornar el alto en milímetros.

Ejemplo

php

use TcpdfNext\ValueObjects\PageSize;

$a4 = PageSize::a4();
$landscape = $a4->landscape();   // 297 x 210 mm
$custom = PageSize::fromMm(140, 216, 'Half Letter');
$letter = PageSize::fromName('Letter');

Margin

Namespace: TcpdfNext\ValueObjects\Margin

Representa márgenes de página en cuatro lados. El almacenamiento interno es en puntos PDF.

Métodos factory

Margin::mm(float $top, float $right, float $bottom, float $left): static

Crear márgenes desde valores en milímetros.

Margin::pt(float $top, float $right, float $bottom, float $left): static

Crear márgenes desde valores en puntos.

Margin::uniform(float $value): static

Los cuatro lados iguales (en puntos).

Margin::uniformMm(float $value): static

Los cuatro lados iguales (en milímetros).

Margin::symmetric(float $horizontal, float $vertical): static

Márgenes simétricos (horizontal = izquierda + derecha, vertical = arriba + abajo) en puntos.

Margin::zero(): static

Todos los márgenes establecidos a cero.

Propiedades

Propiedad	Tipo	Descripción
`$top`	`float`	Margen superior en puntos
`$right`	`float`	Margen derecho en puntos
`$bottom`	`float`	Margen inferior en puntos
`$left`	`float`	Margen izquierdo en puntos

Métodos modificadores

withTop(float $value): static

Retornar un nuevo Margin con el valor superior reemplazado (en puntos).

withRight(float $value): static

Retornar un nuevo Margin con el valor derecho reemplazado.

withBottom(float $value): static

Retornar un nuevo Margin con el valor inferior reemplazado.

withLeft(float $value): static

Retornar un nuevo Margin con el valor izquierdo reemplazado.

Métodos de cálculo

printableArea(PageSize $pageSize): Dimension

Retornar la Dimension imprimible (tamaño de página menos márgenes).

Ejemplo

php

use TcpdfNext\ValueObjects\Margin;
use TcpdfNext\ValueObjects\PageSize;

$margin = Margin::mm(top: 15, right: 20, bottom: 15, left: 20);
$narrow = $margin->withLeft(36.0)->withRight(36.0);
$area = $margin->printableArea(PageSize::a4());
echo $area->widthMm(); // 170.0

Position

Namespace: TcpdfNext\ValueObjects\Position

Un par de coordenadas x--y inmutable en puntos PDF.

Métodos factory

new Position(float $x, float $y)

Crear desde valores en puntos.

Position::mm(float $x, float $y): static

Crear desde valores en milímetros (convertido a puntos internamente).

Propiedades

Propiedad	Tipo	Descripción
`$x`	`float`	Coordenada horizontal en puntos
`$y`	`float`	Coordenada vertical en puntos

Métodos

translate(float $dx, float $dy): static

Retornar una nueva Position desplazada por (dx, dy) puntos.

xMm(): float

Retornar x en milímetros.

yMm(): float

Retornar y en milímetros.

Ejemplo

php

use TcpdfNext\ValueObjects\Position;

$pos = Position::mm(x: 25.4, y: 50.8);
$shifted = $pos->translate(dx: 10, dy: 20);
echo $shifted->xMm(); // ~28.9

Dimension

Namespace: TcpdfNext\ValueObjects\Dimension

Un par ancho--alto inmutable en puntos PDF.

Métodos factory

new Dimension(float $width, float $height)

Crear desde valores en puntos.

Dimension::mm(float $width, float $height): static

Crear desde valores en milímetros.

Propiedades

Propiedad	Tipo	Descripción
`$width`	`float`	Ancho en puntos
`$height`	`float`	Alto en puntos

Métodos

swap(): static

Retornar una nueva Dimension con ancho y alto intercambiados.

widthMm(): float

Retornar el ancho en milímetros.

heightMm(): float

Retornar el alto en milímetros.

area(): float

Retornar el área en puntos cuadrados.

Ejemplo

php

use TcpdfNext\ValueObjects\Dimension;

$dim = Dimension::mm(width: 210, height: 297);
echo $dim->width;      // 595.28
echo $dim->widthMm();  // 210.0
$swapped = $dim->swap(); // 297 x 210 mm equivalent

Unit

Namespace: TcpdfNext\ValueObjects\Unit

Clase de utilidad estática para convertir entre unidades de medida. Todas las conversiones se basan en el estándar PDF de 72 puntos por pulgada.

Métodos de conversión

Unit::mm(float $value): float

Convertir milímetros a puntos. Alias para mmToPoints().

Unit::pt(float $value): float

Identidad -- retorna el valor sin cambios (para consistencia de API).

Unit::cm(float $value): float

Convertir centímetros a puntos.

Unit::in(float $value): float

Convertir pulgadas a puntos (valor x 72).

Unit::mmToPoints(float $mm): float

Convertir milímetros a puntos (mm x 72 / 25.4).

Unit::pointsToMm(float $pt): float

Convertir puntos a milímetros (pt x 25.4 / 72).

Unit::inchesToPoints(float $inches): float

Convertir pulgadas a puntos (inches x 72).

Unit::pointsToInches(float $pt): float

Convertir puntos a pulgadas (pt / 72).

Unit::cmToPoints(float $cm): float

Convertir centímetros a puntos (cm x 72 / 2.54).

Unit::pointsToCm(float $pt): float

Convertir puntos a centímetros (pt x 2.54 / 72).

Unit::convert(float $value, string $from, string $to): float

Conversor de propósito general. Cadenas de unidad soportadas: 'mm', 'cm', 'in', 'pt'.

Ejemplo

php

use TcpdfNext\ValueObjects\Unit;

$points = Unit::mmToPoints(210.0);       // 595.28
$mm     = Unit::pointsToMm(595.28);      // 210.0
$points = Unit::inchesToPoints(8.5);     // 612.0
$result = Unit::convert(1.0, 'in', 'mm'); // 25.4

Color

Namespace: TcpdfNext\Graphics\Color

Representación de color inmutable que soporta múltiples espacios de color. Aunque Color reside en el paquete Graphics, se usa de forma generalizada en toda la biblioteca (color de texto, color de trazo, color de relleno, color de marcador, color de anotación).

Métodos factory

Color::rgb(int $r, int $g, int $b): static

Crear un color DeviceRGB. Los valores van de 0 a 255.

Color::cmyk(float $c, float $m, float $y, float $k): static

Crear un color DeviceCMYK. Los valores van de 0 a 100.

Color::gray(int $level): static

Crear un color DeviceGray. El nivel va de 0 (negro) a 255 (blanco).

Color::spot(string $name, Color $fallback, float $tint = 100): static

Crear un color spot (Separation) nombrado con un respaldo de color de proceso y porcentaje de tinta.

Color::hex(string $hex): static

Crear un color desde una cadena hex de 3 o 6 dígitos (con o sin '#').

Color::black(): static

Conveniencia: rgb(0, 0, 0).

Color::white(): static

Conveniencia: rgb(255, 255, 255).

Color::transparent(): static

Conveniencia: color totalmente transparente.

Propiedades

Propiedad	Tipo	Descripción
`$space`	`ColorSpace`	El enum de espacio de color (DeviceRGB, DeviceCMYK, DeviceGray, Separation)

Métodos

toRgbArray(): array

Retornar [r, g, b] con valores 0--255. Convierte desde CMYK o Gray si es necesario.

toCmykArray(): array

Retornar [c, m, y, k] con valores 0--100.

toHex(): string

Retornar una cadena hex de 6 dígitos (ej., 'ff6600').

withAlpha(float $alpha): static

Retornar un nuevo Color con el alpha dado (0.0--1.0).

equals(Color $other): bool

Comparar dos colores por igualdad de valor.

Ejemplo

php

use TcpdfNext\Graphics\Color;

$brand  = Color::hex('#0066CC');
$print  = Color::cmyk(100, 0, 0, 0);
$spot   = Color::spot('PANTONE 286 C', Color::cmyk(100, 66, 0, 2));
$faded  = $brand->withAlpha(0.5);
echo $brand->toHex(); // '0066cc'

Ver también

Resumen API -- Todos los paquetes de un vistazo
API de Document -- Métodos que aceptan estos value objects
Referencia de Enums -- ColorSpace, Orientation y otros enums relacionados
Guía de Value Objects -- Resumen conceptual y patrones avanzados

API de Value Objects ​

PageSize ​

Métodos factory (Serie ISO A) ​

Métodos factory (Serie ISO B) ​

Métodos factory (Norteamericanos) ​

Personalizado y búsqueda ​

Helpers de orientación ​

Propiedades ​

Métodos de conveniencia ​

Ejemplo ​

Margin ​

Métodos factory ​

Propiedades ​

Métodos modificadores ​

Métodos de cálculo ​

Ejemplo ​

Position ​

Métodos factory ​

Propiedades ​

Métodos ​

Ejemplo ​

Dimension ​

Métodos factory ​

Propiedades ​

Métodos ​

Ejemplo ​

Unit ​

Métodos de conversión ​

Ejemplo ​

Color ​

Métodos factory ​

Propiedades ​

Métodos ​

Ejemplo ​

Ver también ​

API de Value Objects

PageSize

Métodos factory (Serie ISO A)

Métodos factory (Serie ISO B)

Métodos factory (Norteamericanos)

Personalizado y búsqueda

Helpers de orientación

Propiedades

Métodos de conveniencia

Ejemplo

Margin

Métodos factory

Propiedades

Métodos modificadores

Métodos de cálculo

Ejemplo

Position

Métodos factory

Propiedades

Métodos

Ejemplo

Dimension

Métodos factory

Propiedades

Métodos

Ejemplo

Unit

Métodos de conversión

Ejemplo

Color

Métodos factory

Propiedades

Métodos

Ejemplo

Ver también