Value Objects API

All value objects in TCPDF-Next are immutable. Every "modifier" method returns a new instance, leaving the original unchanged. This eliminates a category of bugs caused by shared mutable state.

PageSize

Namespace: TcpdfNext\ValueObjects\PageSize

Represents the dimensions of a page. Internally all measurements are stored in PDF points (1/72 inch).

Factory Methods (ISO A Series)

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 (default)

PageSize::a5(): static

148 x 210 mm

PageSize::a6(): static

105 x 148 mm

Factory Methods (ISO B Series)

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

Factory Methods (North American)

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)

Custom & Lookup

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

Create a page size from millimetre dimensions.

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

Create a page size from point dimensions.

PageSize::fromName(string $name): static

Look up a standard page size by name (case-insensitive). Throws InvalidArgumentException for unknown names.

Orientation Helpers

landscape(): static

Return a new PageSize with width and height swapped so that width > height.

portrait(): static

Return a new PageSize with width and height swapped so that height > width.

Properties

Property	Type	Description
`$width`	`float`	Width in points
`$height`	`float`	Height in points
`$name`	`string`	Human-readable name (e.g., `'A4'`, `'Letter'`)

Convenience Methods

widthMm(): float

Return the width in millimetres.

heightMm(): float

Return the height in millimetres.

Example

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

Represents four-sided page margins. Internal storage is in PDF points.

Factory Methods

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

Create margins from millimetre values.

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

Create margins from point values.

Margin::uniform(float $value): static

All four sides equal (in points).

Margin::uniformMm(float $value): static

All four sides equal (in millimetres).

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

Symmetric margins (horizontal = left + right, vertical = top + bottom) in points.

Margin::zero(): static

All margins set to zero.

Properties

Property	Type	Description
`$top`	`float`	Top margin in points
`$right`	`float`	Right margin in points
`$bottom`	`float`	Bottom margin in points
`$left`	`float`	Left margin in points

Modifier Methods

withTop(float $value): static

Return a new Margin with the top value replaced (in points).

withRight(float $value): static

Return a new Margin with the right value replaced.

withBottom(float $value): static

Return a new Margin with the bottom value replaced.

withLeft(float $value): static

Return a new Margin with the left value replaced.

Calculation Methods

printableArea(PageSize $pageSize): Dimension

Return the printable Dimension (page size minus margins).

Example

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

An immutable x--y coordinate pair in PDF points.

Factory Methods

new Position(float $x, float $y)

Create from point values.

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

Create from millimetre values (converted to points internally).

Properties

Property	Type	Description
`$x`	`float`	Horizontal coordinate in points
`$y`	`float`	Vertical coordinate in points

Methods

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

Return a new Position shifted by (dx, dy) points.

xMm(): float

Return x in millimetres.

yMm(): float

Return y in millimetres.

Example

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

An immutable width--height pair in PDF points.

Factory Methods

new Dimension(float $width, float $height)

Create from point values.

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

Create from millimetre values.

Properties

Property	Type	Description
`$width`	`float`	Width in points
`$height`	`float`	Height in points

Methods

swap(): static

Return a new Dimension with width and height swapped.

widthMm(): float

Return width in millimetres.

heightMm(): float

Return height in millimetres.

area(): float

Return the area in square points.

Example

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

Static utility class for converting between measurement units. All conversions are based on the PDF standard of 72 points per inch.

Conversion Methods

Unit::mm(float $value): float

Convert millimetres to points. Alias for mmToPoints().

Unit::pt(float $value): float

Identity -- returns the value unchanged (for API consistency).

Unit::cm(float $value): float

Convert centimetres to points.

Unit::in(float $value): float

Convert inches to points (value x 72).

Unit::mmToPoints(float $mm): float

Convert millimetres to points (mm x 72 / 25.4).

Unit::pointsToMm(float $pt): float

Convert points to millimetres (pt x 25.4 / 72).

Unit::inchesToPoints(float $inches): float

Convert inches to points (inches x 72).

Unit::pointsToInches(float $pt): float

Convert points to inches (pt / 72).

Unit::cmToPoints(float $cm): float

Convert centimetres to points (cm x 72 / 2.54).

Unit::pointsToCm(float $pt): float

Convert points to centimetres (pt x 2.54 / 72).

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

General-purpose converter. Supported unit strings: 'mm', 'cm', 'in', 'pt'.

Example

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

Immutable color representation supporting multiple color spaces. Although Color lives in the Graphics package, it is used pervasively across the library (text color, draw color, fill color, bookmark color, annotation color).

Factory Methods

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

Create a DeviceRGB color. Values range from 0 to 255.

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

Create a DeviceCMYK color. Values range from 0 to 100.

Color::gray(int $level): static

Create a DeviceGray color. Level ranges from 0 (black) to 255 (white).

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

Create a named spot (Separation) color with a process-color fallback and tint percentage.

Color::hex(string $hex): static

Create a color from a 3- or 6-digit hex string (with or without '#').

Color::black(): static

Convenience: rgb(0, 0, 0).

Color::white(): static

Convenience: rgb(255, 255, 255).

Color::transparent(): static

Convenience: fully transparent color.

Properties

Property	Type	Description
`$space`	`ColorSpace`	The color space enum (DeviceRGB, DeviceCMYK, DeviceGray, Separation)

Methods

toRgbArray(): array

Return [r, g, b] with values 0--255. Converts from CMYK or Gray if needed.

toCmykArray(): array

Return [c, m, y, k] with values 0--100.

toHex(): string

Return a 6-digit hex string (e.g., 'ff6600').

withAlpha(float $alpha): static

Return a new Color with the given alpha (0.0--1.0).

equals(Color $other): bool

Compare two colors for value equality.

Example

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'

Value Objects API ​

PageSize ​

Factory Methods (ISO A Series) ​

Factory Methods (ISO B Series) ​

Factory Methods (North American) ​

Custom & Lookup ​

Orientation Helpers ​

Properties ​

Convenience Methods ​

Example ​

Margin ​

Factory Methods ​

Properties ​

Modifier Methods ​

Calculation Methods ​

Example ​

Position ​

Factory Methods ​

Properties ​

Methods ​

Example ​

Dimension ​

Factory Methods ​

Properties ​

Methods ​

Example ​

Unit ​

Conversion Methods ​

Example ​

Color ​

Factory Methods ​

Properties ​

Methods ​

Example ​

See Also ​

Value Objects API

PageSize

Factory Methods (ISO A Series)

Factory Methods (ISO B Series)

Factory Methods (North American)

Custom & Lookup

Orientation Helpers

Properties

Convenience Methods

Example

Margin

Factory Methods

Properties

Modifier Methods

Calculation Methods

Example

Position

Factory Methods

Properties

Methods

Example

Dimension

Factory Methods

Properties

Methods

Example

Unit

Conversion Methods

Example

Color

Factory Methods

Properties

Methods

Example

See Also