Шаблоны (XObjects)

PDF Form XObjects — в TCPDF-Next называемые шаблонами — позволяют записать блок контента один раз и поместить его на любое количество страниц. Это идеально подходит для колонтитулов, водяных знаков, логотипов и любых повторяющихся элементов.

Все методы возвращают static, поэтому каждый вызов может быть объединён в цепочку (кроме startTemplate(), который возвращает ID шаблона).

Краткий справочник

Метод	Назначение
startTemplate()	Начать запись шаблона; возвращает ID шаблона
endTemplate()	Остановить запись
printTemplate()	Разместить записанный шаблон на текущей странице

Базовый пример

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create();

// Создание переиспользуемого шаблона заголовка
$tpl = $pdf->startTemplate(190, 20);
$pdf->setFont('Helvetica', 'B', 14)
    ->setTextColor(255, 102, 0)
    ->cell(0, 10, 'ACME Corp — Confidential', align: 'C')
    ->line(0, 18, 190, 18);
$pdf->endTemplate();

// Использование шаблона на нескольких страницах
$pdf->addPage()
    ->printTemplate($tpl, 10, 10)
    ->setFont('Helvetica', '', 12)
    ->setY(35)
    ->cell(0, 10, 'Page 1 content', newLine: true)

    ->addPage()
    ->printTemplate($tpl, 10, 10)
    ->setY(35)
    ->cell(0, 10, 'Page 2 content', newLine: true);

startTemplate()

$tpl = $pdf->startTemplate(float $w = 0, float $h = 0): int

Начинает запись нового шаблона. Все операции рисования после этого вызова фиксируются в шаблоне, а не рендерятся непосредственно на странице.

Параметр	Тип	Описание
$w	float	Ширина шаблона в пользовательских единицах (0 = ширина страницы)
$h	float	Высота шаблона в пользовательских единицах (0 = высота страницы)

Возвращает целочисленный ID шаблона для дальнейшего использования.

WARNING

Не вызывайте addPage() во время записи шаблона. Шаблоны фиксируют контент в пределах фиксированной ограничивающей рамки — это не страницы.

endTemplate()

Останавливает запись и финализирует шаблон. Контент, нарисованный после этого вызова, снова направляется на текущую страницу.

printTemplate()

$pdf->printTemplate(int $id, float $x, float $y, float $w = 0, float $h = 0): static

Размещает ранее записанный шаблон на текущей странице в указанной позиции.

Параметр	Тип	Описание
$id	int	ID шаблона, возвращённый startTemplate()
$x	float	Позиция X на странице
$y	float	Позиция Y на странице
$w	float	Ширина отображения (0 = оригинальная ширина шаблона)
$h	float	Высота отображения (0 = оригинальная высота шаблона)

Один и тот же шаблон можно размещать в разных размерах, варьируя $w и $h. Контент шаблона масштабируется для соответствия.

Сценарии использования

Повторяющийся колонтитул

$header = $pdf->startTemplate(190, 15);
$pdf->setFont('Helvetica', 'B', 10)
    ->cell(95, 10, 'Company Name', align: 'L')
    ->cell(95, 10, date('Y-m-d'), align: 'R');
$pdf->endTemplate();

for ($i = 1; $i <= 5; $i++) {
    $pdf->addPage()
        ->printTemplate($header, 10, 10)
        ->setY(30)
        ->cell(0, 10, "Content for page {$i}", newLine: true);
}

Масштабируемый логотип

Размещение одного шаблона в разных размерах:

$logo = $pdf->startTemplate(60, 20);
$pdf->image('/path/to/logo.png', 0, 0, 60, 20);
$pdf->endTemplate();

$pdf->addPage()
    ->printTemplate($logo, 10, 10, 60, 20)   // Полный размер
    ->printTemplate($logo, 10, 40, 30, 10);   // Половина размера

Советы

• Шаблоны хранятся как PDF Form XObjects — контент определяется один раз независимо от количества размещений, сохраняя небольшой размер файла.
• Шаблоны могут содержать любой рисуемый контент: текст, изображения, фигуры и даже другие шаблоны.
• Система координат внутри шаблона начинается с (0, 0) в левом верхнем углу ограничивающей рамки.