API de Value Objects

Todos os value objects no TCPDF-Next são imutáveis. Cada método "modificador" retorna uma nova instância, deixando o original inalterado. Isso elimina uma categoria de bugs causados por estado mutável compartilhado.

PageSize

Namespace: TcpdfNext\ValueObjects\PageSize

Representa as dimensões de uma página. Internamente todas as medidas são armazenadas em pontos PDF (1/72 polegada).

Métodos de Fábrica (Série 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 (padrão)

PageSize::a5(): static

148 x 210 mm

PageSize::a6(): static

105 x 148 mm

Métodos de Fábrica (Série 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 de Fábrica (Norte-Americanos)

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 e Busca

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

Criar um tamanho de página a partir de dimensões em milímetros.

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

Criar um tamanho de página a partir de dimensões em pontos.

PageSize::fromName(string $name): static

Buscar um tamanho de página padrão pelo nome (case-insensitive). Lança InvalidArgumentException para nomes desconhecidos.

Auxiliares de Orientação

landscape(): static

Retornar um novo PageSize com largura e altura trocadas para que largura > altura.

portrait(): static

Retornar um novo PageSize com largura e altura trocadas para que altura > largura.

Propriedades

Propriedade	Tipo	Descrição
`$width`	`float`	Largura em pontos
`$height`	`float`	Altura em pontos
`$name`	`string`	Nome legível (ex: `'A4'`, `'Letter'`)

Métodos de Conveniência

widthMm(): float

Retornar a largura em milímetros.

heightMm(): float

Retornar a altura em milímetros.

Exemplo

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 margens de página de quatro lados. Armazenamento interno em pontos PDF.

Métodos de Fábrica

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

Criar margens a partir de valores em milímetros.

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

Criar margens a partir de valores em pontos.

Margin::uniform(float $value): static

Todos os quatro lados iguais (em pontos).

Margin::uniformMm(float $value): static

Todos os quatro lados iguais (em milímetros).

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

Margens simétricas (horizontal = esquerda + direita, vertical = topo + base) em pontos.

Margin::zero(): static

Todas as margens definidas como zero.

Propriedades

Propriedade	Tipo	Descrição
`$top`	`float`	Margem superior em pontos
`$right`	`float`	Margem direita em pontos
`$bottom`	`float`	Margem inferior em pontos
`$left`	`float`	Margem esquerda em pontos

Métodos Modificadores

withTop(float $value): static

Retornar uma nova Margin com o valor do topo substituído (em pontos).

withRight(float $value): static

Retornar uma nova Margin com o valor da direita substituído.

withBottom(float $value): static

Retornar uma nova Margin com o valor da base substituído.

withLeft(float $value): static

Retornar uma nova Margin com o valor da esquerda substituído.

Métodos de Cálculo

printableArea(PageSize $pageSize): Dimension

Retornar a Dimension imprimível (tamanho da página menos margens).

Exemplo

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

Um par de coordenadas x--y imutável em pontos PDF.

Métodos de Fábrica

new Position(float $x, float $y)

Criar a partir de valores em pontos.

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

Criar a partir de valores em milímetros (convertidos para pontos internamente).

Propriedades

Propriedade	Tipo	Descrição
`$x`	`float`	Coordenada horizontal em pontos
`$y`	`float`	Coordenada vertical em pontos

Métodos

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

Retornar uma nova Position deslocada por (dx, dy) pontos.

xMm(): float

Retornar x em milímetros.

yMm(): float

Retornar y em milímetros.

Exemplo

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

Um par largura--altura imutável em pontos PDF.

Métodos de Fábrica

new Dimension(float $width, float $height)

Criar a partir de valores em pontos.

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

Criar a partir de valores em milímetros.

Propriedades

Propriedade	Tipo	Descrição
`$width`	`float`	Largura em pontos
`$height`	`float`	Altura em pontos

Métodos

swap(): static

Retornar uma nova Dimension com largura e altura trocadas.

widthMm(): float

Retornar largura em milímetros.

heightMm(): float

Retornar altura em milímetros.

area(): float

Retornar a área em pontos quadrados.

Exemplo

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 equivalente

Unit

Namespace: TcpdfNext\ValueObjects\Unit

Classe utilitária estática para conversão entre unidades de medida. Todas as conversões são baseadas no padrão PDF de 72 pontos por polegada.

Métodos de Conversão

Unit::mm(float $value): float

Converter milímetros para pontos. Alias para mmToPoints().

Unit::pt(float $value): float

Identidade -- retorna o valor inalterado (para consistência da API).

Unit::cm(float $value): float

Converter centímetros para pontos.

Unit::in(float $value): float

Converter polegadas para pontos (valor x 72).

Unit::mmToPoints(float $mm): float

Converter milímetros para pontos (mm x 72 / 25.4).

Unit::pointsToMm(float $pt): float

Converter pontos para milímetros (pt x 25.4 / 72).

Unit::inchesToPoints(float $inches): float

Converter polegadas para pontos (inches x 72).

Unit::pointsToInches(float $pt): float

Converter pontos para polegadas (pt / 72).

Unit::cmToPoints(float $cm): float

Converter centímetros para pontos (cm x 72 / 2.54).

Unit::pointsToCm(float $pt): float

Converter pontos para centímetros (pt x 2.54 / 72).

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

Conversor de propósito geral. Strings de unidade suportadas: 'mm', 'cm', 'in', 'pt'.

Exemplo

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

Representação de cor imutável suportando múltiplos espaços de cor. Embora Color resida no pacote Graphics, é usado de forma pervasiva em toda a biblioteca (cor de texto, cor de traço, cor de preenchimento, cor de marcador, cor de anotação).

Métodos de Fábrica

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

Criar uma cor DeviceRGB. Valores variam de 0 a 255.

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

Criar uma cor DeviceCMYK. Valores variam de 0 a 100.

Color::gray(int $level): static

Criar uma cor DeviceGray. Level varia de 0 (preto) a 255 (branco).

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

Criar uma cor spot (Separation) nomeada com fallback em cor de processo e porcentagem de tinta.

Color::hex(string $hex): static

Criar uma cor a partir de uma string hex de 3 ou 6 dígitos (com ou sem '#').

Color::black(): static

Conveniência: rgb(0, 0, 0).

Color::white(): static

Conveniência: rgb(255, 255, 255).

Color::transparent(): static

Conveniência: cor totalmente transparente.

Propriedades

Propriedade	Tipo	Descrição
`$space`	`ColorSpace`	O enum do espaço de cor (DeviceRGB, DeviceCMYK, DeviceGray, Separation)

Métodos

toRgbArray(): array

Retornar [r, g, b] com valores 0--255. Converte de CMYK ou Gray se necessário.

toCmykArray(): array

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

toHex(): string

Retornar uma string hex de 6 dígitos (ex: 'ff6600').

withAlpha(float $alpha): static

Retornar uma nova Color com o alfa fornecido (0.0--1.0).

equals(Color $other): bool

Comparar duas cores para igualdade de valor.

Exemplo

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'

Veja Também

Visão Geral da API -- Todos os pacotes em resumo
API do Document -- Métodos que aceitam esses value objects
Referência de Enums -- ColorSpace, Orientation e outros enums relacionados
Guia de Value Objects -- Visão conceitual e padrões avançados

API de Value Objects ​

PageSize ​

Métodos de Fábrica (Série ISO A) ​

Métodos de Fábrica (Série ISO B) ​

Métodos de Fábrica (Norte-Americanos) ​

Personalizado e Busca ​

Auxiliares de Orientação ​

Propriedades ​

Métodos de Conveniência ​

Exemplo ​

Margin ​

Métodos de Fábrica ​

Propriedades ​

Métodos Modificadores ​

Métodos de Cálculo ​

Exemplo ​

Position ​

Métodos de Fábrica ​

Propriedades ​

Métodos ​

Exemplo ​

Dimension ​

Métodos de Fábrica ​

Propriedades ​

Métodos ​

Exemplo ​

Unit ​

Métodos de Conversão ​

Exemplo ​

Color ​

Métodos de Fábrica ​

Propriedades ​

Métodos ​

Exemplo ​

Veja Também ​

API de Value Objects

PageSize

Métodos de Fábrica (Série ISO A)

Métodos de Fábrica (Série ISO B)

Métodos de Fábrica (Norte-Americanos)

Personalizado e Busca

Auxiliares de Orientação

Propriedades

Métodos de Conveniência

Exemplo

Margin

Métodos de Fábrica

Propriedades

Métodos Modificadores

Métodos de Cálculo

Exemplo

Position

Métodos de Fábrica

Propriedades

Métodos

Exemplo

Dimension

Métodos de Fábrica

Propriedades

Métodos

Exemplo

Unit

Métodos de Conversão

Exemplo

Color

Métodos de Fábrica

Propriedades

Métodos

Exemplo

Veja Também