API объектов значений
Все объекты значений в TCPDF-Next неизменяемы. Каждый «модифицирующий» метод возвращает новый экземпляр, оставляя оригинал без изменений. Это устраняет категорию ошибок, вызванных общим мутабельным состоянием.
PageSize
Namespace: TcpdfNext\ValueObjects\PageSize
Представляет размеры страницы. Внутренне все измерения хранятся в пунктах PDF (1/72 дюйма).
Фабричные методы (серия ISO A)
PageSize::a0(): static
841 x 1189 мм
PageSize::a1(): static
594 x 841 мм
PageSize::a2(): static
420 x 594 мм
PageSize::a3(): static
297 x 420 мм
PageSize::a4(): static
210 x 297 мм (по умолчанию)
PageSize::a5(): static
148 x 210 мм
PageSize::a6(): static
105 x 148 мм
Фабричные методы (серия ISO B)
PageSize::b0(): static
1000 x 1414 мм
PageSize::b1(): static
707 x 1000 мм
PageSize::b2(): static
500 x 707 мм
PageSize::b3(): static
353 x 500 мм
PageSize::b4(): static
250 x 353 мм
PageSize::b5(): static
176 x 250 мм
Фабричные методы (североамериканские)
PageSize::letter(): static
8.5 x 11 дюймов (215.9 x 279.4 мм)
PageSize::legal(): static
8.5 x 14 дюймов (215.9 x 355.6 мм)
PageSize::tabloid(): static
11 x 17 дюймов (279.4 x 431.8 мм)
Пользовательские и поиск
PageSize::fromMm(float $width, float $height, string $name = 'Custom'): static
Создать размер страницы из миллиметровых размеров.
PageSize::fromPoints(float $width, float $height, string $name = 'Custom'): static
Создать размер страницы из размеров в пунктах.
PageSize::fromName(string $name): static
Найти стандартный размер страницы по имени (регистронезависимо). Выбрасывает InvalidArgumentException для неизвестных имён.
Хелперы ориентации
landscape(): static
Вернуть новый PageSize с шириной и высотой, поменянными местами, так что ширина > высоты.
portrait(): static
Вернуть новый PageSize с шириной и высотой, поменянными местами, так что высота > ширины.
Свойства
| Свойство | Тип | Описание |
|---|---|---|
$width | float | Ширина в пунктах |
$height | float | Высота в пунктах |
$name | string | Человекочитаемое имя (например, 'A4', 'Letter') |
Удобные методы
widthMm(): float
Вернуть ширину в миллиметрах.
heightMm(): float
Вернуть высоту в миллиметрах.
Пример
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
Представляет четырёхсторонние поля страницы. Внутреннее хранение в пунктах PDF.
Фабричные методы
Margin::mm(float $top, float $right, float $bottom, float $left): static
Создать поля из миллиметровых значений.
Margin::pt(float $top, float $right, float $bottom, float $left): static
Создать поля из значений в пунктах.
Margin::uniform(float $value): static
Все четыре стороны одинаковы (в пунктах).
Margin::uniformMm(float $value): static
Все четыре стороны одинаковы (в миллиметрах).
Margin::symmetric(float $horizontal, float $vertical): static
Симметричные поля (horizontal = лево + право, vertical = верх + низ) в пунктах.
Margin::zero(): static
Все поля установлены в ноль.
Свойства
| Свойство | Тип | Описание |
|---|---|---|
$top | float | Верхнее поле в пунктах |
$right | float | Правое поле в пунктах |
$bottom | float | Нижнее поле в пунктах |
$left | float | Левое поле в пунктах |
Модифицирующие методы
withTop(float $value): static
Вернуть новый Margin с заменённым значением верхнего поля (в пунктах).
withRight(float $value): static
Вернуть новый Margin с заменённым значением правого поля.
withBottom(float $value): static
Вернуть новый Margin с заменённым значением нижнего поля.
withLeft(float $value): static
Вернуть новый Margin с заменённым значением левого поля.
Методы вычислений
printableArea(PageSize $pageSize): Dimension
Вернуть печатную область Dimension (размер страницы минус поля).
Пример
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.0Position
Namespace: TcpdfNext\ValueObjects\Position
Неизменяемая пара координат x--y в пунктах PDF.
Фабричные методы
new Position(float $x, float $y)
Создать из значений в пунктах.
Position::mm(float $x, float $y): static
Создать из миллиметровых значений (преобразуются в пункты внутренне).
Свойства
| Свойство | Тип | Описание |
|---|---|---|
$x | float | Горизонтальная координата в пунктах |
$y | float | Вертикальная координата в пунктах |
Методы
translate(float $dx, float $dy): static
Вернуть новый Position, смещённый на (dx, dy) пунктов.
xMm(): float
Вернуть x в миллиметрах.
yMm(): float
Вернуть y в миллиметрах.
Пример
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.9Dimension
Namespace: TcpdfNext\ValueObjects\Dimension
Неизменяемая пара ширина--высота в пунктах PDF.
Фабричные методы
new Dimension(float $width, float $height)
Создать из значений в пунктах.
Dimension::mm(float $width, float $height): static
Создать из миллиметровых значений.
Свойства
| Свойство | Тип | Описание |
|---|---|---|
$width | float | Ширина в пунктах |
$height | float | Высота в пунктах |
Методы
swap(): static
Вернуть новый Dimension с поменянными местами шириной и высотой.
widthMm(): float
Вернуть ширину в миллиметрах.
heightMm(): float
Вернуть высоту в миллиметрах.
area(): float
Вернуть площадь в квадратных пунктах.
Пример
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 equivalentUnit
Namespace: TcpdfNext\ValueObjects\Unit
Статический утилитарный класс для преобразования между единицами измерения. Все преобразования основаны на стандарте PDF — 72 пункта на дюйм.
Методы преобразования
Unit::mm(float $value): float
Преобразовать миллиметры в пункты. Алиас для mmToPoints().
Unit::pt(float $value): float
Тождественное преобразование — возвращает значение без изменений (для единообразия API).
Unit::cm(float $value): float
Преобразовать сантиметры в пункты.
Unit::in(float $value): float
Преобразовать дюймы в пункты (значение x 72).
Unit::mmToPoints(float $mm): float
Преобразовать миллиметры в пункты (мм x 72 / 25.4).
Unit::pointsToMm(float $pt): float
Преобразовать пункты в миллиметры (пт x 25.4 / 72).
Unit::inchesToPoints(float $inches): float
Преобразовать дюймы в пункты (дюймы x 72).
Unit::pointsToInches(float $pt): float
Преобразовать пункты в дюймы (пт / 72).
Unit::cmToPoints(float $cm): float
Преобразовать сантиметры в пункты (см x 72 / 2.54).
Unit::pointsToCm(float $pt): float
Преобразовать пункты в сантиметры (пт x 2.54 / 72).
Unit::convert(float $value, string $from, string $to): float
Универсальный конвертер. Поддерживаемые строки единиц: 'mm', 'cm', 'in', 'pt'.
Пример
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.4Color
Namespace: TcpdfNext\Graphics\Color
Неизменяемое представление цвета, поддерживающее множественные цветовые пространства. Хотя Color находится в пакете Graphics, он повсеместно используется по всей библиотеке (цвет текста, цвет обводки, цвет заливки, цвет закладок, цвет аннотаций).
Фабричные методы
Color::rgb(int $r, int $g, int $b): static
Создать цвет DeviceRGB. Значения от 0 до 255.
Color::cmyk(float $c, float $m, float $y, float $k): static
Создать цвет DeviceCMYK. Значения от 0 до 100.
Color::gray(int $level): static
Создать цвет DeviceGray. Уровень от 0 (чёрный) до 255 (белый).
Color::spot(string $name, Color $fallback, float $tint = 100): static
Создать именованный плашечный (Separation) цвет с запасным процессным цветом и процентом тонирования.
Color::hex(string $hex): static
Создать цвет из 3- или 6-значной hex-строки (с '#' или без).
Color::black(): static
Удобный метод: rgb(0, 0, 0).
Color::white(): static
Удобный метод: rgb(255, 255, 255).
Color::transparent(): static
Удобный метод: полностью прозрачный цвет.
Свойства
| Свойство | Тип | Описание |
|---|---|---|
$space | ColorSpace | Enum цветового пространства (DeviceRGB, DeviceCMYK, DeviceGray, Separation) |
Методы
toRgbArray(): array
Вернуть [r, g, b] со значениями 0--255. Преобразует из CMYK или Gray при необходимости.
toCmykArray(): array
Вернуть [c, m, y, k] со значениями 0--100.
toHex(): string
Вернуть 6-значную hex-строку (например, 'ff6600').
withAlpha(float $alpha): static
Вернуть новый Color с заданной альфой (0.0--1.0).
equals(Color $other): bool
Сравнить два цвета на равенство значений.
Пример
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'См. также
- Обзор API -- Все пакеты одним взглядом
- API документа -- Методы, принимающие эти объекты значений
- Справочник Enums -- ColorSpace, Orientation и другие связанные enum-ы
- Руководство по объектам значений -- Концептуальный обзор и продвинутые паттерны